diff --git a/docs/layout/api/cell/layout_cell_header_config.md b/docs/layout/api/cell/layout_cell_header_config.md index ca44dd1c..f9711791 100644 --- a/docs/layout/api/cell/layout_cell_header_config.md +++ b/docs/layout/api/cell/layout_cell_header_config.md @@ -6,21 +6,95 @@ description: You can explore the header config of Layout in the documentation of # header -@short: Optional. Adds a header with text for a cell +@short: Optional. Adds a header with a text or with custom content for a cell -@signature: {'header?: string;'} +#### Usage + +~~~ts +type TCellHeaderTemplate = (cell: ICellConfig) => string | IView; + +header?: string | TCellHeaderTemplate; +~~~ + +The type of the value defines the way the component renders the content of a header: + +- **a string** - defines the text the header shows. The component doesn't interpret HTML tags and displays them as a part of the text +- **a callback function** - defines the way to render HTML content in a header. It takes the following parameter: + + - `cell: ICellConfig` - the configuration object of the cell the header belongs to + + The component calls the callback while it renders the cell and places the returned value into the DOM of the header: + + - *a string with HTML markup* - the component parses the markup and renders it + - *an object of a DHTMLX widget* - an initialized widget, the same object that you pass to the [`attach()`](layout/api/cell/layout_cell_attach_method.md) method of a cell. The name of a component doesn't work here, as the header treats any returned string as HTML + +#### Example + +- a header with a text + +~~~jsx +const layout = new dhx.Layout("layout_container", { + cols: [ + { header: "Cell header" } + ] +}); +~~~ + +- a header with HTML content + +~~~jsx +const layout = new dhx.Layout("layout_container", { + cols: [ + { + id: "orders", + header: cell => `Orders 3 new` + } + ] +}); +~~~ + +- a header with a DHTMLX widget inside + +~~~jsx +const toolbar = new dhx.Toolbar(null, { + data: [ + { id: "add", type: "button", value: "Add", icon: "dxi dxi-plus" } + ] +}); -@example: const layout = new dhx.Layout("layout_container", { cols: [ - { header: "Cell header"} + { header: () => toolbar } ] }); +~~~ @descr: -**Related sample**: [Layout. Header](https://snippet.dhtmlx.com/bxqnzesl) -[comment]: # (@relatedapi: layout/api/cell/layout_cell_headerheight_config.md layout/api/cell/layout_cell_headericon_config.md layout/api/cell/layout_cell_headerimage_config.md) +A *header with custom content* has the following specifics: + +- **events**: to handle clicks and other DOM events of the markup returned by the callback, use the [`on`](layout/api/cell/layout_cell_on_config.md) property of the cell with the selector of the necessary element +- **icon and image**: the [`headerIcon`](layout/api/cell/layout_cell_headericon_config.md) and [`headerImage`](layout/api/cell/layout_cell_headerimage_config.md) options work as well. The cell renders the icon and the image before the content that the callback returns +- **height**: the height of a header adjusts to the size of the custom content. The [`headerHeight`](layout/api/cell/layout_cell_headerheight_config.md) option sets a fixed height for it +- **collapsing**: a [`collapsable`](layout/api/cell/layout_cell_collapsable_config.md) cell shows the collapse/expand icon in a header of any type. A click on the custom content of a header calls no API of the cell, so controls inside the header remain operable. A user collapses and expands the cell by clicking the collapse icon or the free space of the header + +@changelog: the ability to set the property as a callback function was added in v9.4 + +**Related samples**: +- [Layout. Header](https://snippet.dhtmlx.com/bxqnzesl) +- [Layout. HTML content in a cell header](https://snippet.dhtmlx.com/lromzzkx) +- [Layout. Toolbar in a cell header](https://snippet.dhtmlx.com/iyci7xt2?mode=wide) +- [Layout. Custom cell headers in a dashboard](https://snippet.dhtmlx.com/awwc1m4u?mode=wide) + +**Related API**: +- [`attach()`](layout/api/cell/layout_cell_attach_method.md) +- [`on`](layout/api/cell/layout_cell_on_config.md) +- [`headerHeight`](layout/api/cell/layout_cell_headerheight_config.md) +- [`headerIcon`](layout/api/cell/layout_cell_headericon_config.md) +- [`headerImage`](layout/api/cell/layout_cell_headerimage_config.md) -[comment]: # (@related: layout/initialization.md#initialize-layout layout/cell_configuration.md#height-of-a-header-cell) +**Related articles**: +- [Layout initialization](layout/initialization.md#initialize-layout) +- [Custom content in a cell header](layout/cell_configuration.md#custom-content-in-a-cell-header) +- [Height of a header cell](layout/cell_configuration.md#height-of-a-header-cell) diff --git a/docs/layout/api/cell/layout_cell_headericon_config.md b/docs/layout/api/cell/layout_cell_headericon_config.md index 4e0953e8..47799ed9 100644 --- a/docs/layout/api/cell/layout_cell_headericon_config.md +++ b/docs/layout/api/cell/layout_cell_headericon_config.md @@ -21,6 +21,11 @@ const layout = new dhx.Layout("layout_container", { **Related sample**: [Layout. Header](https://snippet.dhtmlx.com/bxqnzesl) -[comment]: # (@related: layout/initialization.md#initialize-layout layout/cell_configuration.md#cellheader) - -[comment]: # (@relatedapi: layout/api/layout_header_config.md layout/api/layout_headerheight_config.md layout/api/layout_headerimage_config.md) +**Related API**: +- [`header`](layout/api/cell/layout_cell_header_config.md) +- [`headerImage`](layout/api/cell/layout_cell_headerimage_config.md) +- [`headerHeight`](layout/api/cell/layout_cell_headerheight_config.md) + +**Related articles**: +- [Layout initialization](layout/initialization.md#initialize-layout) +- [Cell header](layout/cell_configuration.md#cell-header) diff --git a/docs/layout/api/cell/layout_cell_headerimage_config.md b/docs/layout/api/cell/layout_cell_headerimage_config.md index 2a57255b..49e97186 100644 --- a/docs/layout/api/cell/layout_cell_headerimage_config.md +++ b/docs/layout/api/cell/layout_cell_headerimage_config.md @@ -19,6 +19,11 @@ const layout = new dhx.Layout("layout_container", { @descr: -[comment]: # (@related: layout/initialization.md#initialize-layout layout/cell_configuration.md#cellheader) +**Related API**: +- [`header`](layout/api/cell/layout_cell_header_config.md) +- [`headerIcon`](layout/api/cell/layout_cell_headericon_config.md) +- [`headerHeight`](layout/api/cell/layout_cell_headerheight_config.md) -[comment]: # (@relatedapi: layout/api/layout_header_config.md layout/api/layout_headerheight_config.md layout/api/layout_headericon_config.md) +**Related articles**: +- [Layout initialization](layout/initialization.md#initialize-layout) +- [Cell header](layout/cell_configuration.md#cell-header) diff --git a/docs/layout/cell_configuration.md b/docs/layout/cell_configuration.md index bf890d15..9794becb 100644 --- a/docs/layout/cell_configuration.md +++ b/docs/layout/cell_configuration.md @@ -6,11 +6,13 @@ description: You can explore the configuration of a Cell of Layout in the docume # Configuration of a Cell +Each cell of a layout takes a configuration object that defines what the cell shows and how it behaves. The properties of this object set the content and the header of a cell, its size and borders, and the ability of a user to collapse, hide or resize the cell. The sections below go through these settings one by one, while the full list of the available properties is in the [Cell API](layout/api/api_overview.md#cell-api) overview. + ## HTML content -A layout cell can have any HTML content inside it. You can set it with the [](layout/api/cell/layout_cell_html_config.md) attribute in the object of a cell. +A layout cell can have any HTML content inside it. You can set it with the [`html`](layout/api/cell/layout_cell_html_config.md) attribute in the object of a cell. -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { cols: [ { header: "Cell header", html: "Hello world"} @@ -20,23 +22,11 @@ const layout = new dhx.Layout("layout_container", { **Related sample**: [Layout. HTML content](https://snippet.dhtmlx.com/6x76kgyq) -## Hidden cell - -It is possible to add the [](layout/api/cell/layout_cell_hidden_config.md) attribute into the the object of a cell(s) to render a layout with some cells hidden: - -~~~js -const layout = new dhx.Layout("layout_container", { - cols: [ - { header: "Cell header", hidden:true} - ] -}); -~~~ - ## Cell header Each layout cell can have a header with some text that describes the content of this cell. -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { cols: [ { header: "Perfect cell header"} @@ -44,9 +34,9 @@ const layout = new dhx.Layout("layout_container", { }); ~~~ -You can also add an icon or an image into the header of a cell with the help of corresponding attributes - [](layout/api/cell/layout_cell_headericon_config.md) and [](layout/api/cell/layout_cell_headerimage_config.md). +You can also add an icon or an image into the header of a cell with the help of corresponding attributes - [`headerIcon`](layout/api/cell/layout_cell_headericon_config.md) and [`headerImage`](layout/api/cell/layout_cell_headerimage_config.md). -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { cols: [ { header: "Cell header", headerIcon:"/icon.png"} @@ -63,11 +53,11 @@ const layout = new dhx.Layout("layout_container", { **Related sample**: [Layout. Header](https://snippet.dhtmlx.com/bxqnzesl) -## Height of a header cell +### Height of a header cell -You can specify the necessary height of the header of a cell using the [](layout/api/cell/layout_cell_headerheight_config.md) configuration option of the cell: +You can specify the necessary height of the header of a cell using the [`headerHeight`](layout/api/cell/layout_cell_headerheight_config.md) configuration option of the cell: -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { rows: [ { @@ -84,13 +74,105 @@ const layout = new dhx.Layout("layout_container", { **Related sample**: [Layout. Header](https://snippet.dhtmlx.com/bxqnzesl) -If the [](layout/api/cell/layout_cell_header_config.md) property is not set in the config of a cell, the [](layout/api/cell/layout_cell_headerheight_config.md) option will add a header without text for a cell. +If the [`header`](layout/api/cell/layout_cell_header_config.md) property is not set in the config of a cell, the [`headerHeight`](layout/api/cell/layout_cell_headerheight_config.md) option will add a header without text for a cell. + +## Custom content in a cell header + +Besides a text, the header of a cell can contain HTML markup or a DHTMLX widget. For this purpose, set the [`header`](layout/api/cell/layout_cell_header_config.md) property to a callback function. The component calls the function while it renders the cell. The function takes the configuration object of the cell as a parameter and returns the content for the header. + +The type of the value that you set for the `header` property defines the expected behavior: + +- *a string*: the header shows it as plain text, and the component doesn't interpret HTML tags, it displays them as part of the text +- *a callback function*: tells the component that the header supports HTML content + +A cell with a custom header collapses and expands as any other cell, see the [Collapsibility](layout/cell_configuration.md#collapsibility) section. + +### HTML markup in a header + +To render HTML markup in a header, return a string with the necessary tags from the callback: + +~~~jsx +const layout = new dhx.Layout("layout_container", { + cols: [ + { + id: "orders", + header: cell => `Orders 3 new` + } + ] +}); +~~~ + +**Related sample**: [Layout. HTML content in a cell header](https://snippet.dhtmlx.com/lromzzkx) + +### A DHTMLX widget in a header + +To render a DHTMLX component in a header, return an initialized widget, the same object that you pass to the [`attach()`](layout/api/cell/layout_cell_attach_method.md) method of a cell. The name of a component doesn't work here, as the header treats any returned string as HTML: + +~~~jsx +const toolbar = new dhx.Toolbar(null, { + data: [ + { id: "add", type: "button", value: "Add", icon: "dxi dxi-plus" }, + { id: "remove", type: "button", value: "Remove", icon: "dxi dxi-delete" } + ] +}); + +const layout = new dhx.Layout("layout_container", { + cols: [ + { header: () => toolbar } + ] +}); +~~~ + +**Related samples**: +- [Layout. Toolbar in a cell header](https://snippet.dhtmlx.com/iyci7xt2?mode=wide) +- [Layout. Custom cell headers in a dashboard](https://snippet.dhtmlx.com/awwc1m4u?mode=wide) + +### Icon, image and height of a custom header + +The [`headerIcon`](layout/api/cell/layout_cell_headericon_config.md) and [`headerImage`](layout/api/cell/layout_cell_headerimage_config.md) options work with a custom header as well. The cell renders the icon and the image before the content that the callback returns. + +The height of a header adjusts to the size of the custom content. To use a fixed height, set the [`headerHeight`](layout/api/cell/layout_cell_headerheight_config.md) option. + +### Events of the header content + +To handle clicks and other DOM events of the markup that the callback returns, use the [`on`](layout/api/cell/layout_cell_on_config.md) property of the cell with the selector of the necessary element. + +The example below shows how to make a control inside a custom cell header interactive. The `header` callback returns markup with a "Check now" button, and a click on that button rebuilds the content of the cell: + +~~~jsx +// builds the HTML content of the cell +function metrics() { + return `
Checked at ${new Date().toLocaleTimeString()}
`; +} + +const layout = new dhx.Layout("layout_container", { + rows: [ + { + id: "service", + html: metrics(), + header: () => `API service + `, + on: { + click: { + "button": function() { + layout.getCell("service").attachHTML(metrics()); + } + } + } + } + ] +}); +~~~ + +The [`attachHTML()`](layout/api/cell/layout_cell_attachhtml_method.md) call repaints the cell, so the component calls the `header` callback again and renders the header with the current data as well. + +**Related sample**: [Layout. HTML content in a cell header](https://snippet.dhtmlx.com/lromzzkx) ## Cell size -You can easily control and change the size of a cell via the [](layout/api/cell/layout_cell_width_config.md) and [](layout/api/cell/layout_cell_height_config.md) attributes of the object of a cell. +You can easily control and change the size of a cell via the [`width`](layout/api/cell/layout_cell_width_config.md) and [`height`](layout/api/cell/layout_cell_height_config.md) attributes of the object of a cell. -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { rows: [ { @@ -121,9 +203,9 @@ const layout = new dhx.Layout("layout_container", { }); ~~~ -Starting from v7.0, you can define the maximal and minimal sizes for a cell by using its corresponding configuration properties: [](layout/api/cell/layout_cell_maxheight_config.md), [](layout/api/cell/layout_cell_maxwidth_config.md), [](layout/api/cell/layout_cell_minheight_config.md), [](layout/api/cell/layout_cell_minwidth_config.md). +Starting from v7.0, you can define the maximal and minimal sizes for a cell by using its corresponding configuration properties: [`maxHeight`](layout/api/cell/layout_cell_maxheight_config.md), [`maxWidth`](layout/api/cell/layout_cell_maxwidth_config.md), [`minHeight`](layout/api/cell/layout_cell_minheight_config.md), [`minWidth`](layout/api/cell/layout_cell_minwidth_config.md). -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { cols: [ { @@ -137,9 +219,9 @@ const layout = new dhx.Layout("layout_container", { }); ~~~ -{{note Note, that [minWidth](layout/api/cell/layout_cell_minwidth_config.md)/[maxWidth](layout/api/cell/layout_cell_maxwidth_config.md) properties prevent [the width of a cell](layout/api/cell/layout_cell_width_config.md) from being less/greater than minWidth/maxWidth values accordingly. The [minHeight](layout/api/cell/layout_cell_minheight_config.md)/[maxHeight](layout/api/cell/layout_cell_maxheight_config.md) options work in the same way. }} +{{note Note, that [`minWidth`](layout/api/cell/layout_cell_minwidth_config.md)/[`maxWidth`](layout/api/cell/layout_cell_maxwidth_config.md) properties prevent [the width of a cell](layout/api/cell/layout_cell_width_config.md) from being less/greater than minWidth/maxWidth values accordingly. The [`minHeight`](layout/api/cell/layout_cell_minheight_config.md)/[`maxHeight`](layout/api/cell/layout_cell_maxheight_config.md) options work in the same way. }} -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { cols: [ { @@ -155,7 +237,7 @@ As you can see from the code example above, the width of the cell occupies 50% o ### Autosize for cells -Starting with v7.0, you can configure a cell so that its width/ height would automatically adjust to the width/ height of the cell content. For this purpose, you need to set the [width](layout/api/cell/layout_cell_width_config.md)/ [height](layout/api/cell/layout_cell_height_config.md) options to *"content"*: +Starting with v7.0, you can configure a cell so that its width/ height would automatically adjust to the width/ height of the cell content. For this purpose, you need to set the [`width`](layout/api/cell/layout_cell_width_config.md)/ [`height`](layout/api/cell/layout_cell_height_config.md) options to *"content"*: ~~~js {5} const layout = new dhx.Layout("layout_container", { @@ -169,12 +251,40 @@ const layout = new dhx.Layout("layout_container", { }); ~~~ +## Resizability + +To allow resizing of a cell, make use of the [`resizable`](layout/api/cell/layout_cell_resizable_config.md) option in the object of a cell. + +~~~jsx +const layout = new dhx.Layout("layout_container", { + cols: [ + { header: "Cell header", resizable:true} + ] +}); +~~~ + +**Related sample**: [Layout. Collapsable and resizable](https://snippet.dhtmlx.com/f1f49n35) + +{{note Starting from v7.0, you can define the resizing limits by setting necessary values to the [`minWidth`](layout/api/cell/layout_cell_minwidth_config.md)/[`maxWidth`](layout/api/cell/layout_cell_maxwidth_config.md), [`minHeight`](layout/api/cell/layout_cell_minheight_config.md)/[`maxHeight`](layout/api/cell/layout_cell_maxheight_config.md) properties in the config of a cell.}} + +## Hidden cell + +It is possible to add the [`hidden`](layout/api/cell/layout_cell_hidden_config.md) attribute into the the object of a cell(s) to render a layout with some cells hidden: + +~~~jsx +const layout = new dhx.Layout("layout_container", { + cols: [ + { header: "Cell header", hidden:true} + ] +}); +~~~ + ## Collapsibility -There are two attributes of the object of a cell: [](layout/api/cell/layout_cell_collapsable_config.md) and [](layout/api/cell/layout_cell_collapsed_config.md). The first one defines whether a cell can be collapsed and expanded, and the second one checks whether a cell is collapsed during +There are two attributes of the object of a cell: [`collapsable`](layout/api/cell/layout_cell_collapsable_config.md) and [`collapsed`](layout/api/cell/layout_cell_collapsed_config.md). The first one defines whether a cell can be collapsed and expanded, and the second one checks whether a cell is collapsed during the initialization of a layout. -~~~js +~~~jsx const layout = new dhx.Layout("layout_container", { cols: [ { header: "Cell header", collapsable:true, collapsed:false} @@ -182,13 +292,16 @@ const layout = new dhx.Layout("layout_container", { }); ~~~ -**Related sample**: [Layout. Collapsable and resizable](https://snippet.dhtmlx.com/f1f49n35) +A [`collapsable`](layout/api/cell/layout_cell_collapsable_config.md) cell keeps its collapse/expand icon when the header contains custom content. A click on the custom content itself calls no API of the cell, so buttons and other controls inside the header remain operable. A user collapses and expands the cell by clicking the collapse icon or the free space of the header. -**Related sample**: [Layout. Accordion](https://snippet.dhtmlx.com/r2e0y6n7) +**Related samples**: +- [Layout. Collapsable and resizable](https://snippet.dhtmlx.com/f1f49n35) +- [Layout. Accordion](https://snippet.dhtmlx.com/r2e0y6n7) +- [Layout. Toolbar in a cell header](https://snippet.dhtmlx.com/iyci7xt2?mode=wide) ## Progress bar -You can configure a Layout cell so that it would render a progress bar (in other words, a loading spinner) if there is no any component or HTML content attached to the cell. To do that, enable the [progressDefault](layout/api/cell/layout_cell_progressdefault_config.md) attribute in the configuration object of the cell: +You can configure a Layout cell so that it would render a progress bar (in other words, a loading spinner) if there is no any component or HTML content attached to the cell. To do that, enable the [`progressDefault`](layout/api/cell/layout_cell_progressdefault_config.md) attribute in the configuration object of the cell: ~~~js {9,14} const layout = new dhx.Layout("layout_container", { @@ -212,27 +325,11 @@ const layout = new dhx.Layout("layout_container", { Note, as soon as you attach a component or HTML content to the cell, the progress bar will be hidden. -By default, the [progressDefault](layout/api/cell/layout_cell_progressdefault_config.md) attribute is disabled. - -## Resizability - -To allow resizing of a cell, make use of the [](layout/api/cell/layout_cell_resizable_config.md) option in the object of a cell. - -~~~js -const layout = new dhx.Layout("layout_container", { - cols: [ - { header: "Cell header", resizable:true} - ] -}); -~~~ - -**Related sample**: [Layout. Collapsable and resizable](https://snippet.dhtmlx.com/f1f49n35) - -{{note Starting from v7.0, you can define the resizing limits by setting necessary values to the [minWidth](layout/api/cell/layout_cell_minwidth_config.md)/[maxWidth](layout/api/cell/layout_cell_maxwidth_config.md), [minHeight](layout/api/cell/layout_cell_minheight_config.md)/[maxHeight](layout/api/cell/layout_cell_maxheight_config.md) properties in the config of a cell.}} +By default, the [`progressDefault`](layout/api/cell/layout_cell_progressdefault_config.md) attribute is disabled. ## Setting borders for cells -By default, there is no space and borders between cells inside a layout and the cells look like they are merged. Starting from v7.0, it is possible to split the cells by adding borders or space between them via the [](layout/api/cell/layout_cell_type_config.md) configuration property of a Layout cell: +By default, there is no space and borders between cells inside a layout and the cells look like they are merged. Starting from v7.0, it is possible to split the cells by adding borders or space between them via the [`type`](layout/api/cell/layout_cell_type_config.md) configuration property of a Layout cell: ~~~js {2} const layout = new dhx.Layout("layout_container", { diff --git a/docs/layout/features.md b/docs/layout/features.md index 1a6378be..67045335 100644 --- a/docs/layout/features.md +++ b/docs/layout/features.md @@ -47,6 +47,7 @@ In this section you can find out how to configure the size and visibility of cel | [Making a cell resizable](layout/cell_configuration.md#resizability) | Learn how to configure the ability to change the size of a cell by dragging its borders ([Example](https://snippet.dhtmlx.com/f1f49n35)) | | [Making cells hidden](layout/cell_configuration.md#hidden-cell) | Learn how to render a layout with some hidden cells | | [Adding the header to a cell](layout/cell_configuration.md#cell-header) | Learn how to add a header for a cell ([Example](https://snippet.dhtmlx.com/bxqnzesl)) | +| [Adding custom content to a cell header](layout/cell_configuration.md#custom-content-in-a-cell-header) | Learn how to render HTML markup or a DHTMLX widget in the header of a cell ([Example](https://snippet.dhtmlx.com/lromzzkx)) | | [Configuring content alignment](layout/api/cell/layout_cell_align_config.md) | Learn how to set the alignment of content inside a cell ([Example](https://snippet.dhtmlx.com/4w1033c9)) | | [Configuring paddings](layout/api/cell/layout_cell_padding_config.md) | Learn how to configure the distance between a cell and the Layout border ([Example](https://snippet.dhtmlx.com/tk6tpwwv)) | | [Initializing a collapsed cell](layout/cell_configuration.md#collapsibility) | Learn how to initialize a collapsed cell and provide the ability to expand it ([Example 1](https://snippet.dhtmlx.com/f1f49n35), [Example 2](https://snippet.dhtmlx.com/r2e0y6n7)) |