diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index 70a66c2..9af6d36 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -6,34 +6,35 @@ description: You can learn about the configuration in the documentation of the D # Configuration -You can configure Pivot appearance and functionality via the corresponding API, namely, you can configure the Pivot table elements and the configuration panel. The available parameters will allow you to: +Configure Pivot appearance and functionality through the API. The following properties are available: -- define the structure of the Pivot table and how data is aggregated via the [`config`](/api/config/config-property) property -- change the table configuration on the fly via the [`render-table`](/api/events/render-table-event) event -- configure the look of the Pivot table via the [`tableShape`](/api/config/tableshape-property) property -- configure the look and behavior of the Pivot columns via the [`columnShape`](/api/config/columnshape-property) property -- configure the look and behavior of headers in the Pivot table via the [`headerShape`](/api/config/headershape-property) property -- control the visibility of the configuration panel via the [`configPanel`](/api/config/configpanel-property) property -- apply the desired locale via the [`setLocale()`](/api/methods/setlocale-method) method (see the [Localization](/guides/localization) section) -- load data and fields via the corresponding [`data`](/api/config/data-property) and [`fields`](/api/config/fields-property) properties -- define how data should be modified before it's applied via the [`predicates`](/api/config/predicates-property) property -- define custom mathematical methods for data aggregation via the [`methods`](/api/config/methods-property) property -- control the maximum limit for the number of rows and columns in the final dataset via the [`limits`](/api/config/limits-property) property +- [`config`](/api/config/config-property) — define the structure of the Pivot table and how data is aggregated +- [`render-table`](/api/events/render-table-event) — change the table configuration on the fly +- [`tableShape`](/api/config/tableshape-property) — configure the look of the Pivot table +- [`columnShape`](/api/config/columnshape-property) — configure the look and behavior of Pivot columns +- [`headerShape`](/api/config/headershape-property) — configure the look and behavior of headers +- [`configPanel`](/api/config/configpanel-property) — control the visibility of the configuration panel +- [`setLocale()`](/api/methods/setlocale-method) — apply a locale (see [Localization](/guides/localization)) +- [`data`](/api/config/data-property) and [`fields`](/api/config/fields-property) — load data and fields +- [`predicates`](/api/config/predicates-property) — define how data is modified before aggregation +- [`methods`](/api/config/methods-property) — define custom mathematical methods for data aggregation +- [`limits`](/api/config/limits-property) — control the maximum number of rows and columns in the dataset +- [`readonly`](/api/config/readonly-property) — enable or disable the read-only mode -All instructions about working with data see here: [Working with data](/guides/working-with-data) +For data operations, see [Working with data](/guides/working-with-data). -You can configure and/or customize the following elements of the Pivot table: +Configure the following elements of the Pivot table: - columns and rows - headers and footers - cells -- the table sizes +- table sizes -## Resizing the table +## Resize the table -You can change the size of the table rows and columns, header and footer using the [`tableShape`](/api/config/tableshape-property) property. +Use the [`tableShape`](/api/config/tableshape-property) property to change the size of table rows, columns, headers, and footers. -The next sizes are applied by default: +The following sizes apply by default: ~~~jsx const sizes = { @@ -44,7 +45,7 @@ const sizes = { }; ~~~ -Example: +The example below sets custom row and header sizes: ~~~jsx {4-11} const table = new pivot.Pivot("#root", { @@ -79,19 +80,73 @@ const table = new pivot.Pivot("#root", { To set the width of specific column(s), apply the `width` parameter of the [columnShape property](/api/config/columnshape-property). ::: -## Autosizing columns to content +## Show total rows and columns -The widget allows setting the minimum width value for all columns and it also enables sizing for the table data only, the table header or combined auto sizing. To configure all these autosizing settings, you should apply the `autoWidth` parameter of the [`columnShape`](/api/config/columnshape-property) property. +Use the `totalRow` and `totalColumn` parameters of the [`tableShape`](/api/config/tableshape-property) property to add rows and columns with aggregated totals. -All parameters of `autoWidth` are optional and for detailed description of each parameter refer to the [columnShape](/api/config/columnshape-property) property. +- Set `totalRow` to `true` to add a footer row with total values. Set `totalRow` to `"sumOnly"` to include only sum totals. +- Set `totalColumn` to `true` to add a total column with total values for rows. Set `totalColumn` to `"sumOnly"` to include only sum totals. -- use the `columns` parameter to define if the width of columns should be calculated automatically and which columns will be affected -- use the `auto` parameter to adjust the width to the header or cell content (or both) -- use `maxRows` to specify how many data rows will be applied to detect the size of a column; by default 20 rows are used +The following code snippet enables both the total row and total column: -If `firstOnly` is set to **true** (default), each field of the same data is analyzed only once to calculate the column width. In case of multiple columns based on the same data (e.g., the *oil* field with the *count* operation and the *oil* field with the *sum* operation), only data in the first one will be analyzed and the others will inherit this width. +~~~jsx {4-5} +const widget = new pivot.Pivot("#pivot", { + fields, + data: dataset, + tableShape: { + totalRow: true, + totalColumn: true, + }, + config: { + rows: ["state"], + columns: ["product_line"], + values: [ + { + field: "profit", + method: "sum" + } + ] + } +}); +~~~ + +## Hide duplicate row values + +Set the `cleanRows` parameter of the [`tableShape`](/api/config/tableshape-property) property to `true` to hide duplicate values in scale columns (default: `false`). + +The following code snippet enables the `cleanRows` parameter: + +~~~jsx {4-6} +const widget = new pivot.Pivot("#pivot", { + fields, + data: dataset, + tableShape: { + cleanRows: true, + }, + config: { + rows: ["state", "product_type"], + columns: [], + values: [ + { + field: "profit", + method: "sum" + } + ] + } +}); +~~~ + +## Autosize columns to content + +Use the `autoWidth` parameter of the [`columnShape`](/api/config/columnshape-property) property to set the minimum column width and configure auto-sizing for table data, headers, or both. All parameters of `autoWidth` are optional. For a detailed description, see the [`columnShape`](/api/config/columnshape-property) property. + +- use the `columns` parameter to define which columns calculate width automatically +- use the `auto` parameter to adjust the width to the header, cell content, or both +- use `maxRows` to specify how many data rows are used to detect column size; 20 rows apply by default + +If `firstOnly` is `true` (default), each data field is analyzed only once to calculate the column width. For multiple columns based on the same data (for example, the `oil` field with `count` and the `oil` field with `sum`), only the first column's data is analyzed; the others inherit that width. -Example: +The example below configures `autoWidth` for specific columns: ~~~jsx {18-30} const table = new pivot.Pivot("#root", { @@ -127,13 +182,13 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Applying templates to cells +## Apply templates to cells -### Adding templates via tableShape +### Add templates via tableShape -To set a template to cells, use the `templates` parameter of the [`tableShape`](/api/config/tableshape-property) property. It's an object where each key is a field id and the value is a function that returns a string. All columns based on the specified field will have the related template applied. +Use the `templates` parameter of the [`tableShape`](/api/config/tableshape-property) property to set cell templates. Each key is a field ID, and the value is a function that returns a string. All columns based on the specified field apply the template. -In the example below we apply the template to the *state* cells to show the combined name of a state (the full name and abbreviation). +The example below applies a template to `state` cells to display the full state name and abbreviation. ~~~jsx {10-15} const states = { @@ -172,11 +227,11 @@ const table = new pivot.Pivot("#root", { }); ~~~ -### Adding a template via the template helper +### Add a template via the template helper -You can insert HTML content to table cells via the [`pivot.template`](/api/helpers/template) helper by defining a template as a `cell` property of the `column` object. You need to apply the template right before the table renders, which is done by intercepting the [render-table](/api/events/render-table-event) event using the [api.intercept()](/api/internal/intercept-method) method. +Insert HTML content into table cells via the [`pivot.template`](/api/helpers/template) helper by defining a template as the `cell` property of the `column` object. Apply the template just before the table renders by intercepting the [`render-table`](/api/events/render-table-event) event with [`api.intercept()`](/api/internal/intercept-method). -The example shows how you can add icons (star or flag icon) to body cells based on their field (id, user_score): +The example below adds icons to body cells based on the field (`id`, `user_score`): ~~~js function cellTemplate(value, method, row, column) { @@ -205,7 +260,7 @@ function scoreTemplate(value) { widget.api.intercept("render-table", ({ config: tableConfig }) => { tableConfig.columns = tableConfig.columns.map((c) => { if (c.area === "rows") { - // Apply a template to column cells from the "rows" area + // apply a template to column cells from the "rows" area c.cell = pivot.template(({ value, method, row, column }) => cellTemplate(value, method, row, column)); } return c; @@ -213,19 +268,18 @@ widget.api.intercept("render-table", ({ config: tableConfig }) => { }); ~~~ -## Applying templates to headers +## Apply templates to headers -### Adding templates via headerShape +### Add templates via headerShape -To define the format of text in headers, apply the `template` parameter of the [`headerShape`](/api/config/headershape-property) property. The parameter is the function that: +Use the `template` parameter of the [`headerShape`](/api/config/headershape-property) property to define the format of header text. The parameter is a function that: -- takes the field id, label and sublabel (the name of a method if any is applied) -- returns the processed value +- takes the field id, label, and sublabel (the method name, if applied) +- returns the processed value -A default template is as follows: *template: (label, id, subLabel) => label + (subLabel ? `(${subLabel})` : "")*. By default, for the fields applied as values the label and method are shown (e.g., *Oil(count)*). -If no other template is applied to columns, the value of the `label` parameter is displayed. If any [`predicates`](/api/config/predicates-property) template is applied, it will override the template of the `headerShape` property. +The default template is: `template: (label, id, subLabel) => label + (subLabel ? "(${subLabel})" : "")`. For fields used as values, the label and method appear by default (for example, *Oil(count)*). If no other template applies, the `label` value displays. A [`predicates`](/api/config/predicates-property) template overrides the `headerShape` template. -In the example below for the **values** fields the header will display the label, the method name (subLabel) and converts the result to lowercase (e.g., *profit (sum)*): +The example below displays the label and method name (`subLabel`) for **values** fields, converted to lowercase (for example, *profit (sum)*): ~~~jsx {3-6} new pivot.Pivot("#pivot", { @@ -253,14 +307,14 @@ new pivot.Pivot("#pivot", { }); ~~~ -### Adding templates via the template helper +### Add templates via the template helper -You can insert HTML content to header cells via the [`pivot.template`](/api/helpers/template) helper by defining a template as a `cell` property of the header cell object. You need to apply the template right before the table renders, which is done by intercepting the [render-table](/api/events/render-table-event) event using the [api.intercept()](/api/internal/intercept-method) method. +Insert HTML content into header cells via the [`pivot.template`](/api/helpers/template) helper by defining a template as the `cell` property of the header cell object. Apply the template just before the table renders by intercepting the [`render-table`](/api/events/render-table-event) event with [`api.intercept()`](/api/internal/intercept-method). The example below shows how to add icons to: -- the header labels based on the field name (for example, if the field is "id", it adds the globe icon next to the header value) -- the column headers based on the value (colored arrow indicators are added) +- the header labels based on the field name (for example, if the field is `"id"`, the template adds the globe icon next to the header value) +- the column headers based on the value (colored arrow indicators apply) ~~~jsx function rowsHeaderTemplate(value, field) { @@ -280,7 +334,7 @@ function statusTemplate(value) { widget.api.intercept("render-table", ({ config: tableConfig }) => { tableConfig.columns = tableConfig.columns.map((c) => { if (c.area === "rows") { - // Apply a template to the first header row of the columns from the "rows" area + // apply a template to the first header row of columns from the "rows" area c.header[0].cell = pivot.template(({ value, field }) => rowsHeaderTemplate(value, field)); } else { // For header cells that display values from the "status" field @@ -294,9 +348,9 @@ widget.api.intercept("render-table", ({ config: tableConfig }) => { }); ~~~ -## Making columns collapsible +## Make columns collapsible -It's possible to collapse/expand columns that are under one header. To make columns collapsible, use the value of the `collapsible` parameter of the [`headerShape`](/api/config/headershape-property) property by setting it to **true**. +Set the `collapsible` parameter of the [`headerShape`](/api/config/headershape-property) property to `true` to collapse and expand columns under the same header. ~~~jsx {4-6} const table = new pivot.Pivot("#root", { @@ -322,13 +376,13 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Freezing columns +## Freeze columns -The widget allows freezing columns on the left or right side, which makes the columns static and visible while scrolling. To freeze columns, apply the **split** parameter of the [`tableShape`](/api/config/tableshape-property) property by setting the value of the `left` or `right` parameter to **true**. More details with examples, see below. +Use the `split` parameter of the [`tableShape`](/api/config/tableshape-property) property to freeze columns on the left or right side. Frozen columns remain static and visible while scrolling. Set the `left` or `right` parameter to `true` to enable freezing. -### Freezing columns on the left +### Freeze columns on the left -The number of columns that are split is equal to the number of the rows fields that are defined in the [`config`](/api/config/config-property) property. In the **tree** mode only one column gets frozen regardless of the number of the rows fields that are defined. In the sample below, 1 column is fixed initially on the left, which is equal to the number of fields defined for the "rows" area. +The number of frozen columns equals the number of row fields defined in the [`config`](/api/config/config-property) property. In **tree** mode, only one column freezes regardless of the number of row fields. The example below fixes 1 column on the left, equal to the number of fields in the rows area. ~~~jsx {19} const table = new pivot.Pivot("#root", { @@ -354,9 +408,9 @@ const table = new pivot.Pivot("#root", { }); ~~~ -You can also apply a custom split using the [`render-table`](/api/events/render-table-event) event. It's not recommended to split columns with colspans. +Apply a custom split with the [`render-table`](/api/events/render-table-event) event. Avoid splitting columns with colspans. -In the sample below all columns from the "rows" area and first 4 columns from the "values" area are fixed initially. The number of columns that are split depends on the number of the rows and values fields that are defined via the [`config`](/api/config/config-property) property. +The example below fixes all columns from the rows area and the first 4 columns from the values area. The number of frozen columns depends on the number of rows and values fields defined in [`config`](/api/config/config-property). ~~~jsx {19-25} const table = new pivot.Pivot("#root", { @@ -386,9 +440,9 @@ table.api.on("render-table", (tableConfig) => { }); ~~~ -### Freezing columns on the right +### Freeze columns on the right -The `right` parameter of the [`tableShape`](/api/config/tableshape-property) property allows fixing total columns on the right. +Use the `right` parameter of [`tableShape`](/api/config/tableshape-property) to fix total columns on the right. ~~~jsx {4-7} const widget = new pivot.Pivot("#pivot", { @@ -415,7 +469,7 @@ const widget = new pivot.Pivot("#pivot", { }); ~~~ -To fix custom columns on the right, you need to apply the table API via the [`render-table`](/api/events/render-table-event) event. It's not recommended to split columns with colspans. In the sample below, 2 columns on the right are fixed initially. +To fix custom columns on the right, use the table API via the [`render-table`](/api/events/render-table-event) event. Avoid splitting columns with colspans. The example below fixes 2 columns on the right. ~~~jsx {20-25} const widget = new pivot.Pivot("#pivot", { @@ -445,9 +499,9 @@ widget.api.on("render-table", ({ config: tableConfig }) => { }) ~~~ -## Sorting in columns +## Sort columns -The sorting functionality is enabled by default. A user can click the column's header to sort data. To disable/enable sorting, apply the `sort` parameter of the [`columnShape`](/api/config/columnshape-property) property. In the example below we disable sorting. +Sorting is enabled by default. Click a column header to sort data. Use the `sort` parameter of the [`columnShape`](/api/config/columnshape-property) property to enable or disable sorting. The example below disables sorting. ~~~jsx {19} const table = new pivot.Pivot("#root", { @@ -475,10 +529,9 @@ const table = new pivot.Pivot("#root", { For more information about sorting data, refer to [Sorting data](/guides/working-with-data#sorting-data). -## Enabling the tree mode +## Enable the tree mode -The widget allows presenting data in a hierarchical format with expandable rows. To switch to the tree mode, apply the `tree` parameter of the [`tableShape`](/api/config/tableshape-property) property by setting its value to **true** (default is **false**). -To specify the parent row, put its name first in the `rows` array of the [`config`](/api/config/config-property) property. +Present data in a hierarchical format with expandable rows. Set the `tree` parameter of the [`tableShape`](/api/config/tableshape-property) property to `true` (default: `false`) to enable tree mode. In the `rows` array of [`config`](/api/config/config-property), put the parent row field first. ~~~jsx {3} const table = new pivot.Pivot("#root", { @@ -515,11 +568,11 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Expanding/collapsing all rows +## Expand and collapse all rows -To expand/collapse all rows, the **tree** mode should be enabled via the [`tableShape`](/api/config/tableshape-property) property and you should use the [`close-row`](/api/table/close-row) and [`open-row`](/api/table/open-row) events of the Table widget getting access to its API via the [`getTable`](/api/methods/gettable-method) method. +Enable **tree** mode via [`tableShape`](/api/config/tableshape-property), then use the [`close-row`](/api/table/close-row) and [`open-row`](/api/table/open-row) events of the Table widget. Access the Table API with the [`getTable`](/api/methods/gettable-method) method. -The example below shows how to expand/collapse all data rows with the button click in the table tree mode. +The example below expands and collapses all data rows on button click in tree mode. ~~~jsx const table = new pivot.Pivot("#root", { @@ -554,11 +607,11 @@ const table = new pivot.Pivot("#root", { const api = table.api; const table = api.getTable(); -// setting all table branches closed on the table config update +// set all table branches closed on config update api.intercept("render-table", (ev) => { ev.config.data.forEach((r) => (r.open = false)); - // returning "false" here will prevent the table from rendering + // return "false" to prevent the table from rendering // return false; }); @@ -582,9 +635,9 @@ document.body.appendChild(openAllButton); document.body.appendChild(closeAllButton); ~~~ -## Changing text orientation in headers +## Change text orientation in headers -To change text orientation from default horizontal to vertical, use the [`headerShape`](/api/config/headershape-property) property and set its `vertical` parameter to **true**. +Use the [`headerShape`](/api/config/headershape-property) property to change text orientation from horizontal to vertical. Set the `vertical` parameter to `true`. ~~~jsx {4-6} const table = new pivot.Pivot("#root", { @@ -610,13 +663,13 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Controlling visibility of Configuration panel +## Control the configuration panel -The Configuration panel is displayed by default. The widget provides the default functionality that allows controlling the visibility of the Configuration panel with the button click. It's made possible via the [`configPanel`](/api/config/configpanel-property) property or [`show-config-panel`](/api/events/show-config-panel-event) event. +The configuration panel appears by default. Control panel visibility with the [`configPanel`](/api/config/configpanel-property) property or the [`show-config-panel`](/api/events/show-config-panel-event) event. -### Hiding Configuration panel +### Hide the configuration panel -To hide the panel, set the value of the [`configPanel`](/api/config/configpanel-property) property to **false**. +Set the [`configPanel`](/api/config/configpanel-property) property to `false` to hide the panel. ~~~jsx // the configuration panel is hidden on init @@ -641,7 +694,7 @@ const table = new pivot.Pivot("#root", { }); ~~~ -You can also trigger the [`show-config-panel`](/api/events/show-config-panel-event) event with the [`api.exec()`](/api/internal/exec-method) method, and set the `mode` parameter to **false**. +Trigger the [`show-config-panel`](/api/events/show-config-panel-event) event with [`api.exec()`](/api/internal/exec-method) and set `mode` to `false`. ~~~jsx {19-22} const table = new pivot.Pivot("#root", { @@ -668,11 +721,11 @@ table.api.exec("show-config-panel", { }); ~~~ -### Disabling the default toggling functionality +### Disable the default toggling -You can block toggling the visibility of the Configuration panel on the button click via the [`api.intercept()`](/api/internal/intercept-method) method (by listening to the [`show-config-panel`](/api/events/show-config-panel-event) event and returning *false*). +Block panel toggling on button click by listening to the [`show-config-panel`](/api/events/show-config-panel-event) event with [`api.intercept()`](/api/internal/intercept-method) and returning `false`. -Example: +The example below intercepts the `show-config-panel` event to disable panel toggling: ~~~jsx {20-22} const table = new pivot.Pivot("#root", { @@ -699,17 +752,47 @@ table.api.intercept("show-config-panel", () => { }); ~~~ -You can also control the visibility of the Configuration panel using the [`showConfigPanel()`](/api/methods/showconfigpanel-method) method. +Use the [`showConfigPanel()`](/api/methods/showconfigpanel-method) method to control panel visibility. -### Actions with fields in the panel +### Manage fields in the configuration panel -In the Configuration panel it's possible to perform the next operations with fields: +Perform the following operations with fields in the configuration panel: - [add-field](/api/events/add-field-event) - [delete-field](/api/events/delete-field-event) - [update-field](/api/events/update-value-event) - [move-field](/api/events/move-field-event) +## Enable the read-only mode + +Set the [`readonly`](/api/config/readonly-property) property to `true` to disable configuring the Pivot structure through the UI. In the read-only mode, users cannot change the configuration via the configuration panel. + +The following code snippet enables the read-only mode: + +~~~jsx {18} +const table = new pivot.Pivot("#root", { + fields, + data: dataset, + config: { + rows: ["studio", "genre"], + columns: [], + values: [ + { + field: "title", + method: "count" + }, + { + field: "score", + method: "max" + } + ] + }, + readonly: true +}); +~~~ + +**Related sample:** [Pivot 2. Readonly mode](https://snippet.dhtmlx.com/0k0mvycv) + **Related samples:** - [Pivot 2. Adding text templates for table and header cells](https://snippet.dhtmlx.com/n9ylp6b2) - [Pivot 2. Custom frozen (fixed) columns (your number)](https://snippet.dhtmlx.com/53erlmgp) diff --git a/docs/guides/exporting-data.md b/docs/guides/exporting-data.md index effed77..246a941 100644 --- a/docs/guides/exporting-data.md +++ b/docs/guides/exporting-data.md @@ -4,36 +4,88 @@ title: Exporting data description: You can explore how to export data in the documentation of the DHTMLX JavaScript Pivot library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Pivot. --- -# Exporting data +# Export data -To export the table data to the XLSX or CSV format, it's necessary to get access to the underlying Table widget instance inside Pivot and apply its API to export data. To do this, you should use the [`getTable`](/api/methods/gettable-method) method and execute the [`export`](/api/table/export) event. +To export Pivot data to XLSX or CSV, access the underlying Table widget instance with the [`getTable()`](/api/methods/gettable-method) method and call `exec("export", ...)` with the required options. -In the example below we get access to the Table instance and trigger the `export`action using the [`api.exec()`](/api/internal/exec-method) method. +The following code snippet accesses the Table instance with `getTable()` and triggers the `export` action for both CSV and XLSX formats: ~~~jsx -const widget = new pivot.Pivot("#root", { /*setting*/}); +const widget = new pivot.Pivot("#root", { /* config */ }); + +// export to CSV widget.api.getTable().exec("export", { - options: { - format: "csv", - cols: ";" - } + options: { + format: "csv", + cols: ";" + } }); + +// export to XLSX widget.api.getTable().exec("export", { - options: { - format: "xlsx", - fileName: "My Report", - sheetName: "Quarter 1", - } + options: { + format: "xlsx", + fileName: "My Report", + sheetName: "Quarter 1", + } }); ~~~ -## Example +## Export to CSV + +Use the [`getTable()`](/api/methods/gettable-method) method to access the Table widget instance and call `exec("export", ...)` with `format: "csv"`. + +The following code snippet exports the table to CSV with a semicolon as column delimiter: + +~~~jsx +widget.api.getTable().exec("export", { + options: { + format: "csv", + fileName: "report", + cols: ";", // column delimiter, "\t" by default + rows: "\n" // row delimiter, "\n" by default + } +}); +~~~ + +## Export to XLSX + +The following code snippet exports the table to XLSX with a custom file and sheet name: + +~~~jsx +widget.api.getTable().exec("export", { + options: { + format: "xlsx", + fileName: "My Report", + sheetName: "Quarter 1", + header: true, // include header, true by default + footer: true, // include footer, true by default + download: true // trigger file download, true by default + } +}); +~~~ + +Set `download` to `false` to suppress the file download and access the exported data as a Blob via `ev.result` instead. + +## Customize export output + +Use the following XLSX-specific options to control cell values and styling during export: + +- `cellTemplate` — a function to override the exported value of each data cell; receives `value`, `row`, and `column` and returns the custom value +- `headerCellTemplate` — a function to override the exported value of header or footer cells; receives `text`, header cell object, `column`, and `type` (`"header"` or `"footer"`) +- `cellStyle` — a function that returns alignment and format for a data cell +- `headerCellStyle` — a function that returns alignment and format for a header or footer cell +- `styles` — set to `false` to export without styling, or pass an object with style settings for `header`, `cell`, `footer`, `lastHeaderCell`, and `firstFooterCell` cells + +:::note +By default, date and number fields export as raw values with the format defined via the [`fields`](/api/config/fields-property) property. If a template is set via [`tableShape`](/api/config/tableshape-property), the rendered value is exported instead. If both `cellTemplate` and `format` are set, `cellTemplate` takes precedence. +::: -In this snippet you can see how to export data: +The live example below demonstrates both export formats: - + -**Related articles**: +**Related articles**: - [Date formatting](/guides/localization#date-formatting) -- [`export`](/api/table/export) \ No newline at end of file +- [`export`](/api/table/export) diff --git a/docs/guides/initialization.md b/docs/guides/initialization.md index a7252f8..4fe85b6 100644 --- a/docs/guides/initialization.md +++ b/docs/guides/initialization.md @@ -4,45 +4,47 @@ title: Initialization description: You can learn about the initialization in the documentation of the DHTMLX JavaScript Pivot library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Pivot. --- -# Initialization +# Initialize Pivot -This guide will give you detailed instructions on how to create Pivot on a page to enrich your application with features of the Pivot table. Take the following steps to get a ready-to-use component: +This guide explains how to add Pivot to a page. Take the following steps to get a ready-to-use component: -1. [Include the Pivot source files on a page](#including-source-files). -2. [Create a container for Pivot](#creating-container). -3. [Initialize Pivot with a constructor](#initializing-pivot). +1. [Include the Pivot source files on a page](#include-source-files). +2. [Create a container for Pivot](#create-a-container). +3. [Initialize Pivot with a constructor](#create-a-pivot-instance). -## Including source files +## Include source files -See also how to download packages: [Downloading packages](/how-to-start#step-1-downloading-and-installing-packages). +Include two files from the `dist/` folder in your HTML page. For information on downloading the package, see [Downloading packages](/how-to-start#step-1-downloading-and-installing-packages). -To create a Pivot app, you need to include 2 source files on your page: +Include the following source files: -- *pivot.js* -- *pivot.css* +- `pivot.js` +- `pivot.css` -Make sure that you set correct relative paths to the source files: +Set correct relative paths to the source files: ~~~html title="index.html" ~~~ -## Creating container +## Create a container -Add a container for Pivot and give it an ID, for example *"root"*: +Add a container for Pivot and give the container an ID, for example `"root"`: ~~~html title="index.html"
~~~ -## Initializing Pivot +## Create a Pivot instance -Initialize Pivot with the **pivot.Pivot** constructor. It takes two parameters: +Initialize Pivot with the `pivot.Pivot` constructor. It takes two parameters: - an HTML container (the ID of the HTML container) - an object with configuration properties +The following code snippet initializes Pivot with fields, data, and a basic config: + ~~~jsx // create Pivot const table = new pivot.Pivot("#root", { @@ -62,14 +64,10 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Configuration properties - :::info -The full list of properties to configure **Pivot** can be found [**here**](api/overview/properties-overview.md). +Find the full list of Pivot configuration properties in the [Properties overview](api/overview/properties-overview.md). ::: -## Example - -In this snippet you can see how to initialize **Pivot** with the initial data: +The live example below shows Pivot initialized with sample data: diff --git a/docs/guides/integration-with-angular.md b/docs/guides/integration-with-angular.md index f043e0d..6460e45 100644 --- a/docs/guides/integration-with-angular.md +++ b/docs/guides/integration-with-angular.md @@ -7,79 +7,79 @@ description: You can learn about the integration with Angular in the documentati # Integration with Angular :::tip -You should be familiar with basic concepts and patterns of **Angular** before reading this documentation. To refresh your knowledge, please refer to the [**Angular documentation**](https://v17.angular.io/docs). +Familiarize yourself with the basic concepts and patterns of [Angular](https://v17.angular.io/docs) before reading this documentation. See the [Angular documentation](https://v17.angular.io/docs) for reference. ::: -DHTMLX Pivot is compatible with **Angular**. We have prepared code examples on how to use DHTMLX Pivot with **Angular**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/angular-pivot-demo). +DHTMLX Pivot is compatible with Angular. For a complete working example, see the [Example on GitHub](https://github.com/DHTMLX/angular-pivot-demo). -## Creating a project +## Create a project :::info -Before you start to create a new project, install [**Angular CLI**](https://v1.angular.io/cli) and [**Node.js**](https://nodejs.org/en/). +Before creating a new project, install [Angular CLI](https://v17.angular.io/cli) and [Node.js](https://nodejs.org/en/). ::: -Create a new **my-angular-pivot-app** project using Angular CLI. Run the following command for this purpose: +Create a new *my-angular-pivot-app* project using Angular CLI: ~~~json ng new my-angular-pivot-app ~~~ :::note -If you want to follow this guide, disable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering) when creating new Angular app! +Disable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering) when creating the Angular app to follow this guide. ::: -The command above installs all the necessary tools, so you don't need to run any additional commands. +The command installs all necessary tools. No additional commands are needed. -### Installation of dependencies +### Install dependencies -Go to the new created app directory: +Go to the new project directory: ~~~json cd my-angular-pivot-app ~~~ -Install dependencies and start the dev server. For this, use the [**yarn**](https://yarnpkg.com/) package manager: +Install dependencies and start the dev server using [yarn](https://yarnpkg.com/): ~~~jsx yarn yarn start // or yarn dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a localhost (for instance `http://localhost:3000`). -## Creating Pivot +## Create a Pivot component -Now you should get the DHTMLX Pivot source code. First of all, stop the app and proceed with installing the Pivot package. +Stop the app and install the Pivot package. ### Step 1. Package installation -Download the [**trial Pivot package**](/how-to-start/#installing-trial-pivot-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Pivot is available 30 days only. - -### Step 2. Component creation +Download the [trial Pivot package](/how-to-start/#installing-trial-pivot-via-npm-or-yarn) and follow the steps in the README file. The trial version is available for 30 days. -Now you need to create an Angular component, to add Pivot into the application. Create the **pivot** folder in the ***src/app/*** directory, add a new file into it and name it ***pivot.component.ts***. Then complete the steps described below. +### Step 2. Create the component + +Create a *pivot* folder in the *src/app/* directory, add a new file named *pivot.component.ts*, then complete the steps below. #### Import source files -Open the file and import Pivot source files. Note that: +Open *pivot.component.ts* and import Pivot source files. -- if you use PRO version and install the Pivot package from a local folder, the imported path looks like this: +- PRO version installed from a local folder: ~~~jsx import { Pivot } from 'dhx-pivot-package'; ~~~ -- if you use the trial version of Pivot, specify the following path: +- Trial version: ~~~jsx import { Pivot } from '@dhx/trial-pivot'; ~~~ -In this tutorial you can see how to configure the **trial** version of Pivot. +This tutorial uses the trial version of Pivot. -#### Set the container and initialize Pivot +#### Set up the container -To display Pivot on the page, you need to set the container to render the component inside and initialize Pivot using the corresponding constructor: +Set the container to render the component and initialize Pivot with the constructor: ~~~jsx {1,8,12-13,18-19} title="pivot.component.ts" import { Pivot } from '@dhx/trial-pivot'; @@ -109,9 +109,9 @@ export class PivotComponent implements OnInit, OnDestroy { } ~~~ -#### Adding styles +#### Add styles -To display Pivot correctly, you need to provide the corresponding styles. For this purpose, you can create the ***pivot.component.css*** file in the ***src/app/pivot/*** directory and specify important styles for Pivot and its container: +Create the *pivot.component.css* file in the *src/app/pivot/* directory and specify styles for Pivot and its container: ~~~css title="pivot.component.css" /* import Pivot styles */ @@ -132,9 +132,9 @@ body { } ~~~ -#### Loading data +#### Load data -To add data into Pivot, you need to provide a data set. You can create the ***data.ts*** file in the ***src/app/pivot/*** directory and add some data into it: +Create the *data.ts* file in the *src/app/pivot/* directory and add your data: ~~~jsx title="data.ts" export function getData() { @@ -172,7 +172,7 @@ export function getData() { "state": "Colorado", "expenses": 45, "type": "Decaf" - }, // othe data items + }, // other data items ]; const fields: any = [ @@ -192,7 +192,7 @@ export function getData() { }; ~~~ -Then open the ***pivot.component.ts*** file. Import the file with data and specify the corresponding data properties to the configuration object of Pivot within the `ngOnInit()` method, as shown below. +Open *pivot.component.ts*, import the data, and pass the data to the Pivot configuration inside `ngOnInit()`: ~~~jsx {2,18,20-21} title="pivot.component.ts" import { Pivot } from '@dhx/trial-pivot'; @@ -236,13 +236,13 @@ export class PivotComponent implements OnInit, OnDestroy { } ~~~ -Now the Pivot component is ready to use. When the element will be added to the page, it will initialize the Pivot with data. You can provide necessary configuration settings as well. Visit our [Pivot API docs](/api/overview/properties-overview/) to check the full list of available properties. +The Pivot component is ready. When the element mounts, the component initializes Pivot with data. See the [Pivot API reference](/api/overview/properties-overview/) for the full list of properties. -#### Handling events +#### Handle events -When a user makes some action in the Pivot, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](/api/overview/events-overview/). +Pivot fires events when a user interacts with the widget. Use these events to detect actions and run the corresponding code. See the [full list of events](/api/overview/events-overview/). -Open the ***pivot.component.ts*** file and complete the `ngOnInit()` method as in: +Open *pivot.component.ts* and add an event listener inside `ngOnInit()`: ~~~jsx {18-20} title="pivot.component.ts" // ... @@ -272,9 +272,9 @@ ngOnDestroy(): void { } ~~~ -### Step 3. Adding Pivot into the app +### Step 3. Add Pivot to the app -To add the ***PivotComponent*** into the app, open the ***src/app/app.component.ts*** file and replace the default code with the following one: +Open *src/app/app.component.ts* and replace the default code with the following: ~~~jsx {5} title="app.component.ts" import { Component } from "@angular/core"; @@ -288,7 +288,7 @@ export class AppComponent { } ~~~ -Then create the ***app.module.ts*** file in the ***src/app/*** directory and specify the *PivotComponent* as shown below: +Create the *app.module.ts* file in the *src/app/* directory and specify `PivotComponent`: ~~~jsx {4-5,8} title="app.module.ts" import { NgModule } from "@angular/core"; @@ -305,7 +305,7 @@ import { PivotComponent } from "./pivot/pivot.component"; export class AppModule {} ~~~ -The last step is to open the ***src/main.ts*** file and replace the existing code with the following one: +Open *src/main.ts* and replace the existing code with the following: ~~~jsx title="main.ts" import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; @@ -315,8 +315,8 @@ platformBrowserDynamic() .catch((err) => console.error(err)); ~~~ -After that, you can start the app to see Pivot loaded with data on a page. +After that, start the app to see Pivot loaded with data on the page. ![Pivot initialization](../assets/trial_pivot.png) -Now you know how to integrate DHTMLX Pivot with Angular. You can customize the code according to your specific requirements. The final example you can find on [**GitHub**](https://github.com/DHTMLX/angular-pivot-demo). +Customize the code to fit your requirements. See the complete example on [GitHub](https://github.com/DHTMLX/angular-pivot-demo). diff --git a/docs/guides/integration-with-react.md b/docs/guides/integration-with-react.md index cfc984d..5c8f74a 100644 --- a/docs/guides/integration-with-react.md +++ b/docs/guides/integration-with-react.md @@ -7,86 +7,86 @@ description: You can learn about the integration with React in the documentation # Integration with React :::tip -You should be familiar with the basic concepts and patterns of [**React**](https://react.dev) before reading this documentation. To refresh your knowledge, please refer to the [**React documentation**](https://react.dev/learn). +Familiarize yourself with the basic concepts and patterns of [React](https://react.dev) before reading this documentation. See the [React documentation](https://react.dev/learn) for reference. ::: -DHTMLX Pivot is compatible with **React**. We have prepared code examples on how to use DHTMLX Pivot with **React**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/react-pivot-demo). +DHTMLX Pivot is compatible with React. For a complete working example, see the [Example on GitHub](https://github.com/DHTMLX/react-pivot-demo). -## Creating a project +## Create a project :::info -Before you start to create a new project, install [**Vite**](https://vite.dev/) (optional) and [**Node.js**](https://nodejs.org/en/). +Before creating a new project, install [Vite](https://vite.dev/) (optional) and [Node.js](https://nodejs.org/en/). ::: -You can create a basic **React** project or use **React with Vite**. Let's name the project as **my-react-pivot-app**: +Create a basic React project or use React with Vite. The following command creates a project named *my-react-pivot-app*: ~~~json npx create-react-app my-react-pivot-app ~~~ -### Installation of dependencies +### Install dependencies -Go to the new created app directory: +Go to the new project directory: ~~~json cd my-react-pivot-app ~~~ -Install dependencies and start the dev server. For this, use a package manager: +Install dependencies and start the dev server using a package manager: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- [yarn](https://yarnpkg.com/): ~~~jsx yarn yarn start // or yarn dev ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- [npm](https://www.npmjs.com/): ~~~json npm install npm run dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a localhost (for instance `http://localhost:3000`). -## Creating Pivot +## Create a Pivot component -Now you should get the DHTMLX Pivot source code. First of all, stop the app and proceed with installing the Pivot package. +Stop the app and install the Pivot package. ### Step 1. Package installation -Download the [**trial Pivot package**](/how-to-start/#installing-trial-pivot-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Pivot is available 30 days only. +Download the [trial Pivot package](/how-to-start/#installing-trial-pivot-via-npm-or-yarn) and follow the steps in the README file. The trial version is available for 30 days. -### Step 2. Component creation +### Step 2. Create the component -Now you need to create a React component, to add a Pivot into the application. Create a new file in the ***src/*** directory and name it ***Pivot.jsx***. +Create a React component to add Pivot to the application. In the *src/* directory, add a new file and name it *Pivot.jsx*. #### Import source files -Open the ***Pivot.jsx*** file and import Pivot source files. Note that: +Open *Pivot.jsx* and import Pivot source files. -- if you use PRO version and install the Pivot package from a local folder, the import paths look like this: +- PRO version installed from a local folder: ~~~jsx title="Pivot.jsx" import { Pivot } from 'dhx-pivot-package'; import 'dhx-pivot-package/dist/pivot.css'; ~~~ -Note that depending on the used package, the source files can be minified. In this case make sure that you are importing the CSS file as ***pivot.min.css***. +Depending on the package, source files may be minified. In that case import *pivot.min.css* instead. -- if you use the trial version of Pivot, specify the following paths: +- Trial version: ~~~jsx title="Pivot.jsx" import { Pivot } from '@dhx/trial-pivot'; import "@dhx/trial-pivot/dist/pivot.css"; ~~~ -In this tutorial you can see how to configure the **trial** version of Pivot. +This tutorial uses the trial version of Pivot. -#### Setting the container and adding Pivot +#### Set up the container -To display Pivot on the page, you need to create the container for Pivot, and initialize this component using the corresponding constructor: +Create a container for Pivot and initialize it with the constructor: ~~~jsx {2,6,9-10} title="Pivot.jsx" import { useEffect, useRef } from "react"; @@ -109,9 +109,9 @@ export default function PivotComponent(props) { } ~~~ -#### Adding styles +#### Add styles -To display Pivot correctly, you need to specify important styles for Pivot and its container in the main css file of the project: +Specify styles for Pivot and its container in the main CSS file of the project: ~~~css title="index.css" /* specify styles for initial page */ @@ -130,9 +130,9 @@ body, } ~~~ -#### Loading data +#### Load data -To add data into the Pivot, you need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +Create the *data.js* file in the *src/* directory and add your data: ~~~jsx title="data.js" export function getData() { @@ -170,7 +170,7 @@ export function getData() { "state": "Colorado", "expenses": 45, "type": "Decaf" - }, // othe data items + }, // other data items ]; const fields = [ @@ -190,7 +190,7 @@ export function getData() { }; ~~~ -Then open the ***App.js*** file and import data. After this you can pass data into the new created `` components as **props**: +Open *App.js*, import the data, and pass the data to the `` component as props: ~~~jsx {2,5-6} title="App.js" import Pivot from "./Pivot"; @@ -204,7 +204,7 @@ function App() { export default App; ~~~ -Go to the ***Pivot.jsx*** file and apply the passed **props** to the Pivot configuration object: +Open *Pivot.jsx* and apply the props to the Pivot configuration object: ~~~jsx {5,10-11} title="Pivot.jsx" import { useEffect, useRef } from "react"; @@ -240,13 +240,13 @@ export default function PivotComponent(props) { } ~~~ -Now the Pivot component is ready to use. When the element will be added to the page, it will initialize the Pivot with data. You can provide necessary configuration settings as well. Visit our [Pivot API docs](/api/overview/properties-overview/) to check the full list of available properties. +The Pivot component is ready. When the element mounts, the component initializes Pivot with data. See the [Pivot API reference](/api/overview/properties-overview/) for the full list of properties. -#### Handling events +#### Handle events -When a user makes some action in the Pivot, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](/api/overview/events-overview/). +Pivot fires events when a user interacts with the widget. Use these events to detect actions and run the corresponding code. See the [full list of events](/api/overview/events-overview/). -Open ***Pivot.jsx*** and complete the `useEffect()` method in the following way: +Open *Pivot.jsx* and add an event listener inside `useEffect()`: ~~~jsx {19-21} title="Pivot.jsx" // ... @@ -278,8 +278,8 @@ useEffect(() => { // ... ~~~ -After that, you can start the app to see Pivot loaded with data on a page. +After that, start the app to see Pivot loaded with data on the page. ![Pivot initialization](../assets/trial_pivot.png) -Now you know how to integrate DHTMLX Pivot with React. You can customize the code according to your specific requirements. The final example you can find on [**GitHub**](https://github.com/DHTMLX/react-pivot-demo). +Customize the code to fit your requirements. See the complete example on [GitHub](https://github.com/DHTMLX/react-pivot-demo). diff --git a/docs/guides/integration-with-svelte.md b/docs/guides/integration-with-svelte.md index d0510d2..99be3c8 100644 --- a/docs/guides/integration-with-svelte.md +++ b/docs/guides/integration-with-svelte.md @@ -7,26 +7,26 @@ description: You can learn about the integration with Svelte in the documentatio # Integration with Svelte :::tip -You should be familiar with the basic concepts and patterns of **Svelte** before reading this documentation. To refresh your knowledge, please refer to the [**Svelte documentation**](https://svelte.dev/). +Familiarize yourself with the basic concepts and patterns of [Svelte](https://svelte.dev/) before reading this documentation. See the [Svelte documentation](https://svelte.dev/) for reference. ::: -DHTMLX Pivot is compatible with **Svelte**. We have prepared code examples on how to use DHTMLX Pivot with **Svelte**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/svelte-pivot-demo). +DHTMLX Pivot is compatible with Svelte. For a complete working example, see the [Example on GitHub](https://github.com/DHTMLX/svelte-pivot-demo). -## Creating a project +## Create a project :::info -Before you start to create a new project, install [**Vite**](https://vite.dev/) (optional) and [**Node.js**](https://nodejs.org/en/). +Before creating a new project, install [Vite](https://vite.dev/) (optional) and [Node.js](https://nodejs.org/en/). ::: -To create a **Svelte** JS project, run the following command: +Run the following command to create a Svelte project: ~~~json npm create vite@latest ~~~ -Let's name the project as **my-svelte-pivot-app**. +Name the project *my-svelte-pivot-app*. -### Installation of dependencies +### Install dependencies Go to the app directory: @@ -34,41 +34,41 @@ Go to the app directory: cd my-svelte-pivot-app ~~~ -Install dependencies and start the dev server. For this, use a package manager: +Install dependencies and start the dev server using a package manager: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- [yarn](https://yarnpkg.com/): ~~~jsx -yarn +yarn yarn start // or yarn dev ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- [npm](https://www.npmjs.com/): ~~~json npm install npm run dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a localhost (for instance `http://localhost:3000`). -## Creating Pivot +## Create a Pivot component -Now you should get the DHTMLX Pivot source code. First of all, stop the app and proceed with installing the Pivot package. +Stop the app and install the Pivot package. ### Step 1. Package installation -Download the [**trial Pivot package**](/how-to-start/#installing-trial-pivot-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Pivot is available 30 days only. +Download the [trial Pivot package](/how-to-start/#installing-trial-pivot-via-npm-or-yarn) and follow the steps in the README file. The trial version is available for 30 days. -### Step 2. Component creation +### Step 2. Create the component -Now you need to create a Svelte component, to add Pivot into the application. Let's create a new file in the ***src/*** directory and name it ***Pivot.svelte***. +Create a Svelte component to add Pivot to the application. In the *src/* directory, add a new file and name it *Pivot.svelte*. #### Import source files -Open the ***Pivot.svelte*** file and import Pivot source files. Note that: +Open *Pivot.svelte* and import Pivot source files. -- if you use PRO version and install the Pivot package from a local folder, the import paths look like this: +- PRO version installed from a local folder: ~~~html title="Pivot.svelte" ~~~ -Note that depending on the used package, the source files can be minified. In this case make sure that you are importing the CSS file as ***pivot.min.css***. +Depending on the package, source files may be minified. In that case import *pivot.min.css* instead. -- if you use the trial version of Pivot, specify the following paths: +- Trial version: ~~~html title="Pivot.svelte" ~~~ -In this tutorial you can see how to configure the **trial** version of Pivot. +This tutorial uses the trial version of Pivot. -#### Setting the container and adding Pivot +#### Set up the container -To display Pivot on the page, you need to create the container for Pivot, and initialize this component using the corresponding constructor: +Create a container for Pivot and initialize it with the constructor: ~~~html {3,6,10-11,19} title="Pivot.svelte" ~~~ -Note that depending on the used package, the source files can be minified. In this case make sure that you are importing the CSS file as ***pivot.min.css***. +Depending on the package, source files may be minified. In that case import *pivot.min.css* instead. -- if you use the trial version of Pivot, specify the following paths: +- Trial version: ~~~html title="Pivot.vue" ~~~ -In this tutorial you can see how to configure the **trial** version of Pivot. +This tutorial uses the trial version of Pivot. -#### Setting the container and adding Pivot +#### Set up the container -To display Pivot on the page, you need to create the container for Pivot, and initialize this component using the corresponding constructor: +Create a container for Pivot and initialize it with the constructor: ~~~html {2,7-8,18} title="Pivot.vue" ~~~ -Create Pivot and load data: +The following code snippet initializes Pivot with data from the local file: ~~~jsx const { data, config, fields } = getData(); const table = new pivot.Pivot("#root", { data, config, fields }); ~~~ -To get server data, you can send the request for data using the native **fetch** method (or any other way): +### Load from a server + +Use the native `fetch` method (or any other approach) to request server data and apply it with `setConfig()`: ~~~jsx const table = new pivot.Pivot("#root", {fields:[], data: []}); @@ -157,17 +188,15 @@ Promise.all([ }); ~~~ -## Loading CSV data +## Load CSV data -You can load CSV data and convert it to JSON and then continue working with this data in the Pivot table. +Load CSV data, convert it to JSON, and use it in the Pivot table. Use an external JS library to convert CSV data to JSON. -To convert data, you should use an external parsing library for JS to convert data from CSV to JSON. +The following code snippet uses the external [PapaParse](https://cdnjs.cloudflare.com/ajax/libs/PapaParse/5.4.1/papaparse.min.js) library to convert CSV data on a button click. The `convert()` function takes the following parameters: -In the example below we apply the external [PapaParse](https://cdnjs.cloudflare.com/ajax/libs/PapaParse/5.4.1/papaparse.min.js) library and enable loading and converting data on a button click. In this example we use the `convert()` function which takes the following parameters: - -- `data` - a string with CSV data -- `headers` - an array with the names of fields for CSV data -- `meta` - an object where keys are the names of fields and values are the data types +- `data` — a string with CSV data +- `headers` — an array with the names of fields for CSV data +- `meta` — an object where keys are the names of fields and values are the data types ~~~jsx const table = new pivot.Pivot("#root", { @@ -261,15 +290,14 @@ importButton.textContent = "Import"; document.body.appendChild(importButton); ~~~ -## Example - -In this snippet you can see how to load JSON and CSV data: +The live example below demonstrates loading JSON and CSV data: - + **Related samples:** + - [Pivot 2. Date format](https://snippet.dhtmlx.com/shn1l794) - [Pivot 2. Different datasets](https://snippet.dhtmlx.com/6xtqge4i) - [Pivot 2. Large dataset](https://snippet.dhtmlx.com/e6qwqrys) -**Related articles**: [Date formatting](/guides/localization#date-formatting) \ No newline at end of file +**Related articles**: [Date formatting](/guides/localization#date-formatting) diff --git a/docs/guides/localization.md b/docs/guides/localization.md index 2c3be82..03d065a 100644 --- a/docs/guides/localization.md +++ b/docs/guides/localization.md @@ -6,11 +6,11 @@ description: You can learn about the localization in the documentation of the DH # Localization -You can localize all labels in the interface of JavaScript Pivot. For this purpose you need to create a new locale or modify a built-in one and apply it to Pivot. +Localize all labels in the Pivot interface by creating a new locale or modifying a built-in one and applying the locale to Pivot. ## Default locale -The **English** locale is applied by default: +The English locale applies by default. The following code snippet shows the full structure of the default locale object: ~~~jsx const en = { @@ -150,17 +150,19 @@ const en = { formats: { dateFormat: "%d.%m.%Y", timeFormat: "%H:%i" - } + }, lang: "en-US", }; ~~~ -## Applying locales +## Apply a locale + +Access built-in locales through the `pivot` object. Pivot includes three built-in locales: `en`, `de`, and `cn`. -You can access built-in locales via the pivot object. Pivot provides three built-in locales: en, de, cn. +### Use a built-in locale -Example: +The following code snippet applies the built-in German locale via the `locale` property: ~~~jsx new pivot.Pivot({ @@ -169,27 +171,38 @@ new pivot.Pivot({ }); ~~~ -To apply a custom locale, you need to: +### Apply a custom locale -- create a custom locale object (or modify the default one) and provide translations for all text labels (it can be any language you need) -- apply the new locale to Pivot via its [`locale`](/api/config/locale-property) property or use the [`setLocale()`](/api/methods/setlocale-method) method +To apply a custom locale: + +- create a custom locale object (or modify the default one) and provide translations for all text labels +- apply the locale via the [`locale`](/api/config/locale-property) property or the [`setLocale()`](/api/methods/setlocale-method) method + +The following code snippet applies a custom locale with `setLocale()`: ~~~jsx // create Pivot const widget = new pivot.Pivot("#root", { - data, -//other configuration properties + data, + // other configuration properties }); -const ko = {...} //object with locale +const ko = { /*...*/ }; // custom locale object widget.setLocale(ko); ~~~ -## Date formatting +To reset to the default English locale, call `setLocale()` with no arguments or pass `null`: -Pivot accepts a date as a Date object (make sure to parse a date to a Date object). By default, the `dateFormat` of the current locale is applied. To redefine the format for all date fields in Pivot, change the value of the `dateFormat` parameter in the `formats` object of the [`locale`](/api/config/locale-property). The default format is "%d.%m.%Y". +~~~jsx +table.setLocale(); // reset to English +table.setLocale(null); // same result +~~~ + +## Format dates + +Pivot accepts dates as `Date` objects. Parse date strings to `Date` before passing the date strings to Pivot. The widget applies the `dateFormat` from the current locale by default. To redefine the format for all date fields, change the `dateFormat` value in the `formats` object of the [`locale`](/api/config/locale-property) property. The default format is `"%d.%m.%Y"`. -Example: +The following code snippet sets a custom date format on init and updates it dynamically: ~~~jsx {17} function setFormat(value) { @@ -232,9 +245,9 @@ const table = new pivot.Pivot("#root", { }); ~~~ -In case you need to set a custom format to a specific field, use the `format` parameter of the [`fields`](/api/config/fields-property) property. Refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields). +To set a custom format for a specific field, use the `format` parameter of the [`fields`](/api/config/fields-property) property. See [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields). -## Date and time format specification +## Date and time format reference Pivot uses the following characters for setting the date and time format: @@ -262,22 +275,22 @@ Pivot uses the following characters for setting the date and time format: | %A | AM or PM | AM (for time from midnight until noon) and PM (for time from noon until midnight)| | %c | displays date and time in the ISO 8601 date format| 2024-10-04T05:04:09 | +To display June 20, 2024 with the exact time as `2024-09-20 16:47:08.128`, use `"%Y-%m-%d-%H:%i:%s.%u"`. -To present the 20th of June, 2024 with the exact time as *2024-09-20 16:47:08.128*, specify "%Y-%m-%d-%H:%i:%s.%u". +## Format numbers -## Number formatting +By default, Pivot localizes all number fields according to the `lang` value in the locale object, using the [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) specification. Fraction digits are limited to 3 and group separation applies to the integer part. -By default, all fields with the number type are localized according to the locale (the value in the `lang` field of the locale). Pivot uses [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) specification. By default the fraction digits are limited to 3 and group separation is applied for the integer part. -In case you do not need to format specific fields with numeric values or need to set a custom format, use the the `format` parameter of the [`fields`](/api/config/fields-property) property. It can be either *false* to cancel formatting or an object with format settings (refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)). +To disable formatting for a specific field or apply a custom format, use the `format` parameter of the [`fields`](/api/config/fields-property) property. Set the `format` parameter to `false` to cancel formatting or pass an object with format settings (see [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)). + +The following code snippet disables number formatting for the `year` field: ~~~jsx const fields = [ - { id: "year", label: "Year", type: "number", format: false}, + { id: "year", label: "Year", type: "number", format: false }, ]; ~~~ -## Example - -In this snippet you can see how to switch between several locales: +The live example below demonstrates switching between locales: - + diff --git a/docs/guides/stylization.md b/docs/guides/stylization.md index 3b2967c..a28c45b 100644 --- a/docs/guides/stylization.md +++ b/docs/guides/stylization.md @@ -8,6 +8,10 @@ description: You can learn about the styling in the documentation of the DHTMLX ## Default style +Use CSS variables to override the default appearance of Pivot components. + +The following CSS variables are available for customization in the default Material theme: + ~~~css .wx-material-theme { --wx-theme-name: material; @@ -21,30 +25,31 @@ description: You can learn about the styling in the documentation of the DHTMLX ~~~ :::tip Note -Next versions of Pivot can bring some changes for the variables and their names. Please, do not forget to check the names after updating to the newer versions and modify them in your code to avoid problems with display of the component. +Next versions of Pivot can bring some changes for the variables and their names. Check the names after updating to newer versions and modify them in your code to avoid display issues. ::: ## Built-in theme -The widget provides one built-in theme which is the **Material** theme. +The widget includes one built-in theme: the Material theme. + +Apply the theme by adding the corresponding CSS class to the widget container: -You can apply the theme via adding the corresponding *CSS* classes to the widget container: +- `wx-material-theme` — Material theme -- **Material theme** ~~~html {}
~~~ -or just include the theme on the page from the skins folder: +Or include the theme directly from the `skins` folder: ~~~html {} ~~~ -## Customize built-in theme +## Customize the built-in theme -The example below demonstrates how to customize the **Material** theme that is applied to the Pivot table: +The following code snippet overrides Material theme variables to apply a dark color scheme: ~~~html @@ -68,11 +73,9 @@ The example below demonstrates how to customize the **Material** theme that is a ~~~ -## Custom style +## Apply a custom style -You can change the appearance of Pivot by applying the corresponding CSS variables. - -The example below shows how to apply a custom style to Pivot: +The following code snippet applies custom CSS variables to a Pivot container: ~~~html
@@ -89,22 +92,25 @@ The example below shows how to apply a custom style to Pivot: ~~~ -## Scroll style +## Style the scrollbar + +Use the `.wx-styled-scroll` CSS class to apply a custom style to the Pivot scrollbar. Check browser compatibility [here](https://caniuse.com/css-scrollbar) before using the class. -You can also apply a custom style to the scroll bar of Pivot. For this, you can use the `.wx-styled-scroll` CSS class. Before using it, check compatibility with the modern browsers [here](https://caniuse.com/css-scrollbar). +The following code snippet enables the styled scrollbar: ~~~html {} title="index.html" - -
+ +
~~~ -## Cell style +## Style cells -To apply a CSS class to the table body or footer cells, use the `cellStyle` parameter of the [`tableShape`](/api/config/tableshape-property) property. The style of the header cells can be customized via the `cellStyle` parameter of the [`headerShape`](/api/config/tableshape-property) property. In both cases the `cellStyle` function returns a string, which can be used as a CSS class name to apply specific styles to a cell. +Use the `cellStyle` parameter of the [`tableShape`](/api/config/tableshape-property) property to apply a CSS class to table body or footer cells. Use the `cellStyle` parameter of the [`headerShape`](/api/config/headershape-property) property to style header cells. In both cases the `cellStyle` function returns a string used as a CSS class name. -In the example below the styles of cells in the table body and headers are customized in the following way: -- for the table body cells, styles are applied dynamically based on cell values (e.g., "Down", "Up", "Idle") in the "status" field and on total values (greater than 40 or less than 5) -- the style of header cells is determined by the value in the "streaming" field, with specific styles applied for "no" or other values (the CSS class "status-down" is applied for the "no" value and "status-up" is applied for the not "no" value) +The following code snippet applies dynamic styles to table body and header cells: + +- body cells: styles change based on values in the `status` field (`"Down"`, `"Up"`, `"Idle"`) and on total values greater than 40 or less than 5 +- header cells: style depends on the value in the `streaming` field — `"status-down"` for `"no"` and `"status-up"` for any other value ~~~jsx const widget = new pivot.Pivot("#pivot", { @@ -155,14 +161,17 @@ const widget = new pivot.Pivot("#pivot", { }); ~~~ -## Marking values in cells +## Mark values in cells + +Use the `marks` parameter of the [`tableShape`](/api/config/tableshape-property) property to mark cells that match specific conditions. -The widget API allows marking required values in cells. You can do it by applying the `marks` parameter of the [`tableShape`](/api/config/tableshape-property) property. You need to do the following: -- create a CSS class to be applied to the marked cell -- add the CSS class name as the parameter of the `marks` object -- set its value which can be a custom function or one of the predefined strings ("max", "min"). The function should return boolean for the checked value; if **true** is returned, the css class is assigned to the cell. +To configure `marks`: -In the example below, cells with min and max values are marked, and custom function is used to mark cells with values that are non-integer and greater than 2. +- create a CSS class to apply to the marked cell +- add the CSS class name as a key in the `marks` object +- set its value to a custom function or one of the predefined strings (`"max"`, `"min"`); the function receives the cell value and returns `true` to assign the CSS class + +The following code snippet marks cells with minimum and maximum values using built-in strings, and uses a custom function to mark non-integer values greater than 2: ~~~jsx {18-26} const table = new pivot.Pivot("#root", { @@ -213,9 +222,9 @@ const table = new pivot.Pivot("#root", { ~~~ -## Specific CSS classes +## Use built-in CSS classes -By default, in the table body numbers are aligned to the right with the help of the built-in `.wx-number` CSS class. The exception is the hierarchical column in the tree mode (when `tree` is set to **true** for the [`tableShape`](/api/config/tableshape-property) property). To reset the default number alignment, change the related CSS class. +By default, Pivot aligns numbers to the right using the built-in `.wx-number` CSS class. The hierarchical column in tree mode (when `tree` is `true` in [`tableShape`](/api/config/tableshape-property)) is an exception. To reset the default alignment, override the `.wx-number` class: ~~~html ~~~ -It's also possible to customize the style of total columns via the ` .wx-total` CSS class: +Use the `.wx-total` class to customize the style of total columns: ~~~html ~~~ -## Example - -In this snippet you can see how to apply a custom style to Pivot +The live example below demonstrates applying a custom style to Pivot: - + -**Related samples**: +**Related samples**: - [Pivot 2. Styling (custom CSS) for total column](https://snippet.dhtmlx.com/9lkdbzmm) - [Pivot 2. Min/max and custom marks for cells (conditional format)](https://snippet.dhtmlx.com/4cm4asbd) diff --git a/docs/guides/working-with-data.md b/docs/guides/working-with-data.md index c14a7b3..254bc8a 100644 --- a/docs/guides/working-with-data.md +++ b/docs/guides/working-with-data.md @@ -4,15 +4,15 @@ title: Working with Data description: You can explore how to work with Data in the documentation of the DHTMLX JavaScript Pivot library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Pivot. --- -# Working with data +# Work with data -This page describes how to aggregate data in Pivot. For the instructions about loading and exporting data refer to [Loading data](/guides/loading-data) and [Exporting data](/guides/exporting-data). +This page covers how to aggregate data in Pivot. For loading and exporting data, see [Loading data](/guides/loading-data) and [Exporting data](/guides/exporting-data). -## Defining fields +## Define fields -Use the [`fields`](/api/config/fields-property) property to add fields to the Pivot table. To add a new field, you should add a new object to the `fields` array. +Use the [`fields`](/api/config/fields-property) property to add fields to the Pivot table. Add a new object to the `fields` array for each field. -Example: +The following code snippet defines a basic `fields` array: ~~~jsx const table = new pivot.Pivot("#root", { @@ -28,11 +28,11 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Applying formats to fields +## Apply formats to fields -For the description of default formatting of date and numeric fields, which depends on locale, refer to [Date formatting](/guides/localization/#date-formatting) and [Number formatting](/guides/localization/#number-formatting). +For default formatting of date and number fields, see [Date formatting](/guides/localization/#date-formatting) and [Number formatting](/guides/localization/#number-formatting). -In case you need to set a custom format to a specific field, use the `format` parameter of the [`fields`](/api/config/fields-property) property. You can add text before and after numeric values using the `prefix` and `suffix` parameters. For example, to convert the value *12.345* to "12.35 EUR", `format` should contain the " EUR" suffix and maximumFractionDigits of 2: +Use the `format` parameter of the [`fields`](/api/config/fields-property) property to set a custom format for a specific field. Add text before or after numeric values with the `prefix` and `suffix` parameters. For example, to display `12.345` as `"12.35 EUR"`, set the `" EUR"` suffix and `maximumFractionDigits` to `2`: ~~~js const fields = [ @@ -40,7 +40,7 @@ const fields = [ ]; ~~~ -By default, the format for numeric values limits fraction digits to 3 and applies group separation for the integer part. You can cancel formatting by setting `format` to *false* in the `field` configuration: +By default, numeric values are limited to 3 fraction digits with group separation for the integer part. Set `format` to `false` to cancel formatting: ~~~js const fields = [ @@ -48,10 +48,10 @@ const fields = [ ]; ~~~ -In the example below, fields like marketing, profit, and sales are identified as currency-related. A formatting object is applied to these fields with: +The following code snippet applies currency formatting to the `marketing` field: -- prefix: "$" to display a dollar sign -- *minimumFractionDigits* and *maximumFractionDigits* set to 2 for consistent decimal formatting +- `prefix: "$"` — displays a dollar sign before the value +- `minimumFractionDigits` and `maximumFractionDigits` set to `2` — ensures consistent decimal formatting ~~~jsx // Initialize pivot with pre-defined dataset and fields @@ -75,7 +75,7 @@ new pivot.Pivot("#pivot", { }); ~~~ -To override the default locale-wide `dateFormat`, apply the `format` parameter of the [`fields`](/api/config/fields-property) property. Date format is a string, for example: +To override the locale-wide `dateFormat` for a specific field, set the `format` parameter of the [`fields`](/api/config/fields-property) property to a format string: ~~~jsx const fields = [ @@ -83,7 +83,7 @@ const fields = [ ]; ~~~ -In the example below we set the date format to "%d %M %Y %H:%i" for the "date" field only. The format displays day, full month name, year, hours, and minutes, e.g., "24 April 2025 14:30". In case you need to disable formatting of some fields, set the `format` parameter of the [`fields`](/api/config/fields-property) property to *false*. +The following code snippet sets the date format to `"%d %M %Y %H:%i"` for the `date` field (for example, `"24 April 2025 14:30"`). Set `format` to `false` to disable formatting for a field. ~~~jsx // Convert date strings to Date objects @@ -111,20 +111,20 @@ new pivot.Pivot("#pivot", { }, fields:[ // Custom format: Day Month Year Hour:Minute - {id:"date", label:"Date", type:"date", "%d %M %Y %H:%i"} + {id:"date", label:"Date", type:"date", format: "%d %M %Y %H:%i"} ] }); ~~~ :::note -By default, for the "xlsx" format, date and number fields are exported as raw values with default format or the format defined via the [`fields`](/api/config/fields-property) property. But if a template is defined for a field (see the [`tableShape`](/api/config/tableshape-property) property), it exports the rendered value defined by that template. In case both the template and `format` are set, the template settings will override the format ones. +By default, for the "xlsx" format, date and number fields export as raw values with the default format or the format defined via the [`fields`](/api/config/fields-property) property. If a template is defined for a field (see [`tableShape`](/api/config/tableshape-property)), the rendered value is exported instead. If both the template and `format` are set, the template takes precedence. ::: -## Defining Pivot structure +## Define the Pivot structure -You can create the Pivot structure using the [`config`](/api/config/config-property) property that also defines how data is aggregated. By default, it has no predefined values. You need to specify this property to define the configuration of the Pivot table, namely, which fields should be applied as columns and rows. The property also allows adding data aggregation methods to be applied to the fields. Here you can also add filters. Please, refer to the [`config`](/api/config/config-property) property description for details. +Use the [`config`](/api/config/config-property) property to define which fields apply as columns and rows, set data aggregation methods, and add filters. By default, `config` has no predefined values. See the [`config`](/api/config/config-property) property reference for details. -Example: +The following code snippet defines rows, columns, values, and a filter: ~~~jsx {4-18} const table = new pivot.Pivot("#root", { @@ -137,24 +137,23 @@ const table = new pivot.Pivot("#root", { "count(oil)", { field: "oil", method: "sum" }, { field: "gdp", method: "sum" } - ] - }, - fields, - filters: { - name: { - contains: "B" + ], + filters: { + name: { + contains: "B" + } } } }); ~~~ -## Sorting data +## Sort data -The widget API allows configuring the sorting settings that are applied to all areas (values, columns and rows) during aggregation. The sorting in UI is enabled by clicking the column header. +The widget supports sorting across all areas (rows, columns, and values) during aggregation. Users enable sorting in the UI by clicking column headers. -To set default sorting values, apply the **sort** parameter of the [`fields`](/api/config/fields-property) property. It accepts either the "asc" or "desc" value, or a custom sorting function. +Use the `sort` parameter of the [`fields`](/api/config/fields-property) property to set default sort order. It accepts `"asc"`, `"desc"`, or a custom sorting function. -In the example below we add clickable field labels and the sorting functionality that is enabled with the icon click: +The following code snippet adds clickable field labels with sort icons: ~~~jsx const bar = document.getElementById("bar"); @@ -210,7 +209,7 @@ const table = new pivot.Pivot("#root", { }); ~~~ -The sorting functionality is enabled by default. A user can click the column's header to sort data. To disable/enable sorting, apply the `sort` parameter of the [`columnShape`](/api/config/columnshape-property) property. In the example below we disable sorting. +Sorting is enabled by default. To disable or enable sorting, use the `sort` parameter of the [`columnShape`](/api/config/columnshape-property) property. The following code snippet disables sorting: ~~~jsx {19} const table = new pivot.Pivot("#root", { @@ -236,25 +235,25 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Filtering data +## Filter data -The widget allows you to set various filters for fields depending on the type of data. It's possible to specify filters both via the Pivot interface after initialization or through the corresponding API using the [`config`](/api/config/config-property) property. +Set filters for fields based on data type. Specify filters through the Pivot UI after initialization or via the [`config`](/api/config/config-property) property. In the UI, filters appear as drop-down lists for each field. -In GUI, filters appear as drop-down lists for each field. +### Filter types -#### Types of filters +Pivot supports the following condition types for filtering: -The Pivot widget provides the next condition types for filtering: +- text: `equal`, `notEqual`, `contains`, `notContains`, `beginsWith`, `notBeginsWith`, `endsWith`, `notEndsWith` +- number: `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `equal`, `notEqual`, `contains`, `notContains`, `beginsWith`, `notBeginsWith`, `endsWith`, `notEndsWith` +- date: `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `equal`, `notEqual`, `between`, `notBetween` -- for text values: equal, notEqual, contains, notContains, beginsWith, notBeginsWith, endsWith, notEndsWith -- for numeric values: greater: less, greaterOrEqual, lessOrEqual, equal, notEqual, contains, notContains, begins with, not begins with, ends with, not ends with -- for date types: greater, less, greaterOrEqual, lessOrEqual, equal, notEqual, between, notBetween +Use the `includes` rule to define the set of values to display. -The filter provides the **includes** filtering rule to define the set of values to be displayed. +### Add a filter -#### Adding a filter +Add the `filters` object with the field ID and filter type to the [`config`](/api/config/config-property) property. -To set a filter, add the **filters** object with the field ID and filter type to the [`config`](/api/config/config-property) property. +The following code snippet filters by `genre` and `title`: ~~~jsx const table = new pivot.Pivot("#root", { @@ -287,18 +286,30 @@ const table = new pivot.Pivot("#root", { ~~~ :::info -You can also filter data using the [`filter-rows`](/api/table/filter-rows) event of the Table widget by getting access to its API via the [`getTable`](/api/methods/gettable-method) method. +You can also filter data using the [`filter-rows`](/api/table/filter-rows) event of the Table widget by getting access to the Table widget API via the [`getTable`](/api/methods/gettable-method) method. ::: -## Limiting loaded data +### Track configuration changes + +Use the [`update-config`](/api/events/update-config-event) event to listen for changes made to rows, columns, values, or filters via the Pivot UI. This is useful for saving a user's configuration between sessions. -To interrupt data rendering and prevent the component from hanging, you can limit the number of rows and columns in the final dataset. To limit data, specify the values using the [`limits`](/api/config/limits-property) property. The values define when to interrupt rendering data. The limits are applied based on the rows/columns defined within the Pivot configuration. The default value for rows is 10 000 and for columns it's 5 000. +The following code snippet logs the updated config when the user modifies the Pivot structure: + +~~~jsx +table.api.on("update-config", (config) => { + console.log("Config updated:", config); +}); +~~~ + +## Limit loaded data + +Use the [`limits`](/api/config/limits-property) property to cap the number of rows and columns in the final dataset and prevent the component from hanging on large data. Limits apply based on the rows and columns defined in the Pivot config. The default limit is 10,000 rows and 5,000 columns. :::note -Limits are used for large dataset. Limits values are approximate values and do not show the exact values of the rows and columns. +Limits are used for large datasets. Limit values are approximate and do not reflect the exact number of rows and columns. ::: -Example: +The following code snippet sets a row limit of 10 and a column limit of 3: ~~~jsx const table = new pivot.Pivot("#root", { @@ -322,27 +333,29 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Applying maths methods +## Apply maths methods + +Pivot provides a set of predefined aggregation methods and supports adding custom ones. ### Default methods The widget provides the following default methods for data aggregation: -- sum (for numeric values only) - sums all the values of the selected data; empty cells, logical values like TRUE, or text are ignored -- min (for numeric and date values)- finds and displays the minimum value of the selected data; empty cells, logical values, or text in the array or reference are ignored. If the arguments contain no numbers, MIN returns 0 (zero) -- max (for numeric and date values) - finds the largest value in a set of values; the function ignores empty cells, the logical values TRUE and FALSE, and text values. If the arguments contain no numbers, MAX returns 0 (zero) -- count (for numeric, text, and date values) - looks for all occurrences of the selected data and displays their number; generally used to count a range of cells containing numbers or dates excluding blanks; this is the default operation assigned to each newly added field -- countunique (for numeric and text values) - сounts the number of unique values in a list of specified values and ranges -- average (for numeric values only) - calculates the average (arithmetic mean) of a group of numbers; logical values, empty cells and cells that contain text in the array or reference are ignored; cells with the value zero are included -- counta (for numeric, text, and date values) - returns the number of values in a dataset; counts numbers, dates, text or a range containing a mixture of these items, but does not count blank cells -- median (for numeric values only) - calculates the median of the given numbers -- product (for numeric values only) - calculates the product of all numbers in the given range -- stdev (for numeric values only) - calculates the standard deviation of the values, treating it as a sample of a bigger set of values -- stdevp (for numeric values only) - calculates the standard deviation of the values, treating it as the entire set of values -- var (for numeric values only) - calculates the variance of the values, treating it as a sample of a bigger set of values -- varp (for numeric values only) - calculates the variance of the values, treating it as the entire set of values - -Predefined methods: +- `sum` (number) — sums all values; ignores empty cells, logical values, and text +- `min` (number, date) — finds the minimum value; ignores empty cells, logical values, and text; returns `0` if no numbers are found +- `max` (number, date) — finds the maximum value; ignores empty cells, logical values, and text; returns `0` if no numbers are found +- `count` (number, text, date) — counts all occurrences of the selected data; the default operation for newly added fields +- `countunique` (number, text) — counts the number of unique values +- `average` (number) — calculates the arithmetic mean; ignores logical values, empty cells, and text; includes cells with zero +- `counta` (number, text, date) — counts all non-blank values including numbers, dates, and text +- `median` (number) — calculates the median of the given numbers +- `product` (number) — calculates the product of all numbers in the range +- `stdev` (number) — calculates the standard deviation treating the data as a sample +- `stdevp` (number) — calculates the standard deviation treating the data as the entire population +- `var` (number) — calculates the variance treating the data as a sample +- `varp` (number) — calculates the variance treating the data as the entire population + +The predefined method definitions: ~~~jsx const defaultMethods = { @@ -374,9 +387,9 @@ const defaultMethods = { }; ~~~ -You can apply default methods using the `values` parameter of the [`config`](/api/config/config-property) property. See [Options for defining values](#options-for-defining-values) below. +Apply default methods with the `values` parameter of the [`config`](/api/config/config-property) property. See [Define values](#define-values) below. -Example: +The following code snippet applies `count` and `max` methods: ~~~jsx const table = new pivot.Pivot("#root", { @@ -401,13 +414,14 @@ const table = new pivot.Pivot("#root", { }); ~~~ -### Options for defining values +### Define values + +Define `values` in either of two equivalent ways: -You can define `values`in either of the two equally valid ways: -- option one is a string representing a data field ID: `operation(fieldID)` -- option two is an object containing the field ID and the method for data aggregation (both are required): `{ field: string, method: string }` +- a string with the field ID and operation: `"operation(fieldID)"` +- an object with `field` and `method`: `{ field: string, method: string }` -Example: +The following code snippet shows both formats: ~~~jsx values: [ @@ -416,11 +430,11 @@ values: [ ] ~~~ -### Redefining the default method +### Redefine the default method -By default, the first available method for the data type is selected. You can redefine a method using the [`api.intercept()`](/api/internal/intercept-method) method. +By default, Pivot selects the first available method for the field's data type. Use [`api.intercept()`](/api/internal/intercept-method) to override this behavior. -In the example below, we check whether a new field is added, and set the **max** method in case a numeric field is added. +The following code snippet sets `max` as the default method when a numeric field is added to the `values` area: ~~~jsx {20-27} const table = new pivot.Pivot("#root", { @@ -452,11 +466,11 @@ table.api.intercept("add-field", (ev) => { }); ~~~ -### Adding custom maths methods +### Add custom maths methods -To add a custom method, use the [`methods`](/api/config/methods-property) property by setting the `key` parameter value to the method name and the `value` parameter should be a function that defines how a method should process data. The function should take an array of numerical values as an input and return a single numerical value. +Use the [`methods`](/api/config/methods-property) property to add a custom aggregation method. Set the key to the method name and provide a `handler` function that takes an array of values as input and returns a single value. -The example below shows how to calculate the count of unique and average values for the date type. The **countUnique** function takes an array of numbers (values) as an input and calculates the exact count of unique values using the **reduce** method. The **countunique_date** sub-property has a handler with a function that gets the unique values from an array of the date values. The **average_date** sub-property has a handler that calculates the average values from an array of the date values. +The following code snippet adds `countunique_date` and `average_date` methods for the date type: ~~~jsx function countUnique(values, converter) { @@ -542,10 +556,9 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Processing data with predicates +## Process data with predicates -Predicates or data modifiers allow you to process data in the required way before this data is used as rows or columns. -For example, you can pre-process the date format before applying and displaying data. The following predicates are applied by default: +Predicates (data modifiers) pre-process field values before Pivot uses them as rows or columns. For example, use a predicate to group dates by month or quarter before displaying. The following predicates apply by default: ~~~jsx const defaultPredicates = { @@ -559,17 +572,20 @@ const defaultPredicates = { }; ~~~ -To add a custom predicate, you should specify the parameters of the [`predicates`](/api/config/predicates-property) property: -- Add keys that are predicate IDs -- Add values that are objects with the predicate configuration: - - specify the `type` to define fields types for which the predicate can be applied ("number", "date", "text") - - add a label that will be displayed in GUI in the drop-down among data modifiers options for a row/column - - for the custom predicate, add the `handler` function that defines how data should be processed; the function takes a single argument as the value to be processed and returns the processed value - - if you want data to be displayed in the way other than the `handler` function returns, add the `template` that defines how data should be displayed (optional) - - if necessary, add the `field` function to specify how data should be filtered for the field - - apply the `filter` parameter if you need the filter type other than the one in the `type` parameter or in case you need the data format different from the `template` +To add a custom predicate, configure the [`predicates`](/api/config/predicates-property) property as follows: -You should also add the predicate id as the value of the `method` parameter for the row/column where this predicate should be applied. +- each key is a predicate ID +- each value is a configuration object with the following parameters: + - `type` — (required) the field types this predicate applies to: `"number"`, `"date"`, or `"text"` + - `label` — (optional) the label shown in the UI drop-down for rows and columns + - `handler` — (required for custom predicates) a function that takes a single value and returns the processed value + - `template` — (optional) a function that defines how the processed value is displayed + - `field` — (optional) a function that specifies how data is filtered for the field + - `filter` — (optional) overrides the filter type or format; use when the `type` filter or `template` format is not sufficient + +Set the predicate ID as the `method` value for the row or column where the predicate applies. + +The following code snippet defines two custom predicates: one groups dates by month-year, and the other labels profit sign: ~~~jsx const predicates = { @@ -622,13 +638,11 @@ const table = new pivot.Pivot("#pivot", { }); ~~~ -## Adding columns and rows with total values +## Add total rows and columns -To enable generating the rightmost column with total values, apply the [`tableShape`](/api/config/tableshape-property) property and set the value of the `totalColumn` parameter to **true**. +Use the `totalColumn` parameter of the [`tableShape`](/api/config/tableshape-property) property to add a rightmost column with total values. Use `totalRow` to add a footer row with totals. Set either to `true` to enable, or `"sumOnly"` to show totals only for sum operations. -To enable generating the footer with totals, apply the [`tableShape`](/api/config/tableshape-property)property and set the value of the `totalRow` parameter to **true**. - -**Example:** +The following code snippet enables both total row and total column: ~~~jsx {2-5} const table = new pivot.Pivot("#root", { @@ -663,11 +677,9 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Example - -In this snippet you can see how to apply custom maths operations: +The live example below demonstrates custom maths operations: - + **Related samples:**