Merge pull request #30 from DHTMLX/mr-next-editbar-basic-controls-4537

Editbar basic controls

docs/guides/diagram_editor/editbar/basic_controls.md

@@ -6,6 +6,36 @@ description: You can learn about the Basic controls of Editbar in the documentat
 
 # Basic controls
 
-Здесь мы детально расписываем настройки для каждого базового контрола и даем ссылку на [Editbar configuration](guides/diagram_editor/editbar/configuration.md) - где даем разные сценарии настройки Editbar (сценарии будут дополняться по запросу пользователей)
+You can use basic controls of Editbar standalone or create complex controls on their base. Below you'll find the list of basic controls. Check the corresponding section to view the detailed description of configuration properties for each control. 
+
+:::info
+Refer to the [Editbar configuration](guides/diagram_editor/editbar/configuration.md) guide for more information about configuring!
+:::
+
+## Overview of Editbar basic controls
+
+| Name                                 							  | Description                                 					  |
+| :-------------------------------------------------------------- | :---------------------------------------------------------------- |
+| [](guides/diagram_editor/editbar/basic_controls/avatar.md)      | @getshort(guides/diagram_editor/editbar/basic_controls/avatar.md) |
+| [](guides/diagram_editor/editbar/basic_controls/button.md)      | @getshort(guides/diagram_editor/editbar/basic_controls/button.md) |
+| [](guides/diagram_editor/editbar/basic_controls/checkbox.md)     | @getshort(guides/diagram_editor/editbar/basic_controls/checkbox.md) |
+| [](guides/diagram_editor/editbar/basic_controls/checkboxgroup.md)| @getshort(guides/diagram_editor/editbar/basic_controls/checkboxgroup.md)|
+| [](guides/diagram_editor/editbar/basic_controls/colorpicker.md)| @getshort(guides/diagram_editor/editbar/basic_controls/colorpicker.md)|
+| [](guides/diagram_editor/editbar/basic_controls/combo.md)| @getshort(guides/diagram_editor/editbar/basic_controls/combo.md)|
+| [](guides/diagram_editor/editbar/basic_controls/container.md)| @getshort(guides/diagram_editor/editbar/basic_controls/container.md)|
+| [](guides/diagram_editor/editbar/basic_controls/datepicker.md)| @getshort(guides/diagram_editor/editbar/basic_controls/datepicker.md)|
+| [](guides/diagram_editor/editbar/basic_controls/fieldset.md)| @getshort(guides/diagram_editor/editbar/basic_controls/fieldset.md)|
+| [](guides/diagram_editor/editbar/basic_controls/input.md)| @getshort(guides/diagram_editor/editbar/basic_controls/input.md)|
+| [](guides/diagram_editor/editbar/basic_controls/radiogroup.md)| @getshort(guides/diagram_editor/editbar/basic_controls/radiogroup.md)|
+| [](guides/diagram_editor/editbar/basic_controls/select.md)| @getshort(guides/diagram_editor/editbar/basic_controls/select.md)|
+| [](guides/diagram_editor/editbar/basic_controls/slider.md)| @getshort(guides/diagram_editor/editbar/basic_controls/slider.md)|
+| [](guides/diagram_editor/editbar/basic_controls/spacer.md)| @getshort(guides/diagram_editor/editbar/basic_controls/spacer.md)|
+| [](guides/diagram_editor/editbar/basic_controls/textarea.md)| @getshort(guides/diagram_editor/editbar/basic_controls/textarea.md)|
+| [](guides/diagram_editor/editbar/basic_controls/timepicker.md)| @getshort(guides/diagram_editor/editbar/basic_controls/timepicker.md)|
+| [](guides/diagram_editor/editbar/basic_controls/toggle.md)| @getshort(guides/diagram_editor/editbar/basic_controls/toggle.md)|
+| [](guides/diagram_editor/editbar/basic_controls/togglegroup.md)| @getshort(guides/diagram_editor/editbar/basic_controls/togglegroup.md)|
+
+
+
+
 
-Задача: https://tracker.webix.io/agiles/87-97/88-554?issue=DHX-4537

docs/guides/diagram_editor/editbar/basic_controls/avatar.md

@@ -0,0 +1,148 @@
+---
+sidebar_label: Avatar!!
+title: Editbar Basic Controls - Avatar 
+description: You can explore the Avatar control of Editbar in the documentation of the the DHTMLX JavaScript Diagram 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.
+---
+
+# Avatar
+
+@short: The basic control for uploading of images.
+
+![Avatar control](../../../../assets/editbar-basic-controls/avatar.png)
+
+## Usage
+
+~~~jsx
+{
+    type: "avatar",
+    key?: string, // "img" by default
+    wrap?: boolean, // false by default
+    target?: string,
+
+    hidden?: boolean, // false by default
+    disabled?: boolean, // false by default
+    readOnly?: boolean, // false by default
+
+    removeIcon?: boolean, // true by default 
+    circle?: boolean, // false by default
+    icon?: string,
+    placeholder?: string,
+    preview?: string,
+    alt?: string,
+    size?: "small" | "medium" | "large" | number, // "medium" by default
+
+    css?: string,
+    width?: string | number | "content", // "content" by default
+    height?: string | number | "content", // "content" by default
+    padding?: string | number,
+
+    // for `wrap:true` check the label properties for the Fieldset
+    label?: string,
+    labelWidth?: string | number,
+    labelPosition?: "left" | "top", // "top" by default
+
+    accept?: string, // "image/*" by default
+    fieldName?: string, // "file" by default
+    autosend?: boolean, // false by default
+    params?: { [key: string]: any },
+    headerParams?: { [key: string]: any },
+    updateFromResponse?: boolean,  // true by default
+
+    // service properties and methods 
+    $on?: { [eventName: string]: function },
+    $handler?: function,
+    $setValue?: function,
+    $layout?: function
+~~~
+
+## Description
+
+### Basic properties
+
+- `type` - (required) the type of a control. Set it to *"avatar"*
+- `key` - (optional) the name of the specified/modified property in the object of a Diagram item. *"img"* by default
+- `wrap` - (optional) allows displaying the external wrapping. *false* by default
+- `target` - (optional) sets an URL to the server-side script that will process file upload, the property is required when an image is sent to the server via the control
+:::note
+While loading an image and sending it to the server via the `target` property, note that the [*value* object](https://docs.dhtmlx.com/suite/form/api/avatar/api_avatar_properties/#description) will be sent to the server. The file itself will be recorded in the dataset in the *base64* format. You can redefine this logic using the [service methods](#service-properties-and-methods). 
+:::
+- `hidden` - (optional) defines whether a control is hidden. *false* by default
+- `disabled` - (optional) defines whether a control is enabled (*false*) or disabled (*true*). *false* by default
+- `readOnly` - (optional) sets the readonly mode for the control. *false* by default
+- `removeIcon` - (optional) enables the possibility to clear the control by means of the UI. *true* by default
+- `circle` - (optional) sets the mode of displaying the control with rounded corners. *false* by default
+- `icon` - (optional) allows setting the CSS class of an icon when there is no image uploaded, doesn't work together with the `preview` property
+- `placeholder` - (optional) allows setting a text to be visible when there is no image uploaded, doesn't work together with the `preview` property
+- `preview` - (optional) specifies the absolute path to the preview image. The preview image is visible, when an image is not uploaded
+- `alt` - (optional) sets the attribute of the <img> tag - an alternative text when there is no image uploaded
+- `size` - (optional) allows setting one of the three basic control's sizes: *"small"* | *"medium"* | *"large"* , or applying a custom size in px. *"medium"* by default
+- `css` - (optional) adds style classes to a control
+- `width` - (optional) the width of a control. *"content"* by default
+- `height` - (optional) the height of a control. *"content"* by default
+- `padding` - (optional) sets padding between a cell and a border of the Avatar control
+- `label` - (optional) specifies a label for the control
+- `labelWidth` - (optional) sets the label width of the control
+- `labelPosition` - (optional) defines the position of a label: *"left"* | *"top"*. *"top"* by default
+- `accept` - (optional) allows specifying the type/extension of the selected file. *"image/*"* by default. [Check details](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers)
+- `fieldName` - (optional) sets the file field name in the form data sent to the server. *"file"* by default
+- `autosend` - (optional) enables/disables automatic sending of an added file. *false* by default
+- `params` - (optional) adds extra parameters for sending an XMLHttpRequest
+- `headerParams` - (optional) provides additional parameters for Request Headers
+- `updateFromResponse` - (optional) updates file attributes with the data from the server response. *true* by default
+
+### Service properties and methods
+
+:::warning
+Note that it's highly not recommended to redefine the service properties and methods for the default types of controls, since it may cause breaks in their functionality. 
+:::
+
+- `$on` - (optional) - allows setting an event listener. The object has the following properties:
+    - `eventName`  - a callback function which is called with the following parameters:
+        - `object` - an object with the following properties:
+            - `control` - the [Avatar](https://docs.dhtmlx.com/suite/form/avatar/) Form control
+            - `editor` - the object of the Diagram Editor
+            - `id` - the id of a Diagram item 
+        - `arguments` - (optional) - the [original event arguments](https://docs.dhtmlx.com/suite/category/form-avatar-events/)
+- `$handler` - (optional) - a callback function that allows handling actions on firing the `change` event of the [Avatar](https://docs.dhtmlx.com/suite/form/avatar/) Form control and the `change` event of DataCollection. Called with the following parameter:
+    - `object` - an object with the following properties:
+        - `id` - the id of a Diagram item 
+        - `key` - the name of the specified/modified property in the object of a Diagram item 
+        - `editor` - the object of the Diagram Editor
+        - `control` - the object of the [Avatar](https://docs.dhtmlx.com/suite/form/avatar/) Form control the component is built on
+        - `value` - the new value of the [Avatar](https://docs.dhtmlx.com/suite/form/avatar/) Form control
+- `$setValue` - (optional) - a callback function that allows setting the value of the [Avatar](https://docs.dhtmlx.com/suite/form/avatar/) Form control on initialization of a control and on changing the value in DataCollection. Called with the following parameter:
+    - `object` - an object with the following properties:
+        - `editor` - the object of the Diagram Editor
+        - `control` - the object of the [Avatar](https://docs.dhtmlx.com/suite/form/avatar/) Form control the component is built on
+        - `value` - the value of a Diagram item 
+- `$layout` - (optional) - a callback function that allows setting the structure of a control. Returns the configuration of the [Avatar](https://docs.dhtmlx.com/suite/form/avatar/) Form control. Called with the following parameter:
+    - `object` - the configuration of the control without service properties
+
+## Example
+
+~~~jsx {7-19}
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        editbar: {
+            properties: {
+                "img-card": [
+                    {
+                        type: "avatar",
+                        accept: "image/*",
+                        fieldName: "file",
+                        target: "https://docs.dhtmlx.com/suite/backend/upload",
+                        params: {
+                            "firstCustomParam": "customValue",
+                        },
+                        headerParams: {
+                            "firstCustomParam": "customValue",
+                        },
+                        autosend: true,
+                    },
+                ]
+            }
+        }
+    }
+});
+~~~

docs/guides/diagram_editor/editbar/basic_controls/button.md

@@ -0,0 +1,104 @@
+---
+sidebar_label: Button!!
+title: Editbar Basic Controls - Button 
+description: You can explore the Button control of Editbar in the documentation of the the DHTMLX JavaScript Diagram 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.
+---
+
+# Button 
+
+@short: The basic button control that can have an icon.
+
+![Button control](../../../../assets/editbar-basic-controls/button.png)
+
+## Usage
+
+~~~jsx
+{
+    type: "button",
+    text?: string,
+
+    css?: string,
+    disabled?: boolean, // false by default
+    hidden?: boolean, // false by default
+    height?: string | number | "content", // "content" by default
+    width?: string | number | "content", // "content" by default
+    padding?: string | number,
+
+    // button view
+    circle?: boolean, // false by default
+    color?: "danger" | "secondary" | "primary" | "success", // "primary" by default
+    full?: boolean, // false by default
+    icon?: string,
+    size?: "small" | "medium", // "medium" by default
+    view?: "flat" | "link", // "flat" by default
+
+    // service properties and methods 
+    $on?: { [eventName: string]: function },
+    $layout?: function
+}
+~~~
+
+## Description
+
+### Basic properties
+
+- `type` - (required) the type of a control. Set it to *"button"*
+- `text` - (optional) the text label of a button
+- `css`	- (optional) adds style classes to a control
+- `disabled` - (optional) defines whether a control is enabled (*false*) or disabled (*true*). *false* by default
+- `hidden` - (optional) defines whether a control is hidden. *false* by default
+- `height` - (optional) the height of a control. *"content"* by default
+- `width` - (optional) the width of a control. *"content"* by default
+- `padding` - (optional) sets padding between a cell and a border of a button control
+- `circle` - (optional) makes the corners of a button round. *false* by default
+- `color` - (optional) defines the color scheme of a button: *"danger"* | *"secondary"* | *"primary"* | *"success"*. *"primary"* by default
+- `full` - (optional) extends a button to the full width of the Editbar. *false* by default
+- `icon` - (optional) sets the CSS class of an icon displayed inside the button
+- `size` - (optional) defines the size of a button: *"small"* | *"medium"*. *"medium"* by default
+- `view` - (optional) defines the look of a button: *"flat"* | *"link"*. *"flat"* by default
+
+### Service properties and methods
+
+:::warning
+Note that it's highly not recommended to redefine the service properties and methods for the default types of controls, since it may cause breaks in their functionality. 
+:::
+
+- `$on` - (optional) - allows setting an event listener. The object has the following properties:
+    - `eventName`  - a callback function which is called with the following parameters:
+        - `object` - an object with the following properties:
+            - `control` - the [Button](https://docs.dhtmlx.com/suite/form/button/) Form control
+            - `editor` - the object of the Diagram Editor
+            - `id` - the id of a Diagram item 
+        - `arguments` - (optional) - the [original event arguments](https://docs.dhtmlx.com/suite/category/form-button-events/)
+- `$layout` - (optional) - a callback function that allows setting the structure of a control. Returns the configuration of the [Button](https://docs.dhtmlx.com/suite/form/button/) Form control. Called with the following parameter:
+    - `object` - the configuration of a control without service properties
+
+## Example
+
+~~~jsx {8-20}
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        editbar: {
+            properties: {
+                $shape: [
+                    { type: "input", label: "Text", placeholder: "Push the button", key: "text" },
+                    {
+                        type: "button",
+                        full: true,
+                        text: "Change shape text",
+                        color: "danger",
+                        $on: {
+                            click: ({ id, editor }) => {
+                                editor.diagram.data.update(id, {
+                                    text: "New text",
+                                });
+                            },
+                        }
+                    },
+                ]
+            }
+        }
+    }
+});
+~~~