Add Calendar controls: DHX-2734

docs/calendar/api/api_overview.md

@@ -35,6 +35,7 @@ description: You can explore the API of Calendar in the documentation of the DHT
 
 | Name                                              | Description                                              |
 | ------------------------------------------------- | -------------------------------------------------------- |
+| [](calendar/api/calendar_controls_config.md)      | @getshort(calendar/api/calendar_controls_config.md)      |
 | [](calendar/api/calendar_css_config.md)           | @getshort(calendar/api/calendar_css_config.md)           |
 | [](calendar/api/calendar_date_config.md)          | @getshort(calendar/api/calendar_date_config.md)          |
 | [](calendar/api/calendar_dateformat_config.md)    | @getshort(calendar/api/calendar_dateformat_config.md)    |

docs/calendar/api/calendar_controls_config.md

@@ -0,0 +1,115 @@
+---
+sidebar_label: controls
+title: JavaScript Calendar - controls Config 
+description: The controls property adds a toolbar with the Clear, Today, and Timepicker controls to the DHTMLX JavaScript Calendar. Learn how to render the default set or list the controls in your own order, and check the code examples in the DHTMLX Suite docs.
+---
+
+# controls
+
+@short: Optional. Adds a toolbar with the Clear, Today, and Timepicker controls to the calendar
+
+#### Usage
+
+~~~ts
+type TCalendarControls = "clear" | "today" | "timepicker" | "spacer";
+
+export interface ICalendarConfig {
+  // ... existing config
+  timePicker?: boolean;
+  controls?: boolean | TCalendarControls[];
+}
+~~~
+
+@default: false
+
+@descr:
+
+The property takes either a boolean value or an array of control names:
+
+<table>
+    <tbody>
+        <tr>
+            <td><b>true</b></td>
+            <td>renders the default set of controls, which is equal to <b>["spacer", "clear", "today"]</b></td>
+        </tr>
+        <tr>
+            <td><b>false</b></td>
+            <td>the calendar renders no controls and adds no related markup to the DOM. The same applies when you do not specify the property. A timepicker that the <code>timePicker</code> property enables still appears</td>
+        </tr>
+        <tr>
+            <td><b>array</b></td>
+            <td>renders the listed controls in the order you specify</td>
+        </tr>
+    </tbody>
+</table>
+
+The array can include the following controls:
+
+<table>
+    <tbody>
+        <tr>
+            <td><b>"clear"</b></td>
+            <td>resets the selected date</td>
+        </tr>
+        <tr>
+            <td><b>"today"</b></td>
+            <td>sets the selected date to today and navigates the calendar to the current month</td>
+        </tr>
+        <tr>
+            <td><b>"timepicker"</b></td>
+            <td>shows the current time and opens the time selection view. It is equivalent to setting <code>timePicker: true</code></td>
+        </tr>
+        <tr>
+            <td><b>"spacer"</b></td>
+            <td>fills in the empty space between the elements of the toolbar</td>
+        </tr>
+    </tbody>
+</table>
+
+The names of controls are case-insensitive, so the calendar treats **"today"**, **"Today"** and **"TODAY"** as the same control and ignores unknown names.
+
+:::note
+Listing the **"Timepicker"** control enables the [`timePicker`](calendar/api/calendar_timepicker_config.md) property as well, so the calendar renders the timepicker once even if you use both ways.
+:::
+
+#### Example
+
+~~~jsx
+// renders the default set of controls
+const calendar = new dhx.Calendar("calendar_container", {
+    controls: true
+});
+
+// renders the "Today" button only
+const calendar = new dhx.Calendar("calendar_container", {
+    controls: ["today"]
+});
+
+// renders the timepicker together with the default set of controls
+const calendar = new dhx.Calendar("calendar_container", {
+    timePicker: true,
+    controls: true
+});
+
+// adds the timepicker via the controls array
+const calendar = new dhx.Calendar("calendar_container", {
+    controls: ["timepicker", "spacer", "clear", "today"]
+});
+
+// renders the timepicker once, though it is enabled in two ways
+const calendar = new dhx.Calendar("calendar_container", {
+    timePicker: true,
+    controls: ["timepicker", "today"]
+});
+
+// the names of controls are case-insensitive
+const calendar = new dhx.Calendar("calendar_container", {
+    controls: ["TODAY", "Clear", "Spacer"]
+});
+~~~
+
+**Related sample**: [Calendar. Controls](https://snippet.dhtmlx.com/guakfjw0?mode=wide)
+
+**Related article**: [Controls](calendar/configuring.md#controls)
+
+@changelog: added in v9.4

docs/calendar/api/calendar_timepicker_config.md

@@ -20,8 +20,14 @@ const calendar = new dhx.Calendar("calendar_container", {
 @descr:
 **Related sample**: [Calendar. Timepicker In Calendar](https://snippet.dhtmlx.com/jkbfb202)
 
-You can define the format of displaying time in a timepicker via the [](calendar/api/calendar_timeformat_config.md) property.
+You can define the format of displaying time in a timepicker via the [`timeFormat`](calendar/api/calendar_timeformat_config.md) property.
 
-[comment]: # (@relatedapi:calendar/api/calendar_timeformat_config.md)
+You can also add a timepicker as the **"Timepicker"** entry of the [`controls`](calendar/api/calendar_controls_config.md) property, and if you use both ways at once, the calendar renders it once.
 
-[comment]: # (@related: calendar/how_to_start.md#initialize-calendar calendar/configuring.md#timepicker)
+**Related API**: 
+- [`timeFormat`](calendar/api/calendar_timeformat_config.md)
+- [`controls`](calendar/api/calendar_controls_config.md)
+
+**Related articles**: 
+- [Initialize Calendar](calendar/how_to_start.md#initialize-calendar)
+- [Timepicker](calendar/configuring.md#timepicker)

docs/calendar/configuring.md

@@ -42,6 +42,59 @@ const calendar = new dhx.Calendar("calendar_container", {
 
 You can also show the calendar in one of the modes using the [](calendar/api/calendar_showdate_method.md) method.
 
+## Controls
+
+You can add a toolbar with quick actions to the calendar via the [`controls`](calendar/api/calendar_controls_config.md) property. By default, the calendar does not render the toolbar.
+
+**Related sample**: [Calendar. Controls](https://snippet.dhtmlx.com/guakfjw0?mode=wide)
+
+### Adding controls
+
+To render the default set of controls, set the property to *true*:
+
+~~~jsx
+const calendar = new dhx.Calendar("calendar_container", {
+    controls: true // the same as controls: ["spacer", "clear", "today"]
+});
+~~~
+
+To choose the controls and their order, pass an array of control names. The names are case-insensitive, and the calendar ignores unknown names:
+
+~~~jsx
+const calendar = new dhx.Calendar("calendar_container", {
+    controls: ["clear", "spacer", "today", "timepicker"]
+});
+~~~
+
+### Available controls
+
+You can use the following controls:
+
+- **"Clear"** - resets the selected date
+- **"Today"** - sets the selected date to today and navigates the calendar to the current month
+- **"Timepicker"** - shows the current time and opens the time selection view, which is equivalent to setting `timePicker: true`
+- **"Spacer"** - fills in the empty space between the elements of the toolbar
+
+The calendar renders the **"Clear"**, **"Today"** and **"Timepicker"** controls as buttons with the **"link"** view, the same look that the [`view`](toolbar/api/api_button_properties.md) property gives to a [Toolbar](toolbar/button.md) or [Form](form/button.md) button. The **"Spacer"** control is a layout element that works like the [Toolbar spacer](toolbar/spacer.md).
+
+### Timepicker as a control
+
+You can add a timepicker either through the `controls` array or through the [`timePicker`](calendar/api/calendar_timepicker_config.md) property. Listing the **"Timepicker"** control enables the `timePicker` property as well, which keeps the time selection view available and renders the timepicker once even if you use both ways.
+
+### Position of the controls
+
+The calendar places the controls in the toolbar from left to right in the order you list them in the array, and puts a timepicker that the [`timePicker`](calendar/api/calendar_timepicker_config.md) property enables at the beginning of the toolbar.
+
+A single control, except for a spacer, stretches to the full width of the calendar. If the toolbar contains several controls and no spacer, the controls keep their own width and line up on the left. Use the **"Spacer"** control to push the controls that follow it to the right edge.
+
+You can combine the controls in different ways to get the desired layout of the toolbar. For example:
+
+![Calendars with different sets of controls showing how a spacer and a timepicker affect the position of the controls in DHTMLX Suite](/img/calendar/controls.png)
+
+### Labels of the controls
+
+The **"Clear"** and **"Today"** buttons take their labels from the calendar locale, where you can translate them, see the [Localization](calendar/localizing_calendar.md) article for details.
+
 ## Date format
 
 There is a possibility to specify the format of dates in the calendar via the [](calendar/api/calendar_dateformat_config.md) property. The default format is "%d/%m/%y". 
@@ -238,7 +291,7 @@ const calendar = new dhx.Calendar("calendar_container", {
 
 ## Timepicker
 
-You can add a timepicker into a calendar by enabling the [](calendar/api/calendar_timepicker_config.md) property. By default, a timepicker uses the 24-hour format.
+You can add a timepicker into a calendar by enabling the [](calendar/api/calendar_timepicker_config.md) property. You can also add the timepicker as the **"Timepicker"** entry of the [`controls`](calendar/api/calendar_controls_config.md) property. By default, a timepicker uses the 24-hour format.
 You can change it to the 12-hour format via the [](calendar/api/calendar_timeformat_config.md) property. It accepts either 12 or 24 value to select the desired time format.
 
 ~~~js

docs/calendar/features.md

@@ -38,6 +38,7 @@ In this section you can discover how to configure Calendar.
 | Topic                                                                          | Description                                                                                                                                 |
 | :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
 | [Calendar modes](calendar/configuring.md#calendar-modes)                               | Learn how initialize Calendar in different modes (calendar, month, year) ([Example](https://snippet.dhtmlx.com/n9q0tc0q))                   |
+| [Controls](calendar/configuring.md#controls)                                           | Learn how to add a toolbar with the Clear, Today and Timepicker controls ([Example](https://snippet.dhtmlx.com/guakfjw0?mode=wide))         |
 | [Showing tooltips](calendar/operating_calendar.md#showing-tooltips)                    | Learn how to show tooltips in Calendar ([Example 1](https://snippet.dhtmlx.com/t4jy4wrr), [Example 2](https://snippet.dhtmlx.com/jwx0barf)) |
 | [Start of the week](calendar/configuring.md#start-of-the-week)                         | Learn how to change the starting day of the week ([Example](https://snippet.dhtmlx.com/kaxmurh9))                                           |
 | [Timepicker in Calendar](calendar/configuring.md#timepicker)                           | Learn how to add a timepicker into Calendar ([Example](https://snippet.dhtmlx.com/jkbfb202))                                                |

docs/calendar/localizing_calendar.md

@@ -14,7 +14,7 @@ You can apply different languages to the interface of dhtmlxCalendar. You just n
 
 The default locale for Calendar looks like this:
 
-~~~js
+~~~jsx
 const en = {
     // short names of months
     monthsShort: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", 
@@ -26,17 +26,22 @@ const en = {
     daysShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
     // full names of days
     days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", 
-                "Friday", "Saturday"]
+                "Friday", "Saturday"],
+    // label of the Cancel button of the month and year views
+    cancel: "Cancel",
+    // labels of the calendar controls
+    today: "Today",
+    clear: "Clear"
 };
 ~~~
 
 ## Custom locale
 
 To use a different locale, your need to:
 
-- define necessary language settings: provide full and short names of months, as well as full and short names of days of a week:
+- define necessary language settings: provide full and short names of months, full and short names of days of a week, and the labels of the buttons, including the ones of the [`controls`](calendar/api/calendar_controls_config.md), if you use them:
 
-~~~js
+~~~jsx
 const de = {
     // short names of months
     monthsShort: ["Jan", "Feb", "Mär", "Apr", "Mai", "Jun", 
@@ -48,15 +53,24 @@ const de = {
     daysShort: ["Son", "Mon", "Die", "Mit", "Don", "Fre", "Sam"],
     // full names of days
     days: ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", 
-                "Freitag", "Samstag"]
+                "Freitag", "Samstag"],
+    // label of the Cancel button of the month and year views
+    cancel: "Abbrechen",
+    // labels of the calendar controls
+    today: "Heute",
+    clear: "Löschen"
 };
 ~~~
 
-- apply the language settings by calling the **dhx.i18n.setLocale()** method before Calendar initialization:
+- apply the language settings by calling the `dhx.i18n.setLocale()` method before Calendar initialization:
 
-~~~js
+~~~jsx
 dhx.i18n.setLocale("calendar", de);
 const calendar = new dhx.Calendar("calendar_container");
 ~~~
 
+The `cancel`, `today` and `clear` labels are optional. If a custom locale does not specify them, the calendar applies the default values.
+
+The **Save** button of the timepicker is not a part of the calendar locale. The `save` entry of the [Timepicker locale](timepicker/localization.md) defines its label.
+
 **Related sample**: [Calendar. Localization](https://snippet.dhtmlx.com/tn40a0w8)

docs/colorpicker/localizing_colorpicker.md

@@ -41,7 +41,7 @@ const de = {
 - apply the language settings by calling the **dhx.i18n.setLocale()** method before Colorpicker initialization:
 
 ~~~js
-dhx.i18n.setLocale("colorpicker_container", de);
+dhx.i18n.setLocale("colorpicker", de);
 const colorpicker = new dhx.Colorpicker("colorpicker_container");
 ~~~
 

docs/combobox/localization.md

@@ -45,7 +45,7 @@ const de = {
 - apply the language settings by calling the **dhx.i18n.setLocale()** method before Combobox initialization:
 
 ~~~js
-dhx.i18n.setLocale("combo_container", de);
+dhx.i18n.setLocale("combobox", de);
 const combo = new dhx.Combobox("combo_container");
 ~~~
 

docs/timepicker/features.md

@@ -10,16 +10,17 @@ This page contains structured information that will help you to start working wi
 
 ## How to start with DHTMLX Timepicker
 
-In this section you can find out the ways of Timepicker initialization, and learn how to integrate Timepicker into your applications.
+In this section you can find out the ways of Timepicker initialization and localization, and learn how to integrate Timepicker into your applications.
 
-### Initialization
+### Initialization and localization
 
 | Topic                                                                                                                  | Description                                                                                      |
 | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | [Basic initialization](timepicker/initialization.md)                                                                             | Learn how to initialize a Timepicker ([Example](https://snippet.dhtmlx.com/3d5u4cxx))            |
 | Timepicker inside a Popup                                                                                                | Learn how to initialize a Timepicker in a popup ([Example](https://snippet.dhtmlx.com/7x6hlbqx)) |
 | [Timepicker in Calendar](https://snippet.dhtmlx.com/jkbfb202)                                                          | Check the example of Timepicker as a part of Calendar                                            |
 | Timepicker in Form: [example 1](https://snippet.dhtmlx.com/4k3o8p7b), [example 2](https://snippet.dhtmlx.com/ikyyekxq) | Check the examples of Timepicker as Form controls                                                |
+| [Localization](timepicker/localization.md)                                                                             | Learn how to localize a Timepicker                                                               |
 
 
 ### Integration

docs/timepicker/index.md

@@ -30,6 +30,7 @@ You can check the following page to learn how to build a full-featured DHTMLX Ti
 
 - [](timepicker/initialization.md)
 - [](timepicker/configuration.md)
+- [](timepicker/localization.md)
 - [](timepicker/usage.md)
 - [](timepicker/customization.md)
 - [](timepicker/handling_events.md)

docs/timepicker/localization.md

@@ -0,0 +1,54 @@
+---
+sidebar_label: Localization
+title: JavaScript Timepicker - Localization 
+description: The Timepicker locale holds the labels of the hours and minutes sliders and of the Save button. Learn how to translate them and apply a custom locale with the dhx.i18n.setLocale() method in the docs of the DHTMLX JavaScript UI library.
+---
+
+# Localization
+
+You can apply different languages to the interface of DHTMLX Timepicker. You just need to translate the corresponding strings for the labels of Timepicker and apply a ready locale to the component.
+
+![Timepicker localized into German with translated labels of the hours and minutes sliders in DHTMLX Suite](/img/timepicker/locale.png)
+
+## Default locale
+
+The default locale for Timepicker looks like this:
+
+~~~jsx
+const en = {
+    // labels of the sliders
+    hours: "Hours",
+    minutes: "Minutes",
+    // label of the Save button
+    save: "Save"
+};
+~~~
+
+Timepicker renders the **Save** button only if you enable the [`controls`](timepicker/api/timepicker_controls_config.md) property.
+
+## Custom locale
+
+To use a different locale, your need to:
+
+- define necessary language settings: provide the labels of the sliders and of the Save button:
+
+~~~jsx
+const de = {
+    hours: "Stunden",
+    minutes: "Minuten",
+    save: "Speichern"
+};
+~~~
+
+- apply the language settings by calling the `dhx.i18n.setLocale()` method before Timepicker initialization:
+
+~~~jsx
+dhx.i18n.setLocale("timepicker", de);
+const timepicker = new dhx.Timepicker("timepicker_container");
+~~~
+
+The method merges the passed labels into the current locale, so you can redefine just some of them.
+
+:::note
+A timepicker inside a calendar takes its labels from the locale of Timepicker as well. The calendar locale defines the rest of the labels, see the [Localization](calendar/localizing_calendar.md) guide of Calendar.
+:::

sidebars.js

@@ -147,6 +147,7 @@ module.exports = {
                     id: "calendar/api/overview/properties_overview"
                   },*/
                   items: [
+                    "calendar/api/calendar_controls_config",
                     "calendar/api/calendar_css_config",
                     "calendar/api/calendar_date_config",
                     "calendar/api/calendar_dateformat_config",
@@ -4281,6 +4282,7 @@ module.exports = {
             "timepicker/features",
             "timepicker/initialization",
             "timepicker/configuration",
+            "timepicker/localization",
             "timepicker/usage",
             "timepicker/customization",
             "timepicker/handling_events",