diff --git a/docs/combobox/adding_options.md b/docs/combobox/adding_options.md index a3f8dd57..27578bad 100644 --- a/docs/combobox/adding_options.md +++ b/docs/combobox/adding_options.md @@ -6,22 +6,22 @@ description: You can explore the data loading of Combo Box in the documentation # Data loading -There are several ways of loading Combo options: +You can load Combobox options in two ways: -- on initialization of ComboBox -- after initialization of ComboBox +- During Combobox initialization +- After Combobox initialization -First, you need to prepare a data set that will be loaded into Combo. +Both ways start from a prepared data set. ## Preparing data set -DHTMLX Combo expects loaded data in the JSON format. +DHTMLX Combobox expects data in 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. +If you specify `id` fields in the data collection, their values must be **unique**. You can also omit these fields. In this case Combobox generates the values automatically. ::: -Here is an example of an appropriate data set: +The following data set is valid: ~~~js const dataset = [ @@ -44,15 +44,17 @@ const dataset = [ ] ~~~ -Each object in the data set contains a number of *key:value* pairs that represent attributes of Combo options. [Check the details](combobox/api/combobox_data_config.md). +Each object in the data set contains `key:value` pairs that define Combobox option attributes. [Check the details](combobox/api/combobox_data_config.md). -You can specify your own template of rendering Combo options with the help of the [template](combobox/api/combobox_template_config.md) configuration option. +Use the [template](combobox/api/combobox_template_config.md) configuration option to define your own template for Combobox options. -{{note Note, until you use the [template](combobox/api/combobox_template_config.md) option, the **value** is a mandatory property for a dataset item and **src** is a reserved one.}} +:::note +Unless you apply the [template](combobox/api/combobox_template_config.md) option, `value` is a mandatory property of a data set item, and `src` is a reserved one. +::: ## Loading data on initialization -You can load [a predefined data set](#preparing-data-set) into Combobox on the initialization stage. Use the [data](combobox/api/combobox_data_config.md) configuration property, as in: +You can load [a predefined data set](#preparing-data-set) into Combobox during initialization. Use the [data](combobox/api/combobox_data_config.md) configuration property: ~~~js const combo = new dhx.Combobox("combo_container",{ @@ -64,25 +66,25 @@ const combo = new dhx.Combobox("combo_container",{ ## Loading data after initialization -There are two ways to load data into Combobox after its initialization: +You can load data into Combobox after initialization in two ways: -- [from an external file](#external-data-loading) -- [from a local data source](#loading-from-local-source) +- [From an external file](#external-data-loading) +- [From a local data source](#loading-from-local-source) ### External data loading -To load data from an external file, make use of the [load()](data_collection/api/datacollection_load_method.md) method of [DataCollection](/data_collection/). It takes the URL of the file with data as a parameter: +The [load()](data_collection/api/datacollection_load_method.md) method of [DataCollection](/data_collection/) loads data from an external file. The method takes the URL of the data file as a parameter: ~~~js -const combo = new dhx.Combo("combo_container"); +const combo = new dhx.Combobox("combo_container"); combo.data.load("../common/dataset.json"); ~~~ **Related sample**: [Combobox. Initialization with data.load()](https://snippet.dhtmlx.com/69jnq5cn) -The component will make an AJAX call and expect the remote URL to provide valid JSON data. +The component makes an AJAX call and expects the remote URL to return valid JSON data. -Data loading is asynchronous, so you need to wrap any after-loading code into a promise: +Combobox loads data asynchronously, so place the code that depends on the loaded data into the `then()` callback: ~~~js combo.data.load("/some/data").then(function(){ @@ -92,10 +94,10 @@ combo.data.load("/some/data").then(function(){ ### Loading from local source -To load data from a local data source, use the [parse()](data_collection/api/datacollection_parse_method.md) method of [DataCollection](/data_collection/). Pass [a predefined data set](#preparing-data-set) as a parameter of this method: +The [parse()](data_collection/api/datacollection_parse_method.md) method of [DataCollection](/data_collection/) loads data from a local data source. Pass [a predefined data set](#preparing-data-set) to this method: ~~~js -const combo = new dhx.Combo("combo_container"); +const combo = new dhx.Combobox("combo_container"); combo.data.parse(dataset); ~~~ @@ -103,28 +105,29 @@ combo.data.parse(dataset); ## Saving and restoring state -To save the current state of a combo box (in other words, the current list of Combobox options), use the **serialize()** method of [DataCollection](/data_collection/). It converts the data of a combo box into an array of JSON objects. -Each JSON object contains a set of *key:value* pairs that represent attributes of ComboBox options. +The `serialize()` method of [DataCollection](/data_collection/) saves the current state of Combobox — the current list of its options. The method converts Combobox data into an array of JSON objects. Each JSON object contains `key:value` pairs that define Combobox option attributes. ~~~js -const state = combo1.data.serialize(); +const state = combo.data.serialize(); // -> [{…}, {…}, {…}, {…}, {…}, {…}, {…}, …] ~~~ :::note -If you just call the [serialize()](data_collection/api/datacollection_serialize_method.md) method, it will return the list of all Combobox options. - -If you select an option in the Combobox and call the [serialize()](data_collection/api/datacollection_serialize_method.md) method, it will return only this option. +The value returned by the [serialize()](data_collection/api/datacollection_serialize_method.md) method depends on the Combobox state: -If you enable the [multi-selection mode](combobox/configuration.md#selection-of-multiple-options) of Combobox, then select one or several options in the Combobox and call the [serialize()](data_collection/api/datacollection_serialize_method.md) method, it will return the list of all Combobox options. +| Combobox state | `serialize()` returns | +| --- | --- | +| No option selected | All Combobox options | +| One option selected | The selected option only | +| [Multi-selection mode](combobox/configuration.md#selection-of-multiple-options) enabled, one or several options selected | All Combobox options | ::: -Then you can parse the data stored in the saved state array to a different combo box. For example: +You can parse the saved state array into a different Combobox: ~~~js // creating a new combo -const combo2 = new dhx.Combo(document.body); -// parsing the state of combo1 into combo2 +const combo2 = new dhx.Combobox(document.body); +// parsing the state of combo into combo2 combo2.data.parse(state); ~~~ diff --git a/docs/combobox/configuration.md b/docs/combobox/configuration.md index 315fef85..df96a041 100644 --- a/docs/combobox/configuration.md +++ b/docs/combobox/configuration.md @@ -8,7 +8,7 @@ description: You can explore the configuration of Combo Box in the documentation ## Disabled mode -There is an option that allows making ComboBox disabled and blocks any operations with it. Use the [](combobox/api/combobox_disabled_config.md) configuration property to enter the described mode. +You can disable Combobox and block all operations with it. Use the [](combobox/api/combobox_disabled_config.md) configuration property: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -22,8 +22,7 @@ const combo = new dhx.Combobox("combo_container", { ## Dynamic rendering of options -When you load a list of options into ComboBox, all items are loaded at once. In case you have a large data collection, it is suitable to render data by portions. DHTMLX ComboBox provides you with such an ability. -Use the [](combobox/api/combobox_virtual_config.md) property to render options in the ComboBox list dynamically on scrolling the list. +Combobox loads all options at once. If you have a large data collection, render the data in portions instead. Use the [](combobox/api/combobox_virtual_config.md) property to render options in the Combobox list dynamically as the user scrolls it: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -39,7 +38,7 @@ const combo = new dhx.Combobox("combo_container", { **Related sample**: [Combobox. List height](https://snippet.dhtmlx.com/vilg4l7w) -There are two useful options to adjust the height of the list of options and the height of a separate item of this list: [](combobox/api/combobox_listheight_config.md) and [](combobox/api/combobox_itemheight_config.md): +Use [](combobox/api/combobox_listheight_config.md) and [](combobox/api/combobox_itemheight_config.md) properties to adjust the height of the option list and the height of a single item in it: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -50,8 +49,7 @@ const combo = new dhx.Combobox("combo_container", { ## Help icon -While using Combo in a form, it is useful to add some info about options that can be selected in it. Use the [](combobox/api/combobox_helpmessage_config.md) configuration option for this purpose. -Set the necessary tip for users as a value of the property. +A Combobox in a form often needs a hint about the options a user can select. Use the [](combobox/api/combobox_helpmessage_config.md) configuration option and set the hint text as its value: ~~~js const combobox = new dhx.Combobox("combo_container", { @@ -61,7 +59,7 @@ const combobox = new dhx.Combobox("combo_container", { ## Hidden label -While sending a form to the server you can add a label for a ComboBox input that won't be visible, but will be used to identify the input on the server side. Use the [](combobox/api/combobox_hiddenlabel_config.md) configuration property for this property. +When you send a form to the server, you can add a label that stays invisible but identifies the Combobox input on the server side. Use the [](combobox/api/combobox_hiddenlabel_config.md) configuration property: ~~~js const combo = new dhx.Combobox("combo_container",{ @@ -72,7 +70,7 @@ const combo = new dhx.Combobox("combo_container",{ ## Initial value -Starting from v7.0, it is possible to define the values that will appear in the input on initialization of the component via the [](combobox/api/combobox_value_config.md) property: +Starting from v7.0, you can define the values that appear in the input during component initialization. Set them with the [](combobox/api/combobox_value_config.md) property: ~~~js {3,8} const combobox = new dhx.Combobox("combo_container", { @@ -88,12 +86,14 @@ const combobox = new dhx.Combobox("combo_container", { **Related sample**: [Combobox. Initial value](https://snippet.dhtmlx.com/spnausim) -- If *multiselection:true* is set for a combo, the property takes an array with options' ids: for example, *value: ["id_1","id_2","id_3"]* or *value: [1, 2, 3]*, -- If *multiselection:false* is set or the *multiselection* config is not defined, the property gets either of the two values: *value:"id_1"*, *value: 1*, or *value: ["id_1"]*. +The value that the property accepts depends on the `multiselection` configuration: + +- If you set `multiselection:true`, the property takes an array of option ids: for example, `value: ["id_1","id_2","id_3"]` or `value: [1, 2, 3]`. +- If you set `multiselection:false` or omit the `multiselection` config, the property takes a single id or an array with one id: `value:"id_1"`, `value: 1`, or `value: ["id_1"]`. ## Label -You can set a label for ComboBox, adjust its width and position using the following properties: [](combobox/api/combobox_label_config.md), [](combobox/api/combobox_labelwidth_config.md) and [](combobox/api/combobox_labelposition_config.md). This is how it can be done: +Use [](combobox/api/combobox_label_config.md), [](combobox/api/combobox_labelwidth_config.md), and [](combobox/api/combobox_labelposition_config.md) properties to set a label for Combobox and adjust the label width and position: ~~~js const combo = new dhx.Combobox("combo_container",{ @@ -105,7 +105,7 @@ const combo = new dhx.Combobox("combo_container",{ ![DHTMLX ComboBox with a label positioned to the left of the input in DHTMLX Suite](/img/combo/label_left.png) -or +To place the label above the input: ~~~js const combo = new dhx.Combobox("combo_container",{ @@ -125,14 +125,13 @@ const combo = new dhx.Combobox("combo_container",{ **Related sample**: [Combobox. Items count](https://snippet.dhtmlx.com/fw2u2bww) -Instead of showing all selected options separately in the ComboBox input, you can group them and display just the number of selected options. For this, you should use the [](combobox/api/combobox_itemscount_config.md) property. +Instead of showing all selected options separately in the Combobox input, you can group them and display only the number of selected options. Use the [](combobox/api/combobox_itemscount_config.md) property. -There are two possible types of values for this config. You can either simply enable the default behavior of the option, -or specify a custom template function to display grouped options in the desired way. The function takes one parameter: +The property accepts two types of values. You can enable the default behavior of the option, or specify a custom template function that displays the grouped options in a custom way. The function takes one parameter: -- **count** - (*number*) the number of selected options +- `count` — (`number`) the number of selected options -and should return a template for displaying a result. +The function must return the template that displays the result: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -152,7 +151,9 @@ const combo = new dhx.Combobox("combo_container", { }); ~~~ -{{note Don't forget to enable the **multiselection** option to select several options at once.}} +:::note +Enable the `multiselection` option to select several options at once. +::: ## Placeholder @@ -160,7 +161,7 @@ const combo = new dhx.Combobox("combo_container", { **Related sample**: [Combobox. Placeholder](https://snippet.dhtmlx.com/759z23gh) -To add some placeholder into the ComboBox input, apply the [](combobox/api/combobox_placeholder_config.md) property: +To add a placeholder to the Combobox input, apply the [](combobox/api/combobox_placeholder_config.md) property: ~~~js const combobox = new dhx.Combobox("combo_container",{ @@ -170,8 +171,7 @@ const combobox = new dhx.Combobox("combo_container",{ ## Editable combobox -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*: +You can allow users to add new items to the data collection from the UI. Set the [newOptions](combobox/api/combobox_newoptions_config.md) property to `true`: ~~~jsx const combobox = new dhx.Combobox("combo_container", { @@ -180,20 +180,20 @@ const combobox = new dhx.Combobox("combo_container", { }); ~~~ -To add a new item into the list of options, the user needs to type a new value into the input field and either press "Enter" or click on the appeared *Create "newValue"* option in the drop-down list. +To add a new item to the list of options, the user types a new value in the input field and then either presses **Enter** or clicks the **Create "newValue"** option that appears in the drop-down list. ![DHTMLX ComboBox dropdown offering a Create option to add a new typed value in DHTMLX Suite](/img/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: +Combobox invokes [beforeAdd](data_collection/api/datacollection_beforeadd_event.md) and [afterAdd](data_collection/api/datacollection_afteradd_event.md) events of DataCollection each time the user enters a new value in the input field. Use the [beforeAdd](data_collection/api/datacollection_beforeadd_event.md) event to reject incorrect values: ~~~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. +You can also let users edit and delete items from the user interface. Use [event handlers](#event-handlers-for-the-template) for the HTML elements in a custom template for Combobox items. **Related sample**: [Combobox. Editing/deleting options](https://snippet.dhtmlx.com/xd511ci5) @@ -203,7 +203,7 @@ You can provide a combobox with the ability to edit/delete items via the user in **Related sample**: [Combobox. Readonly](https://snippet.dhtmlx.com/igjsuf7y) -If needed, you can make ComboBox readonly via the [](combobox/api/combobox_readonly_config.md) property, so that it will be impossible to enter text in the input. In this case a user will only be able to select options from the popup list. +You can make Combobox readonly with the [](combobox/api/combobox_readonly_config.md) property. Users then cannot type in the input and can only select options from the popup list: ~~~js const combo = new dhx.Combobox("combo_container",{ @@ -213,7 +213,7 @@ const combo = new dhx.Combobox("combo_container",{ ## Selection of multiple options -In order to add the possibility to select several options in ComboBox at once, make use of the [](combobox/api/combobox_multiselection_config.md) configuration option. +To select several options in Combobox at once, use the [](combobox/api/combobox_multiselection_config.md) configuration option: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -223,8 +223,7 @@ const combo = new dhx.Combobox("combo_container", { ## Selection of all options in the list -There is the Select All button that allows selecting all options in the ComboBox list. To add this button into the component, use the [](combobox/api/combobox_selectallbutton_config.md) property. Note that you also need to enable selection of -multiple options by setting the [](combobox/api/combobox_multiselection_config.md) configuration option to *true*: +The Select All button selects all options in the Combobox list. To add this button to the component, use the [](combobox/api/combobox_selectallbutton_config.md) property. The button also requires multiple selection, so set the [](combobox/api/combobox_multiselection_config.md) configuration option to `true`: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -237,13 +236,13 @@ const combo = new dhx.Combobox("combo_container", { **Related sample**: [Combobox. Multiselection, add new options (free text), select all button](https://snippet.dhtmlx.com/ui7pi7ty) -## Template for ComboBox options +## Template for Combobox options ![DHTMLX ComboBox dropdown with custom template options showing country names and flag icons in DHTMLX Suite](/img/combo/combo_template.png) **Related sample**: [Combobox. HTML template](https://snippet.dhtmlx.com/z7cpj76i) -You can specify the appearance of ComboBox options in the list with the help of the [](combobox/api/combobox_template_config.md) property. It is a function that takes as a parameter an item of data collection and should return a string with a template for rendering options in the list. +Use the [](combobox/api/combobox_template_config.md) property to specify the appearance of Combobox options in the list. The property is a function that takes a data collection item as a parameter and returns a string with the template for rendering options: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -257,7 +256,7 @@ 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.md) configuration option: +Starting from v8.4, you can assign event handlers to the HTML elements in a custom template for Combobox items. Use the [eventHandlers](combobox/api/combobox_eventhandlers_config.md) configuration option: ~~~js {11-13,17-24} const combobox = new dhx.Combobox("combobox", { @@ -291,9 +290,9 @@ const combobox = new dhx.Combobox("combobox", { ## HTML content of Combobox options -By default, Combobox displays HTML content if it is specified for its options. +The default Combobox behavior is to display the HTML content specified for its options. -In case you need to disable rendering of HTML content and show it as plain text to keep your application safe, set the [htmlEnable](combobox/api/combobox_htmlenable_config.md) property to *false*. +To disable HTML rendering and show the content as plain text to keep your application safe, set the [htmlEnable](combobox/api/combobox_htmlenable_config.md) property to `false`: ~~~js const combo = new dhx.Combobox("combo_container", { diff --git a/docs/combobox/customization.md b/docs/combobox/customization.md index 2276cf87..073ba202 100644 --- a/docs/combobox/customization.md +++ b/docs/combobox/customization.md @@ -12,9 +12,9 @@ description: You can explore the customization of Combo Box in the documentation **Related sample**: [Combobox. Styling (custom CSS)](https://snippet.dhtmlx.com/lldd739i) -There is a possibility to make changes in the look and feel of a combo box. For this you need to take the following steps: +You can change the appearance of a Combobox. Follow these steps: -- add a new CSS class(es) with desired settings in the <style> section of your HTML page or in your file with styles (don't forget to include your file on the page in this case) +- Add one or more CSS classes with the settings you need. Place them in the ` ~~~ -- specify the name of the created CSS class (or names of classes separated by spaces) as the value of the [css](combobox/api/combobox_css_config.md) property in the ComboBox configuration: +- Specify the name of the class you created (or several names separated by spaces) as the value of the [css](combobox/api/combobox_css_config.md) property in the Combobox configuration: ~~~js const combo = new dhx.Combobox("combo_container", { @@ -60,7 +60,7 @@ For example: ![DHTMLX ComboBox with a custom fuzzy filter showing options matching the typed letters in DHTMLX Suite](/img/combo/custom_filter.png) -It is possible to set a custom filtering function for the options of ComboBox via the [](combobox/api/combobox_filter_config.md) option. A custom function takes two parameters: +Use the [](combobox/api/combobox_filter_config.md) option to set a custom filtering function for Combobox options. The function takes two parameters: @@ -75,7 +75,7 @@ It is possible to set a custom filtering function for the options of ComboBox vi
-and should return *true/false* to specify whether an item should be displayed in the filtered list of options. +The function must return `true` or `false` to specify whether Combobox displays the item in the filtered list of options. ~~~js function fuzzySearch(item, target) { @@ -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 all the words that contain entered letters independent of their order in a word in the popup list. +In the above example, the custom filtering function compares the value you type with items of the data collection letter by letter. The popup list then shows every word that contains the typed letters, regardless of their order. diff --git a/docs/combobox/features.md b/docs/combobox/features.md index 45375ce6..a504aaf6 100644 --- a/docs/combobox/features.md +++ b/docs/combobox/features.md @@ -6,11 +6,11 @@ description: You can explore the features of Combo Box in the documentation of t # Features -This page contains structured information that will help you to start working with DHTMLX Combobox and go into deep dive on its functionality. +This page helps you start working with DHTMLX Combobox and explore its functionality in depth. ## How to start with DHTMLX Combobox -In this section you can find out how to initialize and localize Combobox, how to load data into the component and how to integrate Combobox into your applications. +In this section you will learn how to initialize and localize Combobox, load data into it, and integrate it into your applications. ### Initialization and localization @@ -23,104 +23,104 @@ In this section you can find out how to initialize and localize Combobox, how to | Topic | Description | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| [Loading data into Combobox](combobox/adding_options.md#preparing-data-set) | Read how to load the initial data into Combobox | +| [Loading data into Combobox](combobox/adding_options.md#preparing-data-set) | Learn how to load the initial data into Combobox | | [Initialization with config.data](https://snippet.dhtmlx.com/8bsb9dji) | The example shows how to load data into Combobox on the fly | -| [Initialization with data.load()](https://snippet.dhtmlx.com/69jnq5cn) | The example shows to load data from external file | -| [Initialization with data.parse()](https://snippet.dhtmlx.com/d2y5yf46) | The example to load data from a local data source | +| [Initialization with data.load()](https://snippet.dhtmlx.com/69jnq5cn) | The example shows how to load data from an external file | +| [Initialization with data.parse()](https://snippet.dhtmlx.com/d2y5yf46) | The example shows how to load data from a local data source | | [Initialization with external DataCollection](https://snippet.dhtmlx.com/u8bf3efb) | The example shows how to load data from external DataCollection | -| [Rendering a large data set](combobox/configuration.md#dynamic-rendering-of-options) | Learn how to enable dynamic loading of data on scrolling the list of options ([Example](https://snippet.dhtmlx.com/5srwualw)) | +| [Rendering a large data set](combobox/configuration.md#dynamic-rendering-of-options) | Learn how to render options dynamically as the user scrolls the list ([Example](https://snippet.dhtmlx.com/5srwualw)) | ### Integration | Topic | Description | | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| [Backend integration](integration/suite_and_backend.md) | Learn how to connect DHTMLX Suite to a backend ([Demo](https://github.com/DHTMLX/nodejs-suite-demo)) | -| [Optimus](/optimus_guides/) | Learn how to use DHTMLX Optimus framework for creating DHTMLX-based app
(recommended framework for creating apps with Suite components) | -| [React integration](integration/suite_and_react.md) | Learn how to use DHTMLX Chart with React ([Demo](https://github.com/DHTMLX/react-suite-demo)) | -| [Angular integration](integration/suite_and_angular.md) | Learn how to use DHTMLX Chart with Angular ([Demo](https://github.com/DHTMLX/angular-suite-demo)) | -| [Vue integration](integration/suite_and_vue.md) | Learn how to use DHTMLX Chart with Vue.js ([Demo](https://github.com/DHTMLX/vue-suite-demo)) | +| [Backend integration](integration/suite_and_backend.md) | Learn how to connect DHTMLX Suite to a backend ([Demo](https://github.com/DHTMLX/nodejs-suite-demo)) | +| [Optimus](/optimus_guides/) | Learn how to use the DHTMLX Optimus framework to build DHTMLX-based apps
(the recommended framework for apps with Suite components) | +| [React integration](integration/suite_and_react.md) | Learn how to use DHTMLX Combobox with React ([Demo](https://github.com/DHTMLX/react-suite-demo)) | +| [Angular integration](integration/suite_and_angular.md) | Learn how to use DHTMLX Combobox with Angular ([Demo](https://github.com/DHTMLX/angular-suite-demo)) | +| [Vue integration](integration/suite_and_vue.md) | Learn how to use DHTMLX Combobox with Vue.js ([Demo](https://github.com/DHTMLX/vue-suite-demo)) | ## How to configure Combobox -In this section you will find out how to set initial value into the input, to enable multiselection, to configure a label and placeholder, and more. +In this section you will learn how to set an initial value in the input, enable multiselection, configure a label and a placeholder, and more. | Topic | Description | | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| [Setting initial value](combobox/configuration.md#initial-value) | Learn how to specify the initial values to be shown in the Combobox input ([Example](https://snippet.dhtmlx.com/spnausim)) | -| [Enabling multiselection](combobox/configuration.md#selection-of-multiple-options) | Learn how to enable the ability to select several options ([Example](https://snippet.dhtmlx.com/ui7pi7ty)) | -| [Adding Select All button](combobox/configuration.md#selection-of-all-options-in-the-list) | Learn how to enable the ability to select all options at once ([Example](https://snippet.dhtmlx.com/ui7pi7ty)) | -| [Displaying the number of selected options](combobox/configuration.md#number-of-selected-options) | Learn how to show total number of selected options in the Combobox input ([Example](https://snippet.dhtmlx.com/fw2u2bww)) | +| [Setting initial value](combobox/configuration.md#initial-value) | Learn how to specify the initial values that appear in the Combobox input ([Example](https://snippet.dhtmlx.com/spnausim)) | +| [Enabling multiselection](combobox/configuration.md#selection-of-multiple-options) | Learn how to select several options at once ([Example](https://snippet.dhtmlx.com/ui7pi7ty)) | +| [Adding Select All button](combobox/configuration.md#selection-of-all-options-in-the-list) | Learn how to select all options with a single button ([Example](https://snippet.dhtmlx.com/ui7pi7ty)) | +| [Displaying the number of selected options](combobox/configuration.md#number-of-selected-options) | Learn how to show the total number of selected options in the Combobox input ([Example](https://snippet.dhtmlx.com/fw2u2bww)) | | [Configuring a label](combobox/configuration.md#label) | Learn how to configure a label and its position for Combobox ([Example](https://snippet.dhtmlx.com/2936fray)) | -| [Hiding a label](combobox/configuration.md#hidden-label) | Learn how to make a label hidden | -| [Setting a placeholder](combobox/configuration.md#placeholder) | Learn how to set a placeholder in the input of Combo ([Example](https://snippet.dhtmlx.com/759z23gh)) | -| [Adding new options](combobox/configuration.md#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](combobox/configuration.md#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](combobox/configuration.md#readonly-mode) | Learn how to disable the ability to enter text in the input ([Example](https://snippet.dhtmlx.com/igjsuf7y)) | -| [Making Combobox disabled](combobox/configuration.md#disabled-mode) | Learn how to block any operations with Combobox ([Example](https://snippet.dhtmlx.com/ductsm0f)) | +| [Hiding a label](combobox/configuration.md#hidden-label) | Learn how to hide a label | +| [Setting a placeholder](combobox/configuration.md#placeholder) | Learn how to set a placeholder in the Combobox input ([Example](https://snippet.dhtmlx.com/759z23gh)) | +| [Adding new options](combobox/configuration.md#editable-combobox) | Learn how to let users add new options to Combobox from the UI ([Example](https://snippet.dhtmlx.com/ui7pi7ty)) | +| [Editing/deleting options](combobox/configuration.md#editable-combobox) | Learn how to let users edit and delete Combobox options from the UI ([Example](https://snippet.dhtmlx.com/xd511ci5)) | +| [Making Combobox readonly](combobox/configuration.md#readonly-mode) | Learn how to prevent typing in the input ([Example](https://snippet.dhtmlx.com/igjsuf7y)) | +| [Making Combobox disabled](combobox/configuration.md#disabled-mode) | Learn how to block all operations with Combobox ([Example](https://snippet.dhtmlx.com/ductsm0f)) | ## How to customize Combobox and change its size -In this section you can learn how to customize Combobox and configure the height of the options list and its items. +In this section you will learn how to customize Combobox and configure the height of the option list and its items. | Topic | Description | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| [Height of Combobox elements](combobox/configuration.md#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](combobox/customization.md#custom-filter-for-options) | Learn how to set a custom function for filtering Combobox options ([Example](https://snippet.dhtmlx.com/791incm9)) | +| [Height of Combobox elements](combobox/configuration.md#height-of-list-of-options-and-its-items) | Learn how to set the height of the Combobox option list and of its items ([Example](https://snippet.dhtmlx.com/vilg4l7w)) | +| [Applying custom filtering](combobox/customization.md#custom-filter-for-options) | Learn how to set a custom function that filters 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](combobox/configuration.md#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)](combobox/customization.md#styling) | Learn how to change the look and feel of Combobox ([Example](https://snippet.dhtmlx.com/lldd739i)) | -| [Styling Combobox items](combobox/configuration.md#template-for-combobox-options) | Learn how to customize the appearance of displaying options in the popup list ([Example](https://snippet.dhtmlx.com/z7cpj76i)) | -| [List of CSS classes](helpers/base_elements.md) | A set of CSS classes provided by the DHTMLX library | +| [Styling Combobox (custom CSS)](combobox/customization.md#styling) | Learn how to change the appearance of Combobox ([Example](https://snippet.dhtmlx.com/lldd739i)) | +| [Styling Combobox items](combobox/configuration.md#template-for-combobox-options) | Learn how to customize the appearance of options in the popup list ([Example](https://snippet.dhtmlx.com/z7cpj76i)) | +| [List of CSS classes](helpers/base_elements.md) | The CSS classes included in the DHTMLX library | ## How to work with Combobox -In this section you will find out how to enable and disable Combobox, to show and hide the list of options, to set and remove focus. +In this section you will learn how to enable and disable Combobox, show and hide the list of options, and set and remove focus. | Topic | Description | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [Enabling/disabling Combobox](combobox/work_with_combo.md#disablingenabling-combobox) | Learn how to enable/disable Combobox ([Example](https://snippet.dhtmlx.com/7bujtsuu)) | -| [Showing/hiding a list of Combobox options](combobox/work_with_combo.md#hidingshowing-the-popup) | Learn how to manipulate the visibility of the Combo popup ([Example](https://snippet.dhtmlx.com/ztc4sko8)) | +| [Showing/hiding a list of Combobox options](combobox/work_with_combo.md#hidingshowing-the-popup) | Learn how to show and hide the Combobox popup ([Example](https://snippet.dhtmlx.com/ztc4sko8)) | | [Setting/removing focus](combobox/work_with_combo.md#settingremoving-focus) | Learn how to set focus to Combobox ([Example](https://snippet.dhtmlx.com/hp6b5sxe)) | ## How to work with data in Combobox -In this section you can discover how to apply the [DataCollection API](guides/datacollection_guide.md) to work with data of Combobox (for example, how to add, update, serialize, or remove data). +In this section you will learn how to apply the [DataCollection API](guides/datacollection_guide.md) to Combobox data (for example, how to add, update, serialize, or remove data). | Topic | Description | | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | [Adding](combobox/work_with_combo.md#adding-options-into-combobox)/[removing](combobox/work_with_combo.md#removing-options-from-combobox) items | Learn how to add or remove Combobox options ([Example](https://snippet.dhtmlx.com/o7vd331z)) | | [Updating items](combobox/work_with_combo.md#updating-combobox-options) | Learn how to update Combobox options (for example, to change their values) ([Example](https://snippet.dhtmlx.com/y7hpq0x8)) | -| [Serializing combobox data](combobox/adding_options.md#saving-and-restoring-state) | Learn how to serialize Combobox data | -| [DataCollection API](/data_collection/) | Check the list of all available DataCollection API| +| [Serializing Combobox data](combobox/adding_options.md#saving-and-restoring-state) | Learn how to serialize Combobox data | +| [DataCollection API](/data_collection/) | Check the full DataCollection API reference | ## How to work with selected options -In this section you will learn how to set the necessary values in the input and get them, how to get the index of the value specified in the input, and how to clear the input. +In this section you will learn how to set and read the input values, get the index of a specified value, and clear the input. | Topic | Description | | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| [Selecting values](combobox/work_with_combo.md#settinggetting-values) | Learn how to set the necessary values into the input ([Example](https://snippet.dhtmlx.com/xl1p7zcx)) | -| [Getting selected values](combobox/work_with_combo.md#settinggetting-values) | Learn how to get the values which are set in the input ([Example](https://snippet.dhtmlx.com/ppvjknid)) | +| [Selecting values](combobox/work_with_combo.md#settinggetting-values) | Learn how to set values in the input ([Example](https://snippet.dhtmlx.com/xl1p7zcx)) | +| [Getting selected values](combobox/work_with_combo.md#settinggetting-values) | Learn how to read the values set in the input ([Example](https://snippet.dhtmlx.com/ppvjknid)) | | [Getting index of selected values](data_collection/api/datacollection_getindex_method.md) | Learn how to get the index of the value specified in the input ([Example](https://snippet.dhtmlx.com/ik6r8cs2)) | -[Clearing input](combobox/work_with_combo.md#clearing-input)|Learn how to clear the Combobox input from the specified values ([Example](https://snippet.dhtmlx.com/omlrtmj7))| +| [Clearing input](combobox/work_with_combo.md#clearing-input) | Learn how to clear the specified values from the Combobox input ([Example](https://snippet.dhtmlx.com/omlrtmj7)) | ## How to work with Combobox events -This section explains how to work with Combobox events. +In this section you will learn how to work with Combobox events. | Topic | Description | | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------- | -| [Event basic rules](guides/events_guide.md) | Learn basic rules on how to work with events | -| [Event handling](combobox/handling_events.md) | Learn how to attach, detach, or call the Combobox events ([Example](https://snippet.dhtmlx.com/n70eqx5l)) | +| [Event basic rules](guides/events_guide.md) | Learn the basic rules of event handling | +| [Event handling](combobox/handling_events.md) | Learn how to attach, detach, or call Combobox events ([Example](https://snippet.dhtmlx.com/n70eqx5l)) | ## API reference -In this section you can find out corresponding references of Combobox API. +In this section you will find the Combobox API reference. | Topic | Description | | ---------------------------------------------------------- | ---------------------------------------- | @@ -130,13 +130,13 @@ In this section you can find out corresponding references of Combobox API. ## Common functionality -In this section you will learn about common functionality of the library which can be useful while working with Combobox. +In this section you will learn about common library functionality that is useful when you work with Combobox. | Topic | Description | | ------------------------------------------------------------- | ------------------------------------------------------------- | | [Touch support](common_features/touch_support.md) | Learn how to work with touch support | | [TypeScript support](common_features/using_typescript.md) | Learn how to work with TypeScript | -| [AwaitRedraw](helpers/await_redraw.md) | Learn how to perform the code after the component's rendering | +| [AwaitRedraw](helpers/await_redraw.md) | Learn how to run code after the component renders | ## Any questions left? diff --git a/docs/combobox/handling_events.md b/docs/combobox/handling_events.md index 6daa28da..dba2327d 100644 --- a/docs/combobox/handling_events.md +++ b/docs/combobox/handling_events.md @@ -8,17 +8,17 @@ description: You can explore the event handling of Combo Box in the documentatio ## Attaching event listeners -The user can add any user-defined handler to any of the available events. To do this, the user can use the **combo.events.on()** method with the following parameters: +You can add a custom handler to any available event with the `combo.events.on()` method. The method takes the following parameters: - + - +
evNamename of the eventthe event name
evHandleruser-defined event handlera custom event handler
@@ -29,17 +29,17 @@ combo.events.on("open", function() { }); ~~~ -Several handlers can be attached to one and the same event, and all of them will be executed. +You can attach several handlers to the same event, and Combobox runs all of them. -{{note -The names of the events are case-insensitive. -}} +:::note +Event names are case-insensitive. +::: **Related sample**: [Combobox. Events](https://snippet.dhtmlx.com/n70eqx5l) ## Detaching event listeners -There is a simple way of removing an event handler via the **combo.events.detach()** method: +The `combo.events.detach()` method removes an event handler: ~~~js combo.events.on("open", function() { @@ -51,7 +51,7 @@ combo.events.detach("open"); ## Calling events -To call events, use **combo.events.fire()**: +The `combo.events.fire()` method calls an event: ~~~js combo.events.fire("name",args); @@ -60,4 +60,4 @@ combo.events.fire("name",args); ## List of supported events -You can find the full list of ComboBox events in the [API Reference](combobox/api/api_overview.md#events). +You can find the full list of Combobox events in the [API Reference](combobox/api/api_overview.md#events). diff --git a/docs/combobox/how_to_start.md b/docs/combobox/how_to_start.md index 33f04703..c5c06eaa 100644 --- a/docs/combobox/how_to_start.md +++ b/docs/combobox/how_to_start.md @@ -7,16 +7,16 @@ description: You can explore the initialization of Combo Box in the documentatio # Initialization :::info -[Download the DHTMLX Combo package](https://dhtmlx.com/docs/products/dhtmlxSuite/download.shtml) as a part of the DHTMLX Suite library +[Download the DHTMLX Combobox package](https://dhtmlx.com/docs/products/dhtmlxSuite/download.shtml) as part of the DHTMLX Suite library. ::: -To add DHTMLX Combo in your application, you need to follow the steps below: +Follow these steps to add DHTMLX Combobox to your application: - [Include source files](#include-source-files) - [Create a container](#create-a-container) -- [Initialize ComboBox](#initialize-combobox) with the object constructor -- [Load data into ComboBox](#load-data-into-combobox) +- [Initialize Combobox](#initialize-combobox) with the constructor +- [Load data into Combobox](#load-data-into-combobox) ~~~html title="index.html" @@ -39,12 +39,12 @@ To add DHTMLX Combo in your application, you need to follow the steps below: ## Include source files -Unpack the downloaded package into a folder of your project. +Unpack the downloaded package into your project folder. -After that, create an HTML file and place full paths to JS and CSS files of the DHTMLX Suite library into the header of the file. The files are: +Create an HTML file and add the full paths to the JS and CSS files of the DHTMLX Suite library in its header. The files are: -- *suite.js* -- *suite.css* +- `suite.js` +- `suite.css` ~~~html title="index.html" @@ -53,34 +53,34 @@ After that, create an HTML file and place full paths to JS and CSS files of the ## Create a container -Add a container for ComboBox and give it an id, for example "combo_container": +Add a container for Combobox and give it an id, for example `combo_container`: ~~~html title="index.html"
~~~ -## Initialize ComboBox +## Initialize Combobox -To initialize DHTMLX ComboBox, you should use the `dhx.Combobox` constructor. The constructor function takes two parameters: +Use the `dhx.Combobox` constructor to initialize DHTMLX Combobox. The constructor takes two parameters: -- a container to place a Combo Box into. The one we have created at the previous step. -- an object with configuration properties. See the full list below. +- A container to place Combobox into — the one you created in the previous step. +- An object with configuration properties. See the full list below. ~~~js title="index.js" const combo = new dhx.Combobox("combo_container", { label: "Countries:", - placeholder: "Сlick to select", + placeholder: "Click to select", // more config options }); ~~~ ### Configuration properties -See the detailed description of Combo configuration options in the [Combobox API overview](combobox/api/api_overview.md#properties) article. +The [Combobox API overview](combobox/api/api_overview.md#properties) article describes Combobox configuration options in detail. -## Load data into ComboBox +## Load data into Combobox -Detailed information on how to load data into ComboBox is given in the [](combobox/adding_options.md) article. +The [](combobox/adding_options.md) article explains how to load data into Combobox. ## Example diff --git a/docs/combobox/index.md b/docs/combobox/index.md index 9a1d85ec..61ce16d4 100644 --- a/docs/combobox/index.md +++ b/docs/combobox/index.md @@ -4,17 +4,16 @@ title: JavaScript Combo Box - Combo Box Overview description: You can have an overview 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. --- -# ComboBox overview +# Combobox overview -DHTMLX ComboBox is an advanced select box that provides the ability to show suggestions while a user is entering text in the input. The component allows you to set custom filtering rules and specify templates of -displaying options in the list. Among other nice features there are tuning of the list of options and Combo Box input, selection of multiple options and data loading on request. -Check [online samples for DHTMLX ComboBox](https://snippet.dhtmlx.com/ui7pi7ty?tag=combobox). +DHTMLX Combobox is an advanced select box that shows suggestions while the user types in the input. The component allows you to set custom filtering rules and specify templates for options in the list. Other features include configuration of the option list and the input, multiple selection, and data loading on demand. +Check [online samples for DHTMLX Combobox](https://snippet.dhtmlx.com/ui7pi7ty?tag=combobox). ![DHTMLX ComboBox with typed text and a dropdown of country options with flag icons in DHTMLX Suite](/img/combo/combo_front.png) ## Features -You can check the following page to learn how to build a full-featured DHTMLX Combobox: +Check the following page to learn how to build a full-featured DHTMLX Combobox: - [Features](combobox/features.md) @@ -24,9 +23,9 @@ You can check the following page to learn how to build a full-featured DHTMLX Co ## Related resources -- You can get DHTMLX ComboBox as a part of the Suite library by [downloading DHTMLX Suite](https://dhtmlx.com/docs/products/dhtmlxSuite/download.shtml) -- There are also [online samples for DHTMLX ComboBox](https://snippet.dhtmlx.com/ui7pi7ty?tag=combobox) -- To work with data of ComboBox check [DataCollection API](/data_collection/) +- [Download DHTMLX Suite](https://dhtmlx.com/docs/products/dhtmlxSuite/download.shtml) to get DHTMLX Combobox as part of the Suite library +- Browse [online samples for DHTMLX Combobox](https://snippet.dhtmlx.com/ui7pi7ty?tag=combobox) +- Check the [DataCollection API](/data_collection/) to work with Combobox data ## Guides diff --git a/docs/combobox/localization.md b/docs/combobox/localization.md index 66c2f66c..91b8bfb2 100644 --- a/docs/combobox/localization.md +++ b/docs/combobox/localization.md @@ -6,13 +6,13 @@ description: You can explore the localization of Combo Box in the documentation # Localization -You can apply different languages to the interface of DHTMLX Combo. You just need to translate the corresponding strings for Combobox labels and apply a ready locale to the component. +You can apply different languages to the DHTMLX Combobox interface. Translate the label strings and apply the resulting locale to the component. **Related sample**: [Combobox. Localization](https://snippet.dhtmlx.com/cnj0j9g0?tag=combobox) ## Default locale -The default locale for Combobox looks like this: +Combobox uses the following default locale: ~~~js const en = { @@ -27,9 +27,9 @@ const en = { ## Custom locale -To use a different locale, your need to: +Follow these steps to use a different locale: -- define necessary language settings - names of buttons and labels: +- Define the language settings—button and label names: ~~~js const de = { @@ -42,10 +42,10 @@ const de = { }; ~~~ -- apply the language settings by calling the **dhx.i18n.setLocale()** method before Combobox initialization: +- Call the `dhx.i18n.setLocale()` method before Combobox initialization to apply the settings: ~~~js -dhx.i18n.setLocale("combo_container", de); +dhx.i18n.setLocale("combobox", de); const combo = new dhx.Combobox("combo_container"); ~~~ diff --git a/docs/combobox/work_with_combo.md b/docs/combobox/work_with_combo.md index 5ef7a67d..b1509c82 100644 --- a/docs/combobox/work_with_combo.md +++ b/docs/combobox/work_with_combo.md @@ -8,9 +8,9 @@ description: You can explore how to work with Combo Box in the documentation of ## Setting/getting value(s) -In order to select options in ComboBox, use the [setValue()](combobox/api/combobox_setvalue_method.md) method. It takes one parameter: +Use the [`setValue()`](combobox/api/combobox_setvalue_method.md) method to select options in Combobox. The method takes one parameter: -- **value** - (*string|number|array*) the **ID(s)** of Combo options from data collection that should be selected in ComboBox +- `value` — (`string|number|array`) the ids of the Combobox options in the data collection to select ~~~js // select one option @@ -22,10 +22,9 @@ combo.setValue([combo.data.getId(1), combo.data.getId(3)]); **Related sample**: [Combobox. Set value](https://snippet.dhtmlx.com/xl1p7zcx) -To get the list of selected options, apply the [getValue()](combobox/api/combobox_getvalue_method.md) method. It returns IDs of selected options either as string(s) (by default) or as an array of strings. -In the latter case you need to pass the following parameter: +Apply the [`getValue()`](combobox/api/combobox_getvalue_method.md) method to get the list of selected options. The method returns ids of selected options, and the default return type is a string. To get an array of strings, pass the following parameter: -- **asArray** - (*boolean*) true, to return ids as an array of strings +- `asArray` — (`boolean`) `true`, to return ids as an array of strings ~~~js const id = combo.getValue(); @@ -44,7 +43,7 @@ const array_ids = combo.getValue(true); ## Disabling/enabling ComboBox -To disable/enable ComboBox, make use of the [disable()](combobox/api/combobox_disable_method.md)/[enable()](combobox/api/combobox_enable_method.md) methods: +Use [`disable()`](combobox/api/combobox_disable_method.md) and [`enable()`](combobox/api/combobox_enable_method.md) methods to disable and enable Combobox: ~~~js // disabling a combo box @@ -57,7 +56,7 @@ combo.enable(); ## Checking if a combobox is disabled -To check if a combobox is disabled, call the [isDisabled()](combobox/api/combobox_isdisabled_method.md) method: +Call the [`isDisabled()`](combobox/api/combobox_isdisabled_method.md) method to check whether Combobox is disabled: ~~~js combo.isDisabled(); // -> true/false @@ -67,7 +66,7 @@ combo.isDisabled(); // -> true/false ## Repainting ComboBox -You can repaint ComboBox on a page, e.g. after changing its configuration, using the [`paint()`](combobox/api/combobox_paint_method.md) method: +You can repaint Combobox on a page with the [`paint()`](combobox/api/combobox_paint_method.md) method, for example after you change its configuration: ~~~js // disabling ComboBox via the configuration object @@ -78,7 +77,7 @@ combo.paint(); ## Clearing input -It is possible to clear the ComboBox input from the selected value(s) with the help of the [`clear()`](combobox/api/combobox_clear_method.md) method: +The [`clear()`](combobox/api/combobox_clear_method.md) method clears the selected values from the Combobox input: ~~~js combo.clear(); @@ -88,13 +87,13 @@ combo.clear(); ## Setting/removing focus -When needed, you can set focus in the ComboBox input without opening the list of options. Use the [`focus()`](combobox/api/combobox_focus_method.md) method for this purpose: +You can set focus in the Combobox input without opening the list of options. Use the [`focus()`](combobox/api/combobox_focus_method.md) method: ~~~js combo.focus(); ~~~ -To remove focus from Combobox, apply the [`blur()`](combobox/api/combobox_blur_method.md) method: +Apply the [`blur()`](combobox/api/combobox_blur_method.md) method to remove focus from Combobox: ~~~js combo.blur(); @@ -104,15 +103,15 @@ combo.blur(); ## Hiding/showing the popup -You can manipulate the visibility of the Combo popup with the help of the [Popup](popup/api/api_overview.md) API. +You can show and hide the Combobox popup with the [Popup](popup/api/api_overview.md) API. -To hide/show the popup, use the corresponding methods: +Use the following methods to hide and show the popup: - + @@ -132,21 +131,21 @@ combo.popup.hide(); **Related sample**: [Combobox. Show / hide options list](https://snippet.dhtmlx.com/ztc4sko8) -To control the process of showing/hiding the popup, apply the related events: +Handle the following events to control when the popup opens and closes:
show()shows a popup in a Combo. Takes two parameters:
  • container - (HTMLElement) mandatory, the container to place a popup in
  • config - (object) optional, the configuration object of a popup
shows a popup in Combobox. Takes two parameters:
  • container - (HTMLElement) mandatory, the container to place a popup in
  • config - (object) optional, the configuration object of a popup
hide()
- + - + - + @@ -180,11 +179,11 @@ combo.popup.events.on("AfterHide", function(e){ ## Using Data Collection API -You can manipulate ComboBox options with the help of the [Data Collection API](/data_collection/). +You can manage Combobox options with the [Data Collection API](/data_collection/). ### Adding options into ComboBox -It is possible to add more options into the initialized ComboBox on the fly. Use the `add()` method of Data Collection. It takes two parameters: +You can add more options to an initialized Combobox on the fly. Use the `add()` method of Data Collection. The method takes two parameters:
beforeShowfires before a popup is shown. The handler function takes one parameter:
  • container - (HTMLElement) a container a popup is placed into
Return false to prevent showing of a popup		fires before a popup is shown. The handler function takes one parameter:
  • container - (HTMLElement) the container the popup is placed in
Return false to prevent the popup from opening
afterShowfires after a popup is shown. The handler function takes one parameter:
  • container - (HTMLElement) a container a popup is placed into
fires after a popup is shown. The handler function takes one parameter:
  • container - (HTMLElement) the container the popup is placed in
beforeHidefires before a popup is hidden. The handler function takes two parameters:
  • fromOuterClick - (boolean) true, for a click outside a popup, otherwise - false
  • e - (Event) the native mouse event
Return false to prevent hiding of a popup		fires before a popup is hidden. The handler function takes two parameters:
  • fromOuterClick - (boolean) true, for a click outside a popup, otherwise - false
  • e - (Event) the native mouse event
Return false to prevent the popup from closing
afterHide
@@ -199,7 +198,7 @@ It is possible to add more options into the initialized ComboBox on the fly. Use
-For instance: +For example: ~~~js combobox.data.add({value:"Russia"},1); @@ -208,12 +207,12 @@ combobox.data.add({value:"Russia"},1); **Related sample**: [Combobox. Add data and remove item](https://snippet.dhtmlx.com/o7vd331z) :::info -From v7.3, Combobox includes the [](combobox/api/combobox_addoption_method.md) method which you can also use for adding new options into the data collection. +From v7.3, Combobox includes the [](combobox/api/combobox_addoption_method.md) method that you can also use to add new options to the data collection. ::: ### Updating ComboBox options -You can change config options of the option via the `update()` method of Data Collection. It takes two parameters: +You can change option settings with the `update()` method of Data Collection. The method takes two parameters: @@ -223,7 +222,7 @@ You can change config options of the option via the `update()` method of Data Co - +
configan object with new configuration of the optionan object with the new option configuration
@@ -240,12 +239,12 @@ combo.data.update("option_id",{ ### Removing options from ComboBox -To remove an option, make use of the `remove()` method of Data Collection. Pass the id of the option that should be removed to the method: +Use the `remove()` method of Data Collection to remove an option. Pass the option id to the method: ~~~js combo.data.remove("option_id"); ~~~ :::note -Check the full list of [Data collection API](/data_collection/) +Check the full [Data Collection API](/data_collection/) reference. ::: diff --git a/docs/common_features/accessibility_support.md b/docs/common_features/accessibility_support.md index ac6f4f51..36ec8cd5 100644 --- a/docs/common_features/accessibility_support.md +++ b/docs/common_features/accessibility_support.md @@ -6,40 +6,40 @@ description: You can learn about Accessibility support in the documentation of t # Accessibility support -Accessibility is one of the key concepts in present-day web development. It presupposes equal access to web resources for people with diverse abilities. +Accessibility is one of the key concepts in present-day web development. It gives people with diverse abilities equal access to web resources. ## Web Conformance Guidelines -Even if you are not mandated to conform to any particular accessibility standard, it can be helpful to understand the guidelines outlined as they are generally good practices worth incorporating into your web based applications. +Even if no accessibility standard is mandatory for you, the guidelines below are good practices worth applying to your web-based applications. -Currently the most commonly encountered conformance guidelines and standards are: +The most common conformance guidelines and standards are: -- [ADA](https://www.ada.gov/) - US Department of Justice -- [Section 508](https://www.section508.gov/) - US federal agencies -- [WCAG 2.0](https://www.w3.org/WAI/standards-guidelines/wcag/) - globally accepted standard. WCAG 2.0 has 3 levels of conformance; A, AA and AAA (in order of conformance) -- [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) - a standard that defines ways to make web content and web applications more accessible to people with disabilities -- [WAI](https://www.w3.org/WAI/) - web accessibility standard +- [ADA](https://www.ada.gov/) — US Department of Justice +- [Section 508](https://www.section508.gov/) — US federal agencies +- [WCAG 2.0](https://www.w3.org/WAI/standards-guidelines/wcag/) — a globally accepted standard with three conformance levels: A, AA, and AAA, in ascending order +- [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) — a standard that defines ways to make web content and web applications more accessible to people with disabilities +- [WAI](https://www.w3.org/WAI/) — a web accessibility standard -The DHTMLX Suite library meets the main requirements of the WCAG 2.0 standards and provides support for the following accessibility components: +The DHTMLX Suite library meets the main requirements of the WCAG 2.0 standard and supports the following accessibility components: - [WAI-ARIA Attributes](#wai-aria-attributes) - [Keyboard Navigation](#keyboard-navigation) -- [High-Сontrast Themes](#high-contrast-themes) +- [High-Contrast Themes](#high-contrast-themes) ## WAI-ARIA Attributes -There are special attributes used in the markup of DHTMLX Suite widgets that make it possible for screen readers to recognize and interpret them to the user, namely: +The markup of DHTMLX Suite widgets contains special attributes that let screen readers recognize the widgets and describe them to the user: ### Grid -There are **roles** and **attributes** for elements of grid, sorting, filters, editable cells to enable screen readers to interpret and navigate the columns and rows of the grid (enabled by default). The semantics are always present and there is no flag to disable them. Custom content should be marked manually. +Grid elements, sorting, filters, and editable cells have **roles** and **attributes** that let screen readers interpret and navigate grid columns and rows. The semantics are always present, and no flag disables them. Mark custom content manually. You can find the following **roles** and **attributes** in the DOM: -- role: *grid* (or *treegrid* in the `type: "tree"` mode), *rowgroup*, *row*, *columnheader*, *gridcell*, *button* -- aria attributes: *label*, *rowcount*, *colcount*, *rowindex*, *colindex*, *aria-sort*, *aria-selected*, *aria-readonly*, *aria-multiselectable*, and — for tree rows — *aria-level* and *aria-expanded*. +- role: `grid` (or `treegrid` in the `type: "tree"` mode), `rowgroup`, `row`, `columnheader`, `gridcell`, `button` +- aria attributes: `label`, `rowcount`, `colcount`, `rowindex`, `colindex`, `aria-sort`, `aria-selected`, `aria-readonly`, `aria-multiselectable`, and — for tree rows — `aria-level` and `aria-expanded`. -In-place editors and header/footer filters get an accessible name derived from the column header text. Role presentation and aria-hidden are used to hide redundant content (resizers, sort icons, drag ghosts, the selection overlay) from the accessibility tree. +In-place editors and header/footer filters get an accessible name derived from the column header text. The `presentation` role and `aria-hidden` hide redundant content (resizers, sort icons, drag ghosts, the selection overlay) from the accessibility tree. :::info For the complete picture — the ARIA model, the keyboard zones (header/body/footer), the focus model, and configuration recipes — see the dedicated [Grid accessibility](grid/accessibility.md) guide. @@ -47,39 +47,39 @@ For the complete picture — the ARIA model, the keyboard zones (header/body/foo ### Chart -There are **aria** attributes for axes, lines, points, legends and general description of the chart (enabled by default). Points on charts like line, spline, area, spline area have aria attributes only when the **pointType** property is set. Information for attributes is taken from the chart config and property names. Currently, the ability to specify this information by yourself is not provided. +**aria** attributes cover axes, lines, points, legends, and a general description of the chart. They are enabled by default. Points on line, spline, area, and spline area charts have aria attributes only when the `pointType` property is set. DHTMLX takes the attribute information from the chart config and property names. You cannot specify this information yourself. You can find the following **roles** and **attributes** in the DOM: -- role: *graphics-document*, *graphics-object*, *graphics-symbol*, *button* -- aria attributes: *label*, *roledescription*. +- role: `graphics-document`, `graphics-object`, `graphics-symbol`, `button` +- aria attributes: `label`, `roledescription`. -Role presentation and aria-hidden are used to hide redundant content from the accessibility tree. +The `presentation` role and `aria-hidden` hide redundant content from the accessibility tree. ### List and DataView -There are general description of the component, items and their states. All the **roles** and **attributes** are enabled by default You can find the following **roles** and **attributes** in the DOM: -- role: *listbox*, *option* -- aria attributes: *label*, *roledescription*, *grabbed*, *selected*, *multiselectable*, *readonly*. +The component, its items, and their states have a general description. All **roles** and **attributes** are enabled by default. You can find the following **roles** and **attributes** in the DOM: +- role: `listbox`, `option` +- aria attributes: `label`, `roledescription`, `grabbed`, `selected`, `multiselectable`, `readonly`. -Role presentation and aria-hidden are used to hide redundant markup from the accessibility tree. +The `presentation` role and `aria-hidden` hide redundant markup from the accessibility tree. -### Toolbar +### Toolbar -There are general description of the component, items and their states. All the **roles** and **attributes** are enabled by default You can find the following **roles** and **attributes** in the DOM: +The component, its items, and their states have a general description. All **roles** and **attributes** are enabled by default. You can find the following **roles** and **attributes** in the DOM: -- role: *toolbar*, *button*, *combobox*, *menu*, *menuitem* -- aria attributes: *label*, *labeledby*, *orientation*, *haspopup*, *expanded*, *disabled*, *pressed*. +- role: `toolbar`, `button`, `combobox`, `menu`, `menuitem` +- aria attributes: `label`, `labeledby`, `orientation`, `haspopup`, `expanded`, `disabled`, `pressed`. -Role presentation and aria-hidden are used to hide redundant markup from the accessibility tree. +The `presentation` role and `aria-hidden` hide redundant markup from the accessibility tree. ## Keyboard Navigation -All DHTMLX Suite widgets are provided with a keyboard navigation support. It allows using a Suite-based app without a mouse pointer. Basic rules include: +All DHTMLX Suite widgets support keyboard navigation, so you can use a Suite-based app without a mouse pointer. Basic rules include: -- the Tab key is used to navigate between widgets and clickable areas of the widgets -- the Esc key closes windows and editors -- the Enter is used to open and hide drop-down lists of select controls -- the Arrow keys are used to move selection or change active elements within widgets +- The Tab key moves focus between widgets and their clickable areas +- The Esc key closes windows and editors +- The Enter key opens and closes drop-down lists of select controls +- The Arrow keys move selection or change active elements within widgets :::info For the full list of built-in hotkeys, refer to the **Keyboard Navigation** articles of the following widgets: @@ -91,9 +91,9 @@ For the full list of built-in hotkeys, refer to the **Keyboard Navigation** arti ## High-Contrast Themes -For users that are visually impaired due to color deficiencies, care should be taken when using colors to provide information. +For users who are visually impaired due to color deficiencies, choose colors carefully when you use them to convey information. -Among various DHTMLX Suite themes there are the high-contrast ones: +DHTMLX Suite includes two high-contrast themes: - **Light High Contrast** - **Dark High Contrast** @@ -101,6 +101,6 @@ Among various DHTMLX Suite themes there are the high-contrast ones: The contrast themes correspond to the AAA level. ::: -Being rather attractive, it is also helpful for those users who have weak eye-sight. +These themes also help users with poor eyesight. \ No newline at end of file diff --git a/docs/common_features/custom_scroll.md b/docs/common_features/custom_scroll.md index ddcc0fa9..016f6e21 100644 --- a/docs/common_features/custom_scroll.md +++ b/docs/common_features/custom_scroll.md @@ -6,15 +6,17 @@ description: You can learn about custom scroll in the documentation of the DHTML # Custom scroll -{{pronote This functionality requires PRO version of the DHTMLX Suite package.}} +:::info +This functionality requires the PRO version of the DHTMLX Suite package. +::: -From v7.2, DHTMLX includes neat custom scrollbars with a thin grey semi-transparent design to replace the standard browser scrollbars. The custom bars come with the auto-hide behavior, i.e., they are initially hidden and shown only when the user hovers the mouse over the page. +From v7.2, DHTMLX includes custom scrollbars with a thin, grey, semi-transparent design that replace the standard browser scrollbars. The custom bars hide automatically: they stay hidden until the user hovers the mouse over the page. -The custom scroll is available for the following DHTMLX components: List, DataView, Grid, Grid in the TreeGrid mode, Layout cell, Toolbar, Ribbon, Sidebar, Window. +The custom scroll is available for the following DHTMLX components: List, DataView, Grid, Grid in the TreeGrid mode, Layout cell, Toolbar, Ribbon, Sidebar, and Window. -To add the feature into your application, you need to set the **enable** property of the **dhx.scrollViewConfig** global variable to *true* before initialization of the widgets: +Set the `enable` property of the `dhx.scrollViewConfig` global variable to `true` before you initialize the widgets: ~~~js // enable the custom scroll for all available widgets @@ -26,7 +28,7 @@ const list = new dhx.List("list_container", { }); ~~~ -or apply the **enable()** method of the **scrollView** object after initialization of the widget: +To enable the custom scroll after initialization, apply the `enable()` method of the `scrollView` object: ~~~js // initialize the widget @@ -42,11 +44,11 @@ list.data.load(data); list.scrollView.enable(); ~~~ -For more details on the custom scroll configuration, read [this article](helpers/custom_scroll.md). +For more details, read the [custom scroll configuration](helpers/custom_scroll.md) article. ## Custom scroll in Optimus demos -You may notice, that all DHTMLX demos built with Optimus have the custom scroll enabled. +All DHTMLX demos built with Optimus have the custom scroll enabled. ![Hospital management demo grid with thin custom scrollbars enabled in DHTMLX Suite](/img/integration/custom_scroll_optimus.png) @@ -54,10 +56,10 @@ You may notice, that all DHTMLX demos built with Optimus have the custom scroll | Demo | Related article | |-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| -| [File Explorer](https://dhtmlx.com/docs/products/demoApps/dhtmlxFileExplorerDemo/) | learn more in [the related article](optimus_guides/filemanager_demo.md) | -| [UI Dashboard](https://dhtmlx.com/docs/products/demoApps/dhtmlxFileExplorerDemo/) | learn more in [the related article](optimus_guides/dashboard_demo.md) | -| [Hotel Management Template](https://dhtmlx.com/docs/products/demoApps/dhtmlxDashboard/) | learn more in [the related article](optimus_guides/hotel_demo.md) | -| [Geo Tracking](https://dhtmlx.com/docs/products/demoApps/dhtmlxGeoTracking/) | learn more in [the related article](optimus_guides/geotracking_demo.md) | -| [Hospital Management](https://dhtmlx.com/docs/products/demoApps/dhtmlxHospital/) | learn more in [the related article](optimus_guides/hospital_demo.md) | -| [Sales KPI Tracking](https://dhtmlx.com/docs/products/demoApps/dhtmlxKPI/) | learn more in [the related article](optimus_guides/kpi_demo.md) | -| [Online Exam System](https://dhtmlx.com/docs/products/demoApps/dhtmlxExam/) | learn more in [the related article](optimus_guides/exam_demo.md) | +| [File Explorer](https://dhtmlx.com/docs/products/demoApps/dhtmlxFileExplorerDemo/) | [File Explorer guide](optimus_guides/filemanager_demo.md) | +| [UI Dashboard](https://dhtmlx.com/docs/products/demoApps/dhtmlxFileExplorerDemo/) | [UI Dashboard guide](optimus_guides/dashboard_demo.md) | +| [Hotel Management Template](https://dhtmlx.com/docs/products/demoApps/dhtmlxDashboard/) | [Hotel Management guide](optimus_guides/hotel_demo.md) | +| [Geo Tracking](https://dhtmlx.com/docs/products/demoApps/dhtmlxGeoTracking/) | [Geo Tracking guide](optimus_guides/geotracking_demo.md) | +| [Hospital Management](https://dhtmlx.com/docs/products/demoApps/dhtmlxHospital/) | [Hospital Management guide](optimus_guides/hospital_demo.md) | +| [Sales KPI Tracking](https://dhtmlx.com/docs/products/demoApps/dhtmlxKPI/) | [Sales KPI Tracking guide](optimus_guides/kpi_demo.md) | +| [Online Exam System](https://dhtmlx.com/docs/products/demoApps/dhtmlxExam/) | [Online Exam System guide](optimus_guides/exam_demo.md) | diff --git a/docs/common_features/touch_support.md b/docs/common_features/touch_support.md index c3784acb..260cb3a7 100644 --- a/docs/common_features/touch_support.md +++ b/docs/common_features/touch_support.md @@ -6,15 +6,17 @@ description: You can learn about touch support in the documentation of the DHTML # Touch support -Since version 7.0 and upper, the dhtmlxSuite library provides the built-in Touch support that should work out of the box. As a result, the interaction with the DHTMLX-based apps on touch devices becomes more comfy and predictable. +From v7.0, the DHTMLX Suite library includes built-in touch support, so interacting with DHTMLX-based apps on touch devices is more comfortable and predictable. -{{note Check the example in our Snippet Tool to try out the functionality on your touch devices.}} +:::info +Check the [example in the Snippet Tool](https://snippet.dhtmlx.com/q3cu6x1a) to try out the functionality on your touch devices. +::: -While interacting with applications by touching the screen, a tap becomes the same thing as a mouse click. -Thus, the click events (fire on clicking, double clicking an item) will continue working on touch-screen devices. But note, that the mouseover events will not trigger. +On a touch screen, a tap works like a mouse click. +Click events, which fire when you click or double-click an item, keep working on touch-screen devices. Note that mouseover events do not trigger. -Touch support works for all DHTMLX widgets and enables recognition for the following touch gestures: +Touch support works for all DHTMLX widgets and recognizes the following gestures: -- **Double Tap** - to edit items -- **Press and Hold** - to call the context menu -- **Drag** - to resize and reorder items, to change the value in Slider, ColorPicker, or TimePicker +- **Double Tap** — to edit items +- **Press and Hold** — to call the context menu +- **Drag** — to resize and reorder items, and to change the value in Slider, ColorPicker, or TimePicker diff --git a/docs/common_features/using_typescript.md b/docs/common_features/using_typescript.md index 5f35679d..20554c04 100644 --- a/docs/common_features/using_typescript.md +++ b/docs/common_features/using_typescript.md @@ -6,16 +6,18 @@ description: You can learn about TypeScript support in the documentation of the # TypeScript support -The dhtmlxSuite library of version 6.5 and higher lets you work with DHTMLX components faster and more effectively by using TypeScript definitions. +From v6.5, the DHTMLX Suite library includes TypeScript definitions that let you work with DHTMLX components faster and more effectively. ![Snippet Tool editor showing TypeScript autocompletion for a Colorpicker in DHTMLX Suite](/img/guides/typescript1.png) -The library provides a built-in support of Typescript that should work out of the box. +TypeScript support is built in and requires no extra setup. -{{note You can try out the functionality directly in our Snippet Tool.}} +:::info +You can try out the functionality directly in the [Snippet Tool](https://snippet.dhtmlx.com/basic). +::: -### Benefits of using TypeScript +## Benefits of using TypeScript -The main advantage of TypeScript is that the app development becomes much easier, safety, and productive. Checking the types together with autocompletion will help you to avoid common mistakes and, therefore, to write a more stable code. +The main advantage of TypeScript is that app development becomes much easier, safer, and more productive. Type checking and autocompletion help you avoid common mistakes and write more stable code. -Moreover, using TypeScript is a good practice as all modern IDE will provide suggestions and type checking for your code created with DHTMLX. +Using TypeScript is also a good practice: all modern IDEs offer suggestions and type checking for the DHTMLX code you write.