Merge pull request #15 from DHTMLX/mr-next-shapebar-api-4328

Update Shapebar properties

docs/api/diagram_editor/shapebar/config/css_property.md

@@ -0,0 +1,45 @@
+---
+sidebar_label: css!!
+title: css Property of Shapebar
+description: You can learn about the css property of Shapebar in the documentation of 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 Diagram.
+---
+
+# css
+
+### Description
+
+@short: Optional. Allows applying custom CSS classes to adjust the shapebar appearance
+
+### Usage
+
+~~~js
+css?: string;
+~~~
+
+### Example
+
+~~~html {6}
+<script>
+    const editor = new dhx.DiagramEditor("editor_container", {
+        type: "default",
+        view: {
+            shapebar: {
+                css: "custom_style"
+            }
+        }
+    });
+</script>
+
+<style>
+    .custom_style {
+        background-color: var(--dhx-background-primary);
+        font-size: var(--dhx-font-size-large);
+    }
+</style>
+~~~
+
+**Related article:** TODO
+
+**Change log**: 
+
+The property was added in v6.0

docs/api/diagram_editor/shapebar/config/preview_property.md

@@ -0,0 +1,85 @@
+---
+sidebar_label: preview!!
+title: preview Property of Shapebar
+description: You can learn about the preview property of Shapebar in the documentation of 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 Diagram.
+---
+
+# preview
+
+### Description
+
+@short: Optional. An object that configures the preview of items
+
+### Usage
+
+~~~js
+preview?:{
+    scale?: number,
+    gap?: string | number
+}
+~~~
+
+### Parameters
+
+- `scale` - (optional) defines the scale of items rendered in the shapebar of the editor
+- `gap` - (optional) specifies the space between the items rendered in the shapebar
+
+### Default config
+
+~~~js
+preview: {
+    scale: 0.5,
+    gap: "6px 8px"
+    // sets 6px gap for the top and bottom sides and 8px gap for the right and left sides
+}
+~~~
+
+### Example
+
+~~~js
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        shapebar: {
+            preview: {
+               scale: 0.65,
+               gap: 8
+            }
+        }
+    }
+});
+~~~
+
+### Details
+
+The values of the **gap** and **scale** properties can be redefined for a separate shape via the **gap** and **scale** attributes of the [preview](../../../../../shapes/configuration_properties/#properties-specific-for-the-default-mode) property of the shape object:
+
+~~~js
+const defaults = {
+    rectangle: {
+        preview: {
+            scale: 0.72, 
+            gap: 8
+        }
+    }
+}
+
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        shapebar: {
+           preview: {
+               scale: 0.65,
+               gap: 2
+            }
+        }
+    },
+    defaults        
+});
+~~~
+
+**Related article:** TODO
+
+**Change log**: 
+
+The property was added in v6.0

docs/api/diagram_editor/shapebar/config/sections_property.md

@@ -0,0 +1,174 @@
+---
+sidebar_label: sections!!
+title: sections Property of Shapebar
+description: You can learn about the sections property of Shapebar in the documentation of 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 Diagram.
+---
+
+# sections
+
+TODO (update link)<br>
+The [default sections of the shapebar](../../../guides/diagram_editor/left_panel/#default-sections) are: *Shapes*, *Groups*, *Swimlanes*.
+
+Using the **sections** property you can change the structure of the shapebar and display the necessary items.
+
+### Description
+
+@short: Optional. An object which specifies sections of items that will be shown in the shapebar of the editor
+
+### Usage
+
+~~~js
+sections?: {
+    [name: string]: (obj | string)[]
+}
+~~~
+
+### Parameters
+
+The `sections` object can contain a set of *key:value* pairs where:
+- `key` - the name of a section specified by a user
+- `value` - an array which can include:
+  - an object with one *key:value* pair for rendering a <span id="basic">basic set of shapes</span>. The list of available pairs is given below:
+    - `{flowShapes: true}` - (optional) displays all available types of the [Flow-chart](../../../../../shapes/default_shapes/#shapes-overview) shapes 
+    - `{org: true}` - (optional) displays Org shapes: the "card" and "img-card" shape types
+    - `{group: true}` - (optional) displays a basic set of Groups
+    - `{swimlane: true}` - (optional) displays a basic set of Swimlanes
+  - a string value with a specific type of the item to be rendered in the section (for example, "text", "topic", etc.)
+  - an object with several *key:value* pairs for [redefining the default properties of any shape](#customization) 
+
+### Example
+
+~~~js
+const editor = new dhx.DiagramEditor("editor_container", {
+    shapeSections: {
+        "Swimlane": [{ swimlane: true }],
+        "Groups": [{ group: true }],   
+        "Flowchart shapes": [{ flowShapes: true }],
+        "Org shapes, text, topic": [{ org: true }, "text", "topic"]
+    }
+});
+~~~
+
+### Details
+
+Depending on the chosen elements, the configuration of items of a particular section can be the following:
+
+1. Rendering of basic sections
+
+You can render [a basic set of shapes](#basic) using the `sections` configuration object. For example:
+
+~~~js
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        shapebar: {
+            sections: {
+                "Base flow shapes": [{ flowShapes: true }],
+                "Base org cards": [{ org: true }],
+                "Base groups": [{ group: true }],
+                "Base swimlane": [{ swimlane: true }]
+            }
+        }
+    }
+});
+~~~
+
+2. Specifying items with the help of string literals
+
+You can render Shapebar items by specifying the types of shapes with the help of string literals. Check the example below:
+
+~~~js
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        shapebar: {
+            sections: {
+                "Custom section": ["custom_shape"],
+                "Other shapes": ["text", "topic", "circle"]
+            }
+        }
+    }
+});
+~~~
+
+3. <p id="customization">Redefining basic configurations</p>
+
+Another option is to redefine basic properties of any shape and render it with the necessary parameters. The example below shows rendering of a shape of the `circle` type with various text and color settings:
+
+~~~js
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        shapebar: {
+            sections: {
+                "Circles": [
+                    {
+                        type: "circle",
+                        fill: "#fcba03",
+                        text: "Orange"
+                    },
+                    {
+                        type: "circle",
+                        fill: "#03d7fc",
+                        text: "Blue"
+                    },
+                    {
+                        type: "circle",
+                        fill: "#03fc88",
+                        text: "Green"
+                    }
+                ]
+            }
+        }
+    }
+});
+~~~
+
+You can reconfigure any type of shapes in such a way. 
+
+4. Combining different types of items in a section
+
+If your project presupposes usage of various elements, you can create sections with mixed types of items in the Shapebar. Check the following example:
+
+~~~js
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        shapebar: {
+            sections: {
+                "Base flow shapes": [{ flowShapes: true }, "text", "topic"],
+                "Circles": [
+                     "circle",
+                    {
+                        type: "circle",
+                        fill: "#fcba03",
+                        text: "Orange"
+                    },
+                    {
+                        type: "circle",
+                        fill: "#03d7fc",
+                        text: "Blue"
+                    },
+                    {
+                        type: "circle",
+                        fill: "#03fc88",
+                        text: "Green"
+                    }
+                ]
+            }
+        }
+    }
+});
+~~~
+
+TODO (update the links to the article and snippets)
+
+**Related article**:  [Left Panel](../../../guides/diagram_editor/left_panel/)
+
+**Related samples**:
+- [Diagram editor. Default mode. Setting the section order in the left panel](https://snippet.dhtmlx.com/7747cx7b)
+- [Diagram editor. Default mode. Left panel customization](https://snippet.dhtmlx.com/2z0a18oz)
+
+**Change log**: 
+
+The property was added in v6.0

docs/api/diagram_editor/shapebar/config/show_property.md

@@ -0,0 +1,42 @@
+---
+sidebar_label: show!!
+title: show Property of Shapebar
+description: You can learn about the show property of Shapebar in the documentation of 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 Diagram.
+---
+
+# show
+
+### Description
+
+@short: Optional. Defines whether a shapebar with custom settings is displayed on initialization of the Diagram Editor
+
+### Usage
+
+~~~js
+show?: boolean;
+~~~
+
+### Default config
+
+~~~js
+show: true 
+~~~
+
+### Example
+
+~~~js
+const editor = new dhx.DiagramEditor("editor_container", {
+    type: "default",
+    view: {
+        shapebar: {
+            show: false, // true by default
+        }
+    }
+});
+~~~
+
+**Related article:** TODO
+
+**Change log**: 
+
+The property was added in v6.0