Merge pull request #11 from DHTMLX/next

Updates for v8.4

docs/chart/api/chart_data_config.md

@@ -8,6 +8,10 @@ description: You can explore the data config of Chart in the documentation of th
 
 @short: Optional. Specifies an array of data objects to set into the chart
 
+:::info
+Please note that if you specify the `id` fields in the data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically.
+:::
+
 @signature: {'data?: object[];'}
 
 @example:

docs/chart/api/chart_series_config.md

@@ -249,6 +249,7 @@ series: [
         strokeWidth?: number,
         subType?: "basic" | "percentOnly" | "valueOnly",
         useLines?: boolean,
+        valueTemplate?: (value: number) => string
     }
 ]
 ~~~
@@ -299,12 +300,16 @@ series: [
         </tr>
         <tr>
             <td><b>subType</b></td>
-            <td>(optional) specifies the subtype of a chart: "basic"|"percentOnly"|"valueOnly"</td>
+            <td>(optional) specifies the subtype of a chart: "basic" | "percentOnly" | "valueOnly"</td>
         </tr>
         <tr>
             <td><b>useLines</b></td>
             <td>(optional) shows/hides lines used to "connect" chart sectors with labels</td>
         </tr>
+         <tr>
+            <td><b>valueTemplate</b></td>
+            <td>(optional) a function that specifies the template for rendering the values for data items on a chart<br/><br><b>Related Sample: </b><a href="https://snippet.dhtmlx.com/77aei7os?tag=chart" target="_blank">Chart. Value template</a> </td>
+        </tr>
     </tbody>
 </table>
 <br><br>

docs/chart/api/export/chart_pdf_method.md

@@ -39,6 +39,8 @@ description: You can explore the pdf method of Chart in the documentation of the
             - `title` - (optional) document name
             - `pageNumber` - (optional) current page number
             - `totalPages` - (optional) total pages in the document
+    - `header?: string` - (optional) an HTML template for the header in the exported file
+    - `footer?: string` - (optional) an HTML template for the footer in the exported file
 
 
 @example:
@@ -78,7 +80,8 @@ It is necessary to set sufficient margin for correct display of `headerTemplate`
 **Related API:** [exportStyles](chart/api/chart_exportstyles_config.md)
 
 **Change log:** 
+- The **header** and **footer** options of the export object were added in v8.4
 - The **theme**, **exportStyles** options of the export object were added in v8.1
-- The **pageRanges**, **displayHeaderFooter**, **footerTemplate**, **headerTemplate** options of the pdf object were added in 8.1
-- The method was added in v8.0
+- The **pageRanges**, **displayHeaderFooter**, **footerTemplate**, **headerTemplate** options of the pdf object were added in v8.1
+- Added in v8.0
 

docs/chart/api/export/chart_png_method.md

@@ -16,6 +16,8 @@ description: You can explore the png method of Chart in the documentation of the
     - `name?: string` - (optional) the name of the exported file
     - `theme?: string` - (optional) the exported theme, "light" by default. For custom or overridden themes, enable the `exportStyles` option
     - `exportStyles?: boolean | string[]` - (optional) defines the styles that will be sent to the export service when exporting Chart. Use *false* to prevent all styles from being sent to the export service
+    - `header?: string` - (optional) an HTML template for the header in the exported file
+    - `footer?: string` - (optional) an HTML template for the footer in the exported file
 
 @example:
 // default export
@@ -34,5 +36,7 @@ chart.export.png({
 **Related API:** [exportStyles](chart/api/chart_exportstyles_config.md)
 
 **Change log:** 
+
+- The **header** and **footer** options of the export object were added in 8.4
 - The **theme** and **exportStyles** options of the export object were added in 8.1
-- The method was added in v8.0
+- Added in v8.0

docs/chart/customization.md

@@ -201,7 +201,7 @@ const chart = new dhx.Chart("chart_container", {
 
 **Related sample**: [Chart. Show text](https://snippet.dhtmlx.com/o7ke2f1s)
 
-The **showTextTemplate** option of [series](chart/configuration_properties.md#series) lets you an opportunity to add a template to values that are shown for data items in bars:
+The **showTextTemplate** option of [series](chart/configuration_properties.md#series) allows you to add a template to values that are shown for data items in bars:
 
 ~~~js {20-22,29-31}
 const chart = new dhx.Chart("chart_container", {
@@ -245,3 +245,25 @@ const chart = new dhx.Chart("chart_container", {
     }
 });
 ~~~
+
+## Adding template to values of data items in Pie and Donut charts
+
+![](../assets/chart/show_percent_values.png)
+
+**Related sample**: [Chart. Value template](https://snippet.dhtmlx.com/o7ke2f1s)
+
+When you need to show values for data items on the Pie, Pie3D and Donut charts, you can use the **valueTemplate** option of [series](chart/configuration_properties.md#the-list-of-config-options-for-series-for-charts-without-scales-pie-pie3d-donut) to specify the necessary template function. For example:
+
+~~~jsx {6-8}
+const chart = new dhx.Chart("chart_container", {
+    type: "pie",
+    series: [
+        {
+            value: "value",
+            valueTemplate: value => {
+                return (value * 100).toFixed(2) + "%";
+            }
+        }
+    ]
+});
+~~~ 

docs/chart/data_loading.md

@@ -15,7 +15,13 @@ First, you need to prepare a data set that will be loaded into Chart.
 
 ## Preparing data set
 
-DHTMLX Chart expects loaded data in the JSON format. Here are examples of appropriate data sets for different chart types:
+DHTMLX Chart expects loaded data in the JSON format. 
+
+:::info
+Please note that if you specify the `id` fields in the data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically.
+:::
+
+Here are examples of appropriate data sets for different chart types:
 
 - **Line, Spline, Bar, X-Bar, Area, Spline Area, Radar, Scatter charts**
 
@@ -46,7 +52,7 @@ A data set for Pie, Pie3D and Donut charts differs a little bit and includes the
     <tbody>
         <tr>
             <td><b>id</b></td>
-            <td>(<i>string, number</i>) the id of a series </td>
+            <td>(<i>string | number</i>) the id of a series</td>
         </tr>
         <tr>
             <td><b>key:value</b></td>
@@ -84,7 +90,7 @@ A data set for Treemap chart has also another structure and may include the foll
     <tbody>
         <tr>
             <td><b>id</b></td>
-            <td>(<i>string, number</i>) the id of a tile or group</td>
+            <td>(<i>string | number</i>) the id of a tile or group</td>
         </tr>
         <tr>
             <td><b>key:value</b></td>
@@ -122,7 +128,7 @@ A data set for Heatmap chart should include the following properties:
     <tbody>
         <tr>
             <td><b>id</b></td>
-            <td>(<i>string, number</i>) the id of a cell</td>
+            <td>(<i>string | number</i>) the id of a cell</td>
         </tr>
         <tr>
             <td><b>key:value</b></td>

docs/combobox/adding_options.md

@@ -15,7 +15,13 @@ First, you need to prepare a data set that will be loaded into Combo.
 
 ## Preparing data set
 
-DHTMLX Combo expects loaded data in the JSON format. Here is an example of an appropriate data set:
+DHTMLX Combo expects loaded data in the JSON format. 
+
+:::info
+Please note that if you specify the `id` fields in the data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically.
+:::
+
+Here is an example of an appropriate data set:
 
 ~~~js
 const dataset = [

docs/combobox/api/combobox_data_config.md

@@ -8,6 +8,10 @@ description: You can explore the data config of Combo Box in the documentation o
 
 @short: Optional. Specifies an array of data objects to set into the combobox
 
+:::info
+Please note that if you specify the `id` fields in the data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically.
+:::
+
 @signature: {'data?: object[];'}
 
 @params:

docs/combobox/api/combobox_eventhandlers_config.md

@@ -0,0 +1,81 @@
+---
+sidebar_label: eventHandlers
+title: JavaScript Combo Box - eventHandlers Config 
+description: You can explore the eventHandlers config of Combo Box in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite.
+---
+
+# eventHandlers
+
+@short: Optional. Adds event handlers to HTML elements of a custom template of Combobox items
+
+~~~js
+eventHandlers?: {
+    [eventName: string]: {
+        [className: string]: (event: Event, id: string | number) => void | boolean; 
+    };
+};
+~~~
+
+@params:
+
+The **eventHandlers** object includes a set of `key:value` pairs, where:
+
+<table>
+    <tbody>
+        <tr>
+            <td><i>key</i></td>
+            <td> the name of the event. Note, that at the beginning of the event name the <b>'on'</b> prefix is used (onclick, onmouseover).</td>
+        </tr>
+		<tr>
+            <td><i>value</i></td>
+            <td>an object that contains a <i>key:value</i> pair, where <i>key</i> is the css class name that the handler will be applied to and <i>value</i> is a function that takes two parameters:<ul><li><b>event</b> - an event object</li><li><b>id</b> - the id of a Combobox item</li></ul></td>
+        </tr>
+    </tbody>
+</table>
+
+@example:
+function template() {
+    return "<div className='class_name'></div>";
+}
+
+const combobox  = new dhx.Combobox("combobox_container", {
+    template: template,
+    eventHandlers: {
+        onclick: {
+            class_name: function(event) {
+                console.log("You clicked on " + event.target.tagName);
+                // return false;
+            },
+        },
+        onmouseover: {
+            class_name: function(event, id) {
+                console.log("Item ID: " + id);
+            },
+        }
+    }
+});
+
+@descr:
+
+**Related sample**: [Combobox. HTML template and handling events](https://snippet.dhtmlx.com/00955xwq)
+
+**Note**. Returning `false` from a handler function will stop the template event bubbling and block triggering of an event on the item with `className`.
+
+As an alternative way, you may use `stopPropagation()` for this purpose:
+
+~~~js
+eventHandlers: {
+    onclick: {
+        class_name: (event) => {                              
+            evt = event || window.event;
+            evt.stopPropagation();
+            console.log("button click");
+        }
+    }
+}
+~~~
+
+@changelog: Added in v8.4
+
+
+

docs/combobox/configuration.md

@@ -173,7 +173,7 @@ const combobox = new dhx.Combobox("combo_container",{
 You may allow end users to add new items into the data collection from UI. 
 You just need to enable the functionality via setting the [newOptions](combobox/api/combobox_newoptions_config.md) property to *true*:
 
-~~~js
+~~~jsx
 const combobox = new dhx.Combobox("combo_container", {
     multiselection: true,
       newOptions: true  
@@ -184,13 +184,18 @@ To add a new item into the list of options, the user needs to type a new value i
 
 ![](../assets/combo/new_value.png)
 
+**Related sample**: [Combobox. Multiselection, add new options (free text), select all button](https://snippet.dhtmlx.com/ui7pi7ty)
+
 The combobox invokes the [beforeAdd](data_collection/api/datacollection_beforeadd_event.md) and [afterAdd](data_collection/api/datacollection_afteradd_event.md) events of DataCollection each time when the user enters a new value into the input field. You can use the [beforeAdd](data_collection/api/datacollection_beforeadd_event.md) event to prevent adding incorrect values into the list of options:
 
-~~~js
+~~~jsx
 // blocks the ability to add an item with value: "new" into the collection of combobox items
 combobox.data.events.on("beforeAdd", item => item.value !== "new");
 ~~~
 
+You can provide a combobox with the ability to edit/delete items via the user interface. For this you can use [event handlers](#event-handlers-for-the-template) for HTML elements of a custom template of Combobox items.
+
+**Related sample**: [Combobox. Editing/deleting options](https://snippet.dhtmlx.com/xd511ci5)
 
 ## Readonly mode
 
@@ -250,6 +255,40 @@ const combo = new dhx.Combobox("combo_container", {
 });            
 ~~~
 
+## Event handlers for the template
+
+Starting from v8.4, it is possible to assign event handlers to HTML elements of a custom template of Combobox items by using the [eventHandlers](/combobox/api/combobox_eventhandlers_config/) configuration option:
+
+~~~js {11-13,17-24}
+const combobox = new dhx.Combobox("combobox", {
+    newOptions: true, // enables the ability to add and save new values from UI
+    itemHeight: 40,
+    template: ({ value, src }) => {
+        return `
+            <div class="list-item">
+                <div class="list-item__content">
+                    <img class="list-item__image" src="${src}" alt="${value}">
+                    <span class="list-item__value">${value}</span>
+                </div>
+                <button class="list-item__button list-item__button--delete">
+                    <i class="dxi dxi-delete-forever"></i>
+                </button>
+            </div>
+        `;
+    },
+    eventHandlers: {
+        onclick: { 
+            "list-item__button--delete": (event, id) => {
+                combobox.data.remove(id);
+                combobox.clear();    
+            } 
+        } 
+    }
+});
+~~~
+
+**Related sample**: [Combobox. HTML template and handling events](https://snippet.dhtmlx.com/00955xwq)
+
 ## HTML content of Combobox options
 
 By default, Combobox displays HTML content if it is specified for its options.

docs/combobox/customization.md

@@ -40,7 +40,7 @@ For example:
 
 ~~~html
 <style>
-      body {
+    body {
         margin: 0;
     }
     .custom-class .dhx_combobox-input-box {
@@ -50,7 +50,7 @@ For example:
 </style>
 
 <script>
-    const combobox = new dhx.Combobox("combobox_container", {
+    const combo = new dhx.Combobox("combo_container", {
         css: "custom-class"
     });
 </script>
@@ -104,4 +104,4 @@ const combo = new dhx.Combobox("combo_container", {
 
 **Related sample**: [Combobox. Custom filter](https://snippet.dhtmlx.com/791incm9)
 
-In the above example a custom filtering function compares an entered value with items of data collection letter by letter, and shows in the popup list all the words that contain entered letters independent of their order in a word.
+In the above example a custom filtering function compares an entered value with items of data collection letter by letter, and shows all the words that contain entered letters independent of their order in a word in the popup list.

docs/combobox/features.md

@@ -53,9 +53,10 @@ In this section you will find out how to set initial value into the input, to en
 | [Configuring a label](../configuration/#label)                                            | Learn how to configure a label and its position for Combobox ([Example](https://snippet.dhtmlx.com/2936fray))              |
 | [Hiding a label](../configuration/#hidden-label)                                          | Learn how to make a label hidden                                                                                           |
 | [Setting a placeholder](../configuration/#placeholder)                                    | Learn how to set a placeholder in the input of Combo ([Example](https://snippet.dhtmlx.com/759z23gh))                      |
-| [Adding new options](../configuration/#editable-combobox)                                 | Learn how to allow end users to add new options into Combobox via UI                                                       |
-| [Making Combobox readonly](../configuration/#readonly-mode)                               | Learn how to disable the ability to enter text in the input ([Example](https://snippet.dhtmlx.com/igjsuf7y))               |
-| [Making Combobox disabled](../configuration/#disabled-mode)                               | Learn how to block any operations with Combobox ([Example](https://snippet.dhtmlx.com/ductsm0f))                           |
+| [Adding new options](../configuration/#editable-combobox)                                 | Learn how to allow end users to add new options into Combobox via UI ([Example](https://snippet.dhtmlx.com/ui7pi7ty))    |
+| [Editing/deleting options](../configuration/#editable-combobox)                                 | Learn how to allow end users to edit/delete options in Combobox via UI ([Example](https://snippet.dhtmlx.com/xd511ci5))    |
+| [Making Combobox readonly](../configuration/#readonly-mode)                               | Learn how to disable the ability to enter text in the input ([Example](https://snippet.dhtmlx.com/igjsuf7y))         |
+| [Making Combobox disabled](../configuration/#disabled-mode)                               | Learn how to block any operations with Combobox ([Example](https://snippet.dhtmlx.com/ductsm0f))                   |
 
 ## How to customize Combobox and change its size
 
@@ -65,6 +66,7 @@ In this section you can learn how to customize Combobox and configure the height
 | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | [Height of Combobox elements](../configuration/#height-of-list-of-options-and-its-items)  | Learn how to set the height for list of Combobox options and its items ([Example](https://snippet.dhtmlx.com/vilg4l7w))        |
 | [Applying custom filtering](../customization/#custom-filter-for-options)   | Learn how to set a custom function for filtering Combobox options ([Example](https://snippet.dhtmlx.com/791incm9))             |
+| [Grouping Combobox options](https://snippet.dhtmlx.com/sk7q5wvl)   | The example shows how to group Combobox options             |
 | [Rendering HTML content](../configuration/#html-content-of-combobox-options) | Learn how to display HTML content as plain text to prevent XSS attacks ([Example](https://snippet.dhtmlx.com/e4dolhfs))        |
 | [Styling combobox (custom CSS)](../customization/#styling)                   | Learn how to change the look and feel of Combobox ([Example](https://snippet.dhtmlx.com/lldd739i))                             |
 | [Styling Combobox items](../configuration/#template-for-combobox-options)    | Learn how to customize the appearance of displaying options in the popup list ([Example](https://snippet.dhtmlx.com/z7cpj76i)) |