diff --git a/docs/api/config/columnshape-property.md b/docs/api/config/columnshape-property.md index f864244..ea6134a 100644 --- a/docs/api/config/columnshape-property.md +++ b/docs/api/config/columnshape-property.md @@ -19,10 +19,10 @@ columnShape?: { [field: string]: number }, autoWidth?: { - columns?: { + columns: { [field: string]: boolean }, - auto: boolean | "header" | "data", + auto?: boolean | "header" | "data", maxRows?: number, firstOnly?: boolean } @@ -34,9 +34,9 @@ columnShape?: { - `sort` - (optional) if **true** (default), the sorting is enabled in UI by clicking the column header; if **false**, the sorting is disabled - `width` - (optional) defines the width of a column; it's an object where each key is a field id and the value is the width of the column in pixels - `autoWidth` - (optional) an object that defines how column width should be calculated automatically. The default configuration uses 20 rows, and the width is calculated based on the header and data, with each field analyzed only once. The object parameters are the following: - - `columns` - (optional) an object where each key is a field id and the boolean value defines whether column width should be calculated automatically - - `auto` - (required) if set to **header**, adjusts the width to the header text; if set to **data**, adjusts the width to the cell with the widest content; if set to **true**, the width is adjusted to the content of both headers and cell. - If autowidth is set to **false**, the `width` value is set or the value of the `columnWidth` from the [`tableShape`](/api/config/tableshape-property) property is applied. + - `columns` - (required) an object where each key is a field id and the boolean value defines whether column width should be calculated automatically + - `auto` - (optional) if set to **header**, adjusts the width to the header text; if set to **data**, adjusts the width to the cell with the widest content; if set to **true**, the width is adjusted to the content of both headers and cell. + If autowidth is set to **false**, the `width` value is set or the value of the `columnWidth` from the [`tableShape`](api/config/tableshape-property.md) property is applied. - `maxRows` - (optional) the number of rows to be processed for the autoWidth calculation - `firstOnly` - (optional) if 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 diff --git a/docs/api/config/config-property.md b/docs/api/config/config-property.md index 8c3af3c..ce8fcce 100644 --- a/docs/api/config/config-property.md +++ b/docs/api/config/config-property.md @@ -27,14 +27,14 @@ The `config` parameters are used to define which fields will be applied as rows - `rows` - (optional) defines the rows of the Pivot table. The default value is an empty array. It can be a string which represents a single field ID or an object with the field ID and a method for data extraction; the object parameters are the following: - `field` - (required) the ID of a field - - `method` - (optional) defines a method for data aggregation in the field; methods for the time-based data fields are available by default: year, month, day, hour, minute which group data by year/month/day/hour; here you can also add the name of a custom method ([see `predicates`](/api/config/predicates-property)) for the field of any data type + - `method` - (optional) defines a method for data aggregation in the field; methods for the time-based data fields are available by default: "year", "quarter", "month", "week", "day", "hour", "minute" which group data accordingly; here you can also add the name of a custom method ([see `predicates`](api/config/predicates-property.md)) for the field of any data type - `columns` - (optional) defines columns for the Pivot table. It's an empty array by default. It can be a single field ID or an object with the field ID and a method for data extraction; the object parameters are the following: - `field` - (required) the ID of a field - `method` - (optional) defines a method for data processing (for time-based data fields). - By default, methods are available for the time-based fields (the **date** type) with the next values: "year", "quarter", "month", "week", "day", "hour", "minute". Here you can also add the name of a custom method ([see `predicates`](/api/config/predicates-property)) for the field of any data type + By default, methods are available for the time-based fields (the **date** type) with the next values: "year", "quarter", "month", "week", "day", "hour", "minute". Here you can also add the name of a custom method ([see `predicates`](api/config/predicates-property.md)) for the field of any data type - `values` - (optional) defines the data aggregation for the cells of the Pivot table. It's an empty array by default. Each element can be a string representing a data field ID and aggregation method or an object containing the field ID and the method for data aggregation. The object parameters are the following: - `field` - (required) the ID of a field - - `method` - (required) defines a method for data extraction; for methods types and their description refer to [Applying methods](/guides/working-with-data#default-methods) + - `method` - (required) defines a method for data extraction; for methods types and their description refer to [Applying methods](guides/working-with-data.md#default-methods)
@@ -49,7 +49,7 @@ You can define `values` in either of the two equally valid ways: ~~~jsx values: [ "sum(sales)", // option one - { id: "sales", method: "sum" }, // option two + { field: "sales", method: "sum" }, // option two ] ~~~ @@ -78,7 +78,7 @@ values: [ - `includes` - (optional) an array of values to be displayed from those that are already filtered; available for text and dates values :::info -When config is processed by Pivot, its properties receive extra data and if you try to return the config state via the [`api.getState()`](/api/internal/getstate-method) method, the full object will look like this: +When config is processed by Pivot, its properties receive extra data and if you try to return the config state via the [`api.getState()`](api/internal/getstate-method.md) method, the full object will look like this: ~~~jsx interface IParsedField { diff --git a/docs/api/config/configpanel-property.md b/docs/api/config/configpanel-property.md index 928f43b..4d0c92c 100644 --- a/docs/api/config/configpanel-property.md +++ b/docs/api/config/configpanel-property.md @@ -53,6 +53,6 @@ const table = new pivot.Pivot("#root", { **Related sample:** [Pivot 2.0: Toggle visibility of configuration panel](https://snippet.dhtmlx.com/1xq1x5bo) **Related articles:** -- [`show-config-panel` event](/api/events/show-config-panel-event) -- [`showConfigPanel()` method](/api/methods/showconfigpanel-method) -- [Controlling visibility of Configuration panel](/guides/configuration#controlling-visibility-of-configuration-panel) +- [`show-config-panel` event](api/events/show-config-panel-event.md) +- [`showConfigPanel()` method](api/methods/showconfigpanel-method.md) +- [Controlling visibility of Configuration panel](guides/configuration.md#controlling-visibility-of-configuration-panel) diff --git a/docs/api/config/fields-property.md b/docs/api/config/fields-property.md index 6dd054b..fc5cb21 100644 --- a/docs/api/config/fields-property.md +++ b/docs/api/config/fields-property.md @@ -32,21 +32,21 @@ Each object in the `fields` array should have the following properties: - `id` - (required) the ID of a field - `label` - (optional) the field label to be displayed in GUI -- `type` - (required) data type in a field ( "number", "date", or "string") +- `type` - (required) data type in a field ( "number", "date", or "text") - `sort` - (optional) defines the default sorting order for the field. Accepts "asc", "desc", or a custom sorting function -- `format` - (optional) allows customizing the format of numbers and dates in a field; the format will be also applied during [export](/guides/exporting-data) +- `format` - (optional) allows customizing the format of numbers and dates in a field; the format will be also applied during [export](guides/exporting-data.md) - `string` - (optional) the format for dates (by default, Pivot uses `dateFormat` from locale) - `boolean` - (optional) if set to **false**, a number is displayed as is, without any formatting - `numberFormatOptions` - (optional) an object with options for formatting numeric fields; by default, numbers will be shown with a maximum of 3 decimal digits and group separation for the integer part is applied. - `minimumIntegerDigits`(number) - (optional) the minimum number of integer (for example, if the value is set to 2, the number 1 will be shown as "01"); the default is 1; - - `minimumFractionDigits`(number) - (optional) the minimum number of fraction digits to use (for example, if the value is set to 2, the number 10.5 will be shown as "10.50"); the default is 1; + - `minimumFractionDigits`(number) - (optional) the minimum number of fraction digits to use (for example, if the value is set to 2, the number 10.5 will be shown as "10.50"); the default is 0; - `maximumFractionDigits`(number) - (optional) the maximum number of fraction digits to use (for example, if the value is set to 2, the number 10.3333... will be shown as "10.33"); the default is 3; For more details about digit options refer to [Digit options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#minimumintegerdigits) - `prefix` (string) - (optional) a string (before a number) for additional symbols like currency - `suffix` (string) - (optional) a string (after a number) for additional symbols like currency :::info -If a template is applied via the [`tableShape`](/api/config/tableshape-property) property, it will override the `format` settings. +If a template is applied via the [`tableShape`](api/config/tableshape-property.md) property, it will override the `format` settings. ::: ### Example @@ -106,7 +106,7 @@ const table = new pivot.Pivot("#root", { **Related articles**: -- [Number formatting](/guides/localization/#number-formatting) -- [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields) +- [Number formatting](guides/localization.md#number-formatting) +- [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields) **Related sample:** [Pivot 2. Defining fields formats](https://snippet.dhtmlx.com/77nc4j8v) \ No newline at end of file diff --git a/docs/api/config/headershape-property.md b/docs/api/config/headershape-property.md index 97fa1a8..5608770 100644 --- a/docs/api/config/headershape-property.md +++ b/docs/api/config/headershape-property.md @@ -76,8 +76,8 @@ new pivot.Pivot("#pivot", { **Related samples**: - [Pivot 2. Vertical orientation of text in grid headers](https://snippet.dhtmlx.com/4qroi8ka) - [Pivot 2. Collapsible columns](https://snippet.dhtmlx.com/pt2ljmcm) -- [Pivot 2. Adding сustom CSS for table and header cells](https://snippet.dhtmlx.com/nfdcs4i2) +- [Pivot 2. Adding custom CSS for table and header cells](https://snippet.dhtmlx.com/nfdcs4i2) **Related articles**: -- [Configuration](/guides/configuration) -- [Cell style](/guides/stylization/#cell-style) +- [Configuration](guides/configuration.md) +- [Cell style](guides/stylization.md#cell-style) diff --git a/docs/api/config/limits-property.md b/docs/api/config/limits-property.md index 6bb997f..4b6c54e 100644 --- a/docs/api/config/limits-property.md +++ b/docs/api/config/limits-property.md @@ -10,7 +10,7 @@ description: You can learn about the limits config in the documentation of the D @short: Optional. Defines the maximum limit for the number of rows and columns in the final dataset -Please, also refer to [Limiting data](/guides/working-with-data#limiting-loaded-data). +Please, also refer to [Limiting data](guides/working-with-data.md#limiting-loaded-data). ### Usage diff --git a/docs/api/config/locale-property.md b/docs/api/config/locale-property.md index af2375b..96b0b6d 100644 --- a/docs/api/config/locale-property.md +++ b/docs/api/config/locale-property.md @@ -18,10 +18,10 @@ locale?: object; ### Default config -By default, Pivot uses the [English](/guides/localization/#default-locale) locale. You can set it to the custom locale as well. +By default, Pivot uses the [English](guides/localization.md#default-locale) locale. You can set it to the custom locale as well. :::tip -To change the current locale dynamically, you can use the [`setLocale()`](/api/methods/setlocale-method) method of Pivot +To change the current locale dynamically, you can use the [`setLocale()`](api/methods/setlocale-method.md) method of Pivot ::: ### Example diff --git a/docs/api/config/methods-property.md b/docs/api/config/methods-property.md index f8b6c93..d3702f7 100644 --- a/docs/api/config/methods-property.md +++ b/docs/api/config/methods-property.md @@ -68,7 +68,7 @@ defaultMethods = { }; ~~~ -The definition of each method you can see here: [Applying methods](/guides/working-with-data#default-methods) +The definition of each method you can see here: [Applying methods](guides/working-with-data.md#default-methods) ## Example @@ -160,4 +160,4 @@ const table = new pivot.Pivot("#root", { **Related sample:** [Pivot 2. Custom maths methods](https://snippet.dhtmlx.com/lv90d8q2) -**Related article**: [Applying maths methods](/guides/working-with-data#applying-maths-methods) +**Related article**: [Applying maths methods](guides/working-with-data.md#applying-maths-methods) diff --git a/docs/api/config/predicates-property.md b/docs/api/config/predicates-property.md index e014e43..f7a4406 100644 --- a/docs/api/config/predicates-property.md +++ b/docs/api/config/predicates-property.md @@ -41,12 +41,14 @@ The property is an object where a key is the name of a custom function and value - `type` - (optional) defines which field type will be applied: "number"|"text"|"date"|"tuple". "tuple" is a combo filter applied for numeric values (data will be filtered by the numeric value but in filter the text value will be displayed) - `format` - (optional) the function that defines the format for displaying filter options; if no format is defined, the one from the template parameter will be applied; if the type here (for the `filter` object) is not specified, the format will be applied for the type set for the `type` parameter of the predicate - `handler` - (required for custom predicates) the function that defines how data should be processed; the function should take a single argument as the value to be processed and return the processed value -- `template` - (optional) the function that defines how data should be displayed; the function returns the processed value and it takes the value returned by `handler` and if necessary you can localize text values using [`locale`](/api/config/locale-property). +- `template` - (optional) the function that defines how data should be displayed; the function returns the processed value and it takes the value returned by `handler` and if necessary you can localize text values using [`locale`](api/config/locale-property.md). The following default predicates are applied in case no predicate is specified via the `predicates` property: ~~~jsx const defaultPredicates = { + // a service predicate that represents the raw (unprocessed) value + $empty: { label: (type) => `Raw ${type}`, type: ["number", "date", "text"] }, year: { label: "Year", type: "date", filter: { type: "number" } }, quarter: { label: "Quarter", type: "date", filter: { type: "tuple" } }, month: { label: "Month", type: "date", filter: { type: "tuple" } }, @@ -110,6 +112,6 @@ const table = new pivot.Pivot("#pivot", { }); ~~~ -**Related article**: [Processing data with predicates](/guides/working-with-data#processing-data-with-predicates) +**Related article**: [Processing data with predicates](guides/working-with-data.md#processing-data-with-predicates) **Related sample**: [Pivot 2. Custom predicates](https://snippet.dhtmlx.com/mhymus00) diff --git a/docs/api/config/tableshape-property.md b/docs/api/config/tableshape-property.md index d07bc93..fe1b8b0 100644 --- a/docs/api/config/tableshape-property.md +++ b/docs/api/config/tableshape-property.md @@ -54,7 +54,7 @@ tableShape?: { - `templates` - (optional) allows setting templates to a cell; it's an object where: - each key is a field id - the value is a function that returns a string and receives cell value and operation. All columns based on the specified field will have the related template applied. For example, it allows setting the units of measurement or returning the required number of digits after the decimal point for numeric values, etc. See the example below. -- `marks` - (optional) allows marking a cell with the required values. It's an object where keys are CSS class names and values are either a 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. More information with examples see here [Marking cells](/guides/stylization#cell-style). +- `marks` - (optional) allows marking a cell with the required values. It's an object where keys are CSS class names and values are either a 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. More information with examples see here [Marking cells](guides/stylization.md#cell-style). - `sizes` - (optional) defines the following size parameters of the table: - `rowHeight` - (optional) the row height in the Pivot table in pixels. The default value is 34 - `headerHeight` - (optional) the header height in pixels; the default value is 30 @@ -67,12 +67,12 @@ tableShape?: { - `method` - (optional) a string that can represent the operation performed on a cell (e.g., "sum", "count", etc.) - `isTotal` - (optional) defines whether a cell belongs to a total row, total column, or both: "row"|"column"|"both The `cellStyle` function returns a string, which can be used as a CSS class name to apply specific styles to a cell. -- `tree` - (optional) if set to **true**, enables the tree mode when data can be presented with expandable rows, the default value is **false**. More information with examples see here [Switching to the tree mode](/guides/configuration/#enabling-the-tree-mode) +- `tree` - (optional) if set to **true**, enables the tree mode when data can be presented with expandable rows, the default value is **false**. More information with examples see here [Switching to the tree mode](guides/configuration.md#enabling-the-tree-mode) - `totalColumn` - (optional) if **true**, enables generating the total column with total values for rows (**false** is set by default). If the value is set to "sumOnly", the column with the total sum value will be generated (available only for sum operations) - `totalRow` - (optional) if **true**, enables generating the footer with total values (**false** is set by default). If the value is set to "sumOnly", the row with the total row value will be generated (available only for sum operations) - `cleanRows` - (optional) if set to **true**, the duplicate values in scale columns are hidden in the table view. The default value is **false** -- `split` - (optional) allows freezing columns on the right or left depending on the parameter specified (refer to [Freezing columns](/guides/configuration/#freezing-columns)): - - `left` (boolean) - if set to **true** (**false** is set by default), fixes the columns from the left, which makes columns static and visible while scrolling. 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 +- `split` - (optional) allows freezing columns on the right or left depending on the parameter specified (refer to [Freezing columns](guides/configuration.md#freezing-columns)): + - `left` (boolean) - if set to **true** (**false** is set by default), fixes the columns from the left, which makes columns static and visible while scrolling. 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.md) property - `right` (boolean) - fixes total columns on the right; default value is **false** By default, `tableShape` is undefined, implying that no total row, no total column is present, no templates and marks are applied, the data is shown as a table and not a tree, and columns are not fixed during scroll. @@ -124,8 +124,8 @@ const table = new pivot.Pivot("#root", { - [Pivot 2. Frozen (fixed) columns](https://snippet.dhtmlx.com/lahf729o) - [Pivot 2. Set row, header, footer height and all columns width](https://snippet.dhtmlx.com/x46uyfy9) - [Pivot 2. Clean rows](https://snippet.dhtmlx.com/rwwhgv2w?tag=pivot) -- [Pivot 2. Adding сustom CSS for table and header cells](https://snippet.dhtmlx.com/nfdcs4i2) +- [Pivot 2. Adding custom CSS for table and header cells](https://snippet.dhtmlx.com/nfdcs4i2) **Related articles**: -- [Configuration](/guides/configuration) -- [Cell style](/guides/stylization/#cell-style) +- [Configuration](guides/configuration.md) +- [Cell style](guides/stylization.md#cell-style) diff --git a/docs/api/events/add-field-event.md b/docs/api/events/add-field-event.md index cd026da..ce9b1e5 100644 --- a/docs/api/events/add-field-event.md +++ b/docs/api/events/add-field-event.md @@ -29,17 +29,17 @@ The callback of the action takes an object with the following parameters: - `area` - (required) the name of the area where a new field is added, which can be "rows", "columns" or "values" area - `field` - (required) the name of a field - `method` - (optional) defines a method for data aggregation (if not specified, the first method suitable for this data type is set); a method can be one of the following: - - it's required for the **values** area, it's a string with one of the data operation types: [Default methods](/guides/working-with-data#default-methods) + - it's required for the **values** area, it's a string with one of the data operation types: [Default methods](guides/working-with-data.md#default-methods) - it's optional for the **rows** and **columns** areas and if the value is set it's a predicate; it can be a custom predicate or one from default values: "year", "quarter", "month", "week", "day", "hour", "minute". By default, a raw value is set. - If a custom predicate or method is set, the id should be specified for the [predicates](/api/config/predicates-property) or [methods](/api/config/methods-property) property. + If a custom predicate or method is set, the id should be specified for the [predicates](api/config/predicates-property.md) or [methods](api/config/methods-property.md) property. :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Example -In the example below we use the [`api.intercept()`](/api/internal/intercept-method) method to add a new method to the value field with the **number** data type: +In the example below we use the [`api.intercept()`](api/internal/intercept-method.md) method to add a new method to the value field with the **number** data type: ~~~jsx {20-27} const table = new pivot.Pivot("#root", { @@ -71,4 +71,4 @@ table.api.intercept("add-field", (ev) => { }); ~~~ -**Related articles**: [api.intercept()](/api/internal/intercept-method) +**Related articles**: [api.intercept()](api/internal/intercept-method.md) diff --git a/docs/api/events/apply-filter-event.md b/docs/api/events/apply-filter-event.md index 517788f..96d17c5 100644 --- a/docs/api/events/apply-filter-event.md +++ b/docs/api/events/apply-filter-event.md @@ -26,13 +26,13 @@ The callback of the action takes an object with the following parameters: - `field` - (required) the field id to which filter will be applied - `filter` - (required) filter type: - for text values: equal, notEqual, contains, notContains, beginsWith, notBeginsWith, endsWith, notEndsWith - - for numeric values: greater: less, greaterOrEqual, lessOrEqual, equal, notEqual, contains, notContains + - for numeric values: greater, less, greaterOrEqual, lessOrEqual, equal, notEqual, contains, notContains - for date types: greater, less, greaterOrEqual, lessOrEqual, equal, notEqual, between, notBetween - - `value` - (required) the value to filter by - - `includes` - (required) an array of values to be displayed from those that are already filtered; available for text and date values + - `value` - (optional) the value to filter by + - `includes` - (optional) an array of values to be displayed from those that are already filtered; available for text and date values :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Example @@ -62,4 +62,4 @@ table.api.on("apply-filter", (ev) => { }); ~~~ -**Related articles**: [api.on()](/api/internal/on-method) +**Related articles**: [api.on()](api/internal/on-method.md) diff --git a/docs/api/events/delete-field-event.md b/docs/api/events/delete-field-event.md index 0f32c84..12cb966 100644 --- a/docs/api/events/delete-field-event.md +++ b/docs/api/events/delete-field-event.md @@ -27,12 +27,12 @@ The callback of the action takes an object with the following parameters: - `id` - (required) the id of a field that is removed :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Example -In the example below, the `delete-field` action is triggered via the [`api.exec()`](/api/internal/exec-method) method. The last field is removed from the **values** area. The [`api.getState()`](/api/internal/getstate-method) method here is used to get the current state of the Pivot [`config`](/api/config/config-property). The action will be triggered with the button click. +In the example below, the `delete-field` action is triggered via the [`api.exec()`](api/internal/exec-method.md) method. The last field is removed from the **values** area. The [`api.getState()`](api/internal/getstate-method.md) method here is used to get the current state of the Pivot [`config`](api/config/config-property.md). The action will be triggered with the button click. ~~~jsx {31-34} const table = new pivot.Pivot("#root", { diff --git a/docs/api/events/move-field-event.md b/docs/api/events/move-field-event.md index 8162524..c4aef5c 100644 --- a/docs/api/events/move-field-event.md +++ b/docs/api/events/move-field-event.md @@ -16,8 +16,8 @@ description: You can learn about the move-field event in the documentation of th "move-field": ({ area: string, id: string | number, - before?: id, - after?: id + before?: string, + after?: string }) => void | boolean; ~~~ @@ -31,7 +31,7 @@ The callback of the action takes an object with the following parameters: - `after` - (optional) the id of a field after which the moved field is placed :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Example @@ -62,4 +62,4 @@ table.api.on("move-field", (ev) => { }); ~~~ -**Related articles**: [api.on()](/api/internal/on-method) +**Related articles**: [api.on()](api/internal/on-method.md) diff --git a/docs/api/events/open-filter-event.md b/docs/api/events/open-filter-event.md index 8b4796c..256cf26 100644 --- a/docs/api/events/open-filter-event.md +++ b/docs/api/events/open-filter-event.md @@ -27,7 +27,7 @@ The callback of the action takes the next parameters: - `id` - the id of a field; if there's a single id argument with null value, the filter will be closed. :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Returns diff --git a/docs/api/events/render-table-event.md b/docs/api/events/render-table-event.md index 9137b67..324321e 100644 --- a/docs/api/events/render-table-event.md +++ b/docs/api/events/render-table-event.md @@ -42,13 +42,13 @@ The callback of the action takes the `config` object with the following paramete - `columns` - (optional) columns array with the next parameters for each object: - `id` (number) - (required) the id of a column - - `cell` (any) - (optional) a template with the cell content (please, refer to [Adding templates via the template helper](/guides/configuration/#adding-a-template-via-the-template-helper)) - - `template` - (optional) the template that is defined via the [`tableShape`](/api/config/tableshape-property) property + - `cell` (any) - (optional) a template with the cell content (please, refer to [Adding templates via the template helper](guides/configuration.md#adding-a-template-via-the-template-helper)) + - `template` - (optional) the template that is defined via the [`tableShape`](api/config/tableshape-property.md) property - `fields` (array) - (optional) defines fields in the hierarchical column in the tree mode. Reflects fields displayed in this column on different levels - `field` - (optional) it's a string which is the id of a field - `method` (string) - (optional) a method, if defined for a field in this column - `methods` (array) - (optional) defines methods applied to fields in the hierarchical column in the tree mode - - `format` (string or object) - (required) date format or number format (refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)) + - `format` (string or object) - (required) date format or number format (refer to [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields)) - `isNumeric` (boolean) - (optional) defines whether a column contains numeric values - `isTotal` (boolean) - (optional) defines whether it is a total column - `area` (string) - (optional) an area where the column is rendered: "rows", "columns", "values" @@ -59,7 +59,7 @@ The callback of the action takes the `config` object with the following paramete - `value` (any) - (required) raw value, if a cell belongs to "columns" area - `field` (string) - (required) a field, which value is displayed, if a cell belongs to "columns" area - `method` (string) - (required) the field predicate, if a cell belongs to "columns" area and predicate is defined - - `format` (string or object) - date format or number format (refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)) + - `format` (string or object) - date format or number format (refer to [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields)) - `footer` - (optional) a header label or an object with footer settings which are the same as the header settings - `data` - (optional) an array of objects with data for the table; each object represents a row: - `id` (number) - (required) row id @@ -72,10 +72,10 @@ The callback of the action takes the `config` object with the following paramete - `left` (number) - the number of fixed columns from the left - `right` (number) - the number of fixed columns from the right - `tree` - (optional) defines if the tree mode is enabled (**true** if enabled) -- `cellStyle` - (optional) an object where each key is the 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. +- `cellStyle` - (optional) a function that applies a custom style to a cell. It receives the row and column objects and returns a string with a CSS class name: `(row, col) => string` :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Returns @@ -85,7 +85,7 @@ If the event handler returns **false**, it will block the operation in question. ### Example -The next example shows how to output the [`config`](/api/config/config-property) object to console and add a footer. +The next example shows how to output the [`config`](api/config/config-property.md) object to console and add a footer. ~~~jsx {20-28} const table = new pivot.Pivot("#root", { @@ -118,7 +118,7 @@ table.api.intercept("render-table", (ev) => { }); ~~~ -The next example shows how to make all rows expand/collapse with the button click. The tree mode should be enabled via the [`tableShape`](/api/config/tableshape-property) property. +The next example shows how to make all rows expand/collapse with the button click. The tree mode should be enabled via the [`tableShape`](api/config/tableshape-property.md) property. ~~~jsx const table = new pivot.Pivot("#root", { @@ -152,7 +152,7 @@ const table = new pivot.Pivot("#root", { }); const api = table.api; -const table = api.getTable(); +const tableApi = api.getTable(); // setting all table branches closed on the table config update api.intercept("render-table", (ev) => { @@ -163,16 +163,16 @@ api.intercept("render-table", (ev) => { }); function openAll() { - table.exec("open-row", { id: 0, nested: true }); + tableApi.exec("open-row", { id: 0, nested: true }); } function closeAll() { - table.exec("close-row", { id: 0, nested: true }); + tableApi.exec("close-row", { id: 0, nested: true }); } ~~~ -See also how to configure the split feature using the `render-table` event: [Freezing columns](/guides/configuration#freezing-columns). +See also how to configure the split feature using the `render-table` event: [Freezing columns](guides/configuration.md#freezing-columns). -**Related article:** [pivot.template helper](/api/helpers/template) +**Related article:** [pivot.template helper](api/helpers/template.md) **Related sample:** [Pivot 2. Custom frozen (fixed) columns (your number)](https://snippet.dhtmlx.com/53erlmgp) diff --git a/docs/api/events/show-config-panel-event.md b/docs/api/events/show-config-panel-event.md index aab0430..d4ab871 100644 --- a/docs/api/events/show-config-panel-event.md +++ b/docs/api/events/show-config-panel-event.md @@ -25,7 +25,7 @@ The callback of the action takes an object with the following parameter: - `mode` - (required) if the value is set to **true** (default), the Configuration panel is shown, and it's set to **false** when the Configuration panel is hidden :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Example @@ -56,5 +56,5 @@ table.api.exec("show-config-panel", { ~~~ **Related articles**: -- [`showConfigPanel()` method](/api/methods/showconfigpanel-method) -- [`configPanel` property](/api/config/configpanel-property) +- [`showConfigPanel()` method](api/methods/showconfigpanel-method.md) +- [`configPanel` property](api/config/configpanel-property.md) diff --git a/docs/api/events/update-config-event.md b/docs/api/events/update-config-event.md index 7e2b46c..9ccce91 100644 --- a/docs/api/events/update-config-event.md +++ b/docs/api/events/update-config-event.md @@ -25,7 +25,7 @@ The action is useful for saving a user's aggregation configuration so that it ca ### Parameters -The callback of the action takes an object with the processed [`config`](/api/config/config-property) parameters: +The callback of the action takes an object with the processed [`config`](api/config/config-property.md) parameters: - `rows` - rows of the Pivot table. An object with the field ID and a method for data extraction; the object parameters are the following: - `field` - the ID of a field @@ -36,11 +36,11 @@ The callback of the action takes an object with the processed [`config`](/api/co By default, methods are available for the time-based fields (the **date** type) with the next values: "year", "quarter", "month", "week", "day", "hour", "minute" - `values` - defines the data aggregation for the cells of the Pivot table. It's an object containing the field ID and the method for data aggregation. The object parameters are the following: - `field` - the ID of a field - - `method` - defines a method for data extraction; about methods and possible options refer to [Applying methods](/guides/working-with-data#default-methods) -- `filters` - (optional) defines how data is filtered in the table; it's an object with field IDs and data aggregation method. The description of the `filter` object you can see here: [`config`](/api/config/config-property) + - `method` - defines a method for data extraction; about methods and possible options refer to [Applying methods](guides/working-with-data.md#default-methods) +- `filters` - (optional) defines how data is filtered in the table; it's an object with field IDs and data aggregation method. The description of the `filter` object you can see here: [`config`](api/config/config-property.md) :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Returns @@ -59,11 +59,11 @@ const table = new pivot.Pivot("#root", { columns: [], values: [ { - id: "title", + field: "title", method: "count" }, { - id: "score", + field: "score", method: "max" } ] @@ -75,4 +75,4 @@ table.api.on("update-config", (config) => { }); ~~~ -**Related articles**: [api.intercept()](/api/internal/intercept-method) +**Related articles**: [api.intercept()](api/internal/intercept-method.md) diff --git a/docs/api/events/update-value-event.md b/docs/api/events/update-field-event.md similarity index 84% rename from docs/api/events/update-value-event.md rename to docs/api/events/update-field-event.md index e14c7fe..320e93e 100644 --- a/docs/api/events/update-value-event.md +++ b/docs/api/events/update-field-event.md @@ -26,13 +26,13 @@ The callback of the action takes an object with the following parameters: - `id` - (required) the id of a field that is updated - `method` - (required) the method can be one of the following: - - for the **values** area, it's a string with one of the data operation types: [Default methods](/guides/working-with-data#default-methods) + - for the **values** area, it's a string with one of the data operation types: [Default methods](guides/working-with-data.md#default-methods) - for the **rows** and **columns** areas it can be data predicate value with one of the next values: "year", "quarter", "month", "week", "day", "hour", "minute". By default, a raw value is set. - If a custom predicate or method is set, the id should be specified for the [predicate](/api/config/predicates-property) or [methods](/api/config/methods-property) property. + If a custom predicate or method is set, the id should be specified for the [predicate](api/config/predicates-property.md) or [methods](api/config/methods-property.md) property. - `area` - (required) the name of the area where a field is updated, which can be "rows", "columns" or "values" area :::info -For handling the inner events you can use the [Event Bus methods](/api/overview/internal-eventbus-overview) +For handling the inner events you can use the [Event Bus methods](api/overview/internal-eventbus-overview.md) ::: ### Example @@ -63,5 +63,5 @@ table.api.on("update-field", (ev) => { ~~~ **Related articles**: -- [api.on()](/api/internal/on-method) -- [methods](/api/config/methods-property) +- [api.on()](api/internal/on-method.md) +- [methods](api/config/methods-property.md) diff --git a/docs/api/helpers/template.md b/docs/api/helpers/template.md index dedf461..1172023 100644 --- a/docs/api/helpers/template.md +++ b/docs/api/helpers/template.md @@ -35,13 +35,13 @@ For body cells the function takes the next parameters: - `$level` (boolean)- (optional) branch index - `column` - (required) an object with column data: - `id` (number) - (required) the id of a column - - `cell` (any) - (optional) a template with the cell content (please, refer to [Adding templates via the template helper](/guides/configuration/#adding-a-template-via-the-template-helper)) - - `template` - (optional) the template that is defined via the [`tableShape`](/api/config/tableshape-property) property + - `cell` (any) - (optional) a template with the cell content (please, refer to [Adding templates via the template helper](guides/configuration.md#adding-a-template-via-the-template-helper)) + - `template` - (optional) the template that is defined via the [`tableShape`](api/config/tableshape-property.md) property - `fields` (array) - (optional) defines fields in the hierarchical column in the tree mode. Reflects fields displayed in this column on different levels - `field` - (optional) it's a string which is the id of a field - `method` (string) - (optional) a method, if defined for a field in this column - `methods` (array) - (optional) defines methods applied to fields in the hierarchical column in the tree mode - - `format` (string or object) - (required) date format or number format (please refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)) + - `format` (string or object) - (required) date format or number format (please refer to [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields)) - `isNumeric` (boolean) - (optional) defines whether a column contains numeric values - `isTotal` (boolean) - (optional) defines whether it is a total column - `area` (string) - (optional) an area where the column is rendered: "rows", "columns", "values" @@ -52,7 +52,7 @@ For body cells the function takes the next parameters: - `value` (any) - (required) raw value, if a cell belongs to "columns" area - `field` (string) - (required) a field, which value is displayed, if a cell belongs to "columns" area - `method` (string) - (required) the field predicate, if a cell belongs to "columns" area and predicate is defined - - `format` (string or object) - date format or number format (please refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)) + - `format` (string or object) - date format or number format (please refer to [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields)) For header cells the function parameters are the following: @@ -66,12 +66,12 @@ For header cells the function parameters are the following: - `value` (any) - (required) raw value, if a cell belongs to "columns" area - `field` (string) - (required) a field, which value is displayed, if a cell belongs to "columns" area - `method` (string) - (required) a field predicate, if a cell belongs to "columns" area and predicate is defined - - `format` (string or object) - (required) date format or number format (please refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)) + - `format` (string or object) - (required) date format or number format (please refer to [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields)) - `column` - (required) an object with column data (the same as for the body cell) ### Example -The snippet below shows how to define templates via the `pivot.template` helper. The helper is applied 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. +The snippet below shows how to define templates via the `pivot.template` helper. The helper is applied right before the table renders, which is done by intercepting the [render-table](api/events/render-table-event.md) event using the [api.intercept()](api/internal/intercept-method.md) method. The snippet demonstrates how you can add icons to: @@ -84,6 +84,6 @@ The snippet demonstrates how you can add icons to: **Related articles:** -- [`render-table`](/api/events/render-table-event) -- [Applying templates to cells](/guides/configuration/#applying-templates-to-cells) -- [Applying templates to headers](/guides/configuration/#applying-templates-to-headers) \ No newline at end of file +- [`render-table`](api/events/render-table-event.md) +- [Applying templates to cells](guides/configuration.md#applying-templates-to-cells) +- [Applying templates to headers](guides/configuration.md#applying-templates-to-headers) \ No newline at end of file diff --git a/docs/api/internal/detach-method.md b/docs/api/internal/detach-method.md index 8284136..7861b36 100644 --- a/docs/api/internal/detach-method.md +++ b/docs/api/internal/detach-method.md @@ -22,7 +22,7 @@ api.detach(tag: number | string ): void; ### Example -In the example below we add an object with the **tag** property to the [`api.on()`](/api/internal/on-method) handler, and then we use the `api.detach()` method to stop logging the [`open-filter`](/api/events/open-filter-event) action. +In the example below we add an object with the **tag** property to the [`api.on()`](api/internal/on-method.md) handler, and then we use the `api.detach()` method to stop logging the [`open-filter`](api/events/open-filter-event.md) action. ~~~jsx {31-34} // create Pivot diff --git a/docs/api/internal/exec-method.md b/docs/api/internal/exec-method.md index 54f234f..c800f77 100644 --- a/docs/api/internal/exec-method.md +++ b/docs/api/internal/exec-method.md @@ -16,7 +16,7 @@ description: You can learn about the exec method in the documentation of the DHT api.exec( event: string, config: object -): void; +): Promise; ~~~ ## Parameters @@ -27,12 +27,12 @@ api.exec( ## Actions :::info -The full list of Pivot events can be found [**here**](/api/overview/events-overview) +The full list of Pivot events can be found [**here**](api/overview/events-overview.md) ::: ## Example -In the example below, the [`delete-field`](/api/events/delete-field-event) event is triggered via the `api.exec()`method. The last field is removed from the **values** area. The [`api.getState()`](/api/internal/getstate-method) method here is used to get the current state of the Pivot [`config`](/api/config/config-property). The event will be triggered with the button click. +In the example below, the [`delete-field`](api/events/delete-field-event.md) event is triggered via the `api.exec()`method. The last field is removed from the **values** area. The [`api.getState()`](api/internal/getstate-method.md) method here is used to get the current state of the Pivot [`config`](api/config/config-property.md). The event will be triggered with the button click. ~~~jsx {32-35} // create Pivot diff --git a/docs/api/internal/getreactivestate-method.md b/docs/api/internal/getreactivestate-method.md index ee1a40b..da20b22 100644 --- a/docs/api/internal/getreactivestate-method.md +++ b/docs/api/internal/getreactivestate-method.md @@ -30,17 +30,18 @@ The method returns an object with the following parameters: filters: {}, // filtering rules headerShape: {}, // table header settings predicates: {}, // available predicates by fields - limits: {} // the maximum limit for the number of rows and columns in the dataset + limits: {}, // the maximum limit for the number of rows and columns in the dataset methods: {}, // methods for data aggregation tableShape: {}, // table settings (sizes, total row, templates) tableConfig: {}, // table configuration settings (columns, data, sizes, tree mode, footer) - configPanel: boolean, // the state of the configuration panel visibility + configPanel: boolean, // the state of the configuration panel visibility + readonly: boolean, // whether the read-only mode is enabled } ~~~ ### Example -~~~jsx {22-28} +~~~jsx {21-26} // create Pivot const table = new pivot.Pivot("#root", { fields, @@ -61,12 +62,10 @@ const table = new pivot.Pivot("#root", { } }); -// output the current config state to the console -let config; -let state = table.api.getReactiveState(); +// subscribe to the reactive config store and log it on every change +const state = table.api.getReactiveState(); -if (config) { - console.log("There were some changes in Pivot config. Its current state:"); - console.log(config); -} +state.config.subscribe((config) => { + console.log("Pivot config changed. Its current state:", config); +}); ~~~ diff --git a/docs/api/internal/getstate-method.md b/docs/api/internal/getstate-method.md index 295c8a8..054d278 100644 --- a/docs/api/internal/getstate-method.md +++ b/docs/api/internal/getstate-method.md @@ -30,11 +30,12 @@ The method returns an object with the following parameters: filters: {}, // filtering rules headerShape: {}, // table header settings predicates: {}, // available predicates by fields - limits: {} // the maximum limit for the number of rows and columns in the dataset + limits: {}, // the maximum limit for the number of rows and columns in the dataset methods: {}, // methods for data aggregation tableShape: {}, // table settings (sizes, total row, templates) tableConfig: {}, // table configuration settings (columns, data, sizes, tree mode, footer) - configPanel: boolean, // the state of the configuration panel visibility + configPanel: boolean, // the state of the configuration panel visibility + readonly: boolean, // whether the read-only mode is enabled } ~~~ diff --git a/docs/api/internal/intercept-method.md b/docs/api/internal/intercept-method.md index 69b0a93..c988fa8 100644 --- a/docs/api/internal/intercept-method.md +++ b/docs/api/internal/intercept-method.md @@ -30,8 +30,8 @@ api.intercept( ### Events :::info -The full list of the Pivot internal events can be found [**here**](api/overview/main-overview.md/#pivot-events). -Use the [`api.on()`](/api/internal/on-method) method if you want to listen to the actions without modifying them. To make changes to the actions, apply the `api.intercept()` method. +The full list of the Pivot internal events can be found [**here**](api/overview/main-overview.md#pivot-events). +Use the [`api.on()`](api/internal/on-method.md) method if you want to listen to the actions without modifying them. To make changes to the actions, apply the `api.intercept()` method. ::: ### Example @@ -65,4 +65,4 @@ table.api.intercept("render-table", (ev) => { }, {tag: "render-table-tag"}); ~~~ -**Related articles**: [`render-table`](/api/events/render-table-event) +**Related articles**: [`render-table`](api/events/render-table-event.md) diff --git a/docs/api/internal/on-method.md b/docs/api/internal/on-method.md index 8e28fc4..76b8e02 100644 --- a/docs/api/internal/on-method.md +++ b/docs/api/internal/on-method.md @@ -31,15 +31,15 @@ api.on( ### Events :::info -The full list of the Pivot internal events can be found [**here**](/api/overview/main-overview/#pivot-events). -Use the `api.on()` method if you want to listen to the actions without modifying them. To make changes to the actions, apply the [`api.intercept()`](/api/internal/intercept-method) method. +The full list of the Pivot internal events can be found [**here**](api/overview/main-overview.md#pivot-events). +Use the `api.on()` method if you want to listen to the actions without modifying them. To make changes to the actions, apply the [`api.intercept()`](api/internal/intercept-method.md) method. ::: ### Example The example below shows how to output the label of a field for which the filter was activated: -~~~jsx {21-28} +~~~jsx {21-29} // create Pivot const table = new pivot.Pivot("#root", { fields, @@ -61,11 +61,12 @@ const table = new pivot.Pivot("#root", { }); table.api.on("open-filter", (ev) => { - const fieldObj = ev.field; - const field = fieldObj.base || fieldObj.field; - - if (field) { - console.log("The field for which filter was activated:", ev.field.label); + if (ev.id) { + const { config } = table.api.getState(); + const fieldObj = config[ev.area].find((f) => f.id === ev.id); + if (fieldObj) { + console.log("The field for which filter was activated:", fieldObj.label); + } } }, {tag: "open-filter-tag"}); ~~~ diff --git a/docs/api/internal/setnext-method.md b/docs/api/internal/setnext-method.md index cfe59e2..4b852ab 100644 --- a/docs/api/internal/setnext-method.md +++ b/docs/api/internal/setnext-method.md @@ -42,4 +42,4 @@ Promise.all([ }); ~~~ -**Related articles**: [`setConfig`](/api/methods/setconfig-method) +**Related articles**: [`setConfig`](api/methods/setconfig-method.md) diff --git a/docs/api/methods/gettable-method.md b/docs/api/methods/gettable-method.md index 96e861e..803d2a8 100644 --- a/docs/api/methods/gettable-method.md +++ b/docs/api/methods/gettable-method.md @@ -10,7 +10,7 @@ description: You can learn about the getTable method in the documentation of the @short: Gets access to the underlying Table widget instance in the Pivot table -This method is used when there's a need to access the underlying Table widget instance in Pivot. It provides direct access to the Table functionality allowing for operations such as data serialization and exporting in various formats. The Table API has its own `api.exec()` method that can call the [`open-row`](/api/table/open-row), [`close-row`](/api/table/close-row), [`export`](/api/table/export), and [`filter-rows`](/api/table/filter-rows) events. +This method is used when there's a need to access the underlying Table widget instance in Pivot. It provides direct access to the Table functionality allowing for operations such as data serialization and exporting in various formats. The Table API has its own `api.exec()` method that can call the [`open-row`](api/table/open-row.md), [`close-row`](api/table/close-row.md), [`export`](api/table/export.md), and [`filter-rows`](api/table/filter-rows.md) events. ### Usage @@ -24,7 +24,7 @@ getTable(wait:boolean): Table | Promise; ### Example -In the example below we get access to the Table widget API and trigger the Table `export`event with the button click using the [`api.exec()`](/api/internal/exec-method) method. +In the example below we get access to the Table widget API and trigger the Table `export`event with the button click using the [`api.exec()`](api/internal/exec-method.md) method. ~~~jsx // create Pivot @@ -51,7 +51,7 @@ const table = new pivot.Pivot("#root", { let table_instance = table.getTable(); function toCSV() { - table_instance.exeс("export", { + table_instance.exec("export", { options: { format: "csv", cols: ";" @@ -69,7 +69,7 @@ document.body.appendChild(exportButton); **Related articles:**: -- [`close-row`](/api/table/close-row) -- [`export`](/api/table/export) -- [`filter-rows`](/api/table/filter-rows) -- [`open-row`](/api/table/open-row) \ No newline at end of file +- [`close-row`](api/table/close-row.md) +- [`export`](api/table/export.md) +- [`filter-rows`](api/table/filter-rows.md) +- [`open-row`](api/table/open-row.md) \ No newline at end of file diff --git a/docs/api/methods/setconfig-method.md b/docs/api/methods/setconfig-method.md index 1421864..86e8239 100644 --- a/docs/api/methods/setconfig-method.md +++ b/docs/api/methods/setconfig-method.md @@ -20,7 +20,7 @@ setConfig(config: { [key:any]: any }): void; ### Parameters -- `config` - (required) an object of the Pivot configuration. See the full list of properties [here](/api/overview/properties-overview) +- `config` - (required) an object of the Pivot configuration. See the full list of properties [here](api/overview/properties-overview.md) :::important The method changes only the parameters you passed. It destroys the current component and initializes a new one. diff --git a/docs/api/methods/setlocale-method.md b/docs/api/methods/setlocale-method.md index eeee017..6891bb8 100644 --- a/docs/api/methods/setlocale-method.md +++ b/docs/api/methods/setlocale-method.md @@ -52,5 +52,5 @@ table.setLocale(); // or setLocale(null); ~~~ **Related articles**: -- [Localization](/guides/localization) -- [`locale`](/api/config/locale-property) +- [Localization](guides/localization.md) +- [`locale`](api/config/locale-property.md) diff --git a/docs/api/methods/showconfigpanel-method.md b/docs/api/methods/showconfigpanel-method.md index ea5ddcf..fd01142 100644 --- a/docs/api/methods/showconfigpanel-method.md +++ b/docs/api/methods/showconfigpanel-method.md @@ -51,5 +51,5 @@ table.showConfigPanel ({ ~~~ **Related articles**: -- [`show-config-panel` event](/api/events/show-config-panel-event) -- [`configPanel` property](/api/config/configpanel-property) +- [`show-config-panel` event](api/events/show-config-panel-event.md) +- [`configPanel` property](api/config/configpanel-property.md) diff --git a/docs/api/overview/events-overview.md b/docs/api/overview/events-overview.md index 877c376..3a5be91 100644 --- a/docs/api/overview/events-overview.md +++ b/docs/api/overview/events-overview.md @@ -8,12 +8,12 @@ description: You can have Events overview of JavaScript Pivot in the documentati | Name | Description | | ------------------------------------------------- | ----------------------------------------------- | -| [](../events/add-field-event.md) | @getshort(../events/add-field-event.md) | -| [](../events/apply-filter-event.md) | @getshort(../events/apply-filter-event.md) | -| [](../events/delete-field-event.md) | @getshort(../events/delete-field-event.md) | -| [](../events/move-field-event.md) | @getshort(../events/move-field-event.md) | -| [](../events/open-filter-event.md) | @getshort(../events/open-filter-event.md) | -| [](../events/render-table-event.md) | @getshort(../events/render-table-event.md) | -| [](../events/show-config-panel-event.md) | @getshort(../events/show-config-panel-event.md) | -| [](../events/update-config-event.md) | @getshort(../events/update-config-event.md) | -| [](../events/update-value-event.md) | @getshort(../events/update-value-event.md) | +| [](api/events/add-field-event.md) | @getshort(../events/add-field-event.md) | +| [](api/events/apply-filter-event.md) | @getshort(../events/apply-filter-event.md) | +| [](api/events/delete-field-event.md) | @getshort(../events/delete-field-event.md) | +| [](api/events/move-field-event.md) | @getshort(../events/move-field-event.md) | +| [](api/events/open-filter-event.md) | @getshort(../events/open-filter-event.md) | +| [](api/events/render-table-event.md) | @getshort(../events/render-table-event.md) | +| [](api/events/show-config-panel-event.md) | @getshort(../events/show-config-panel-event.md) | +| [](api/events/update-config-event.md) | @getshort(../events/update-config-event.md) | +| [](api/events/update-field-event.md) | @getshort(../events/update-field-event.md) | diff --git a/docs/api/overview/internal-eventbus-overview.md b/docs/api/overview/internal-eventbus-overview.md index 69011d6..c5f560f 100644 --- a/docs/api/overview/internal-eventbus-overview.md +++ b/docs/api/overview/internal-eventbus-overview.md @@ -8,8 +8,8 @@ description: You can have an Internal Event Bus methods overview of JavaScript P | Name | Description | | ---------------------------------------------- | ------------------------------------------------- | -| [](../internal/detach-method.md) | @getshort(../internal/detach-method.md) | -| [](../internal/exec-method.md) | @getshort(../internal/exec-method.md) | -| [](../internal/intercept-method.md) | @getshort(../internal/intercept-method.md) | -| [](../internal/on-method.md) | @getshort(../internal/on-method.md) | -| [](../internal/setnext-method.md) | @getshort(../internal/setnext-method.md) | +| [](api/internal/detach-method.md) | @getshort(../internal/detach-method.md) | +| [](api/internal/exec-method.md) | @getshort(../internal/exec-method.md) | +| [](api/internal/intercept-method.md) | @getshort(../internal/intercept-method.md) | +| [](api/internal/on-method.md) | @getshort(../internal/on-method.md) | +| [](api/internal/setnext-method.md) | @getshort(../internal/setnext-method.md) | diff --git a/docs/api/overview/internal-state-overview.md b/docs/api/overview/internal-state-overview.md index 1521954..bf770d5 100644 --- a/docs/api/overview/internal-state-overview.md +++ b/docs/api/overview/internal-state-overview.md @@ -8,6 +8,6 @@ description: You can have Internal State methods overview of JavaScript Pivot in | Name | Description | | ---------------------------------------------- | -------------------------------------------------- | -| [](../internal/getreactivestate-method.md) | @getshort(../internal/getreactivestate-method.md) | -| [](../internal/getstate-method.md) | @getshort(../internal/getstate-method.md) | -| [](../internal/getstores-method.md) | @getshort(../internal/getstores-method.md) | +| [](api/internal/getreactivestate-method.md) | @getshort(../internal/getreactivestate-method.md) | +| [](api/internal/getstate-method.md) | @getshort(../internal/getstate-method.md) | +| [](api/internal/getstores-method.md) | @getshort(../internal/getstores-method.md) | diff --git a/docs/api/overview/main-overview.md b/docs/api/overview/main-overview.md index 7a9373c..ef74c25 100644 --- a/docs/api/overview/main-overview.md +++ b/docs/api/overview/main-overview.md @@ -23,10 +23,10 @@ new pivot.Pivot("#root", { | Name | Description | | ------------------------------------------- | ------------------------------------------ | -| [](../methods/gettable-method.md) | @getshort(../methods/gettable-method.md) | -| [](../methods/setconfig-method.md) | @getshort(../methods/setconfig-method.md) | -| [](../methods/setlocale-method.md) | @getshort(../methods/setlocale-method.md) | -| [](../methods/showconfigpanel-method.md) | @getshort(../methods/showconfigpanel-method.md) | +| [](api/methods/gettable-method.md) | @getshort(../methods/gettable-method.md) | +| [](api/methods/setconfig-method.md) | @getshort(../methods/setconfig-method.md) | +| [](api/methods/setlocale-method.md) | @getshort(../methods/setlocale-method.md) | +| [](api/methods/showconfigpanel-method.md) | @getshort(../methods/showconfigpanel-method.md) | ## Pivot internal API @@ -34,47 +34,47 @@ new pivot.Pivot("#root", { | Name | Description | | :------------------------------------ | :------------------------------------------- | -| [](../internal/detach-method.md) | @getshort(../internal/detach-method.md) | -| [](../internal/exec-method.md) | @getshort(../internal/exec-method.md) | -| [](../internal/intercept-method.md) | @getshort(../internal/intercept-method.md) | -| [](../internal/on-method.md) | @getshort(../internal/on-method.md) | -| [](../internal/setnext-method.md) | @getshort(../internal/setnext-method.md) | +| [](api/internal/detach-method.md) | @getshort(../internal/detach-method.md) | +| [](api/internal/exec-method.md) | @getshort(../internal/exec-method.md) | +| [](api/internal/intercept-method.md) | @getshort(../internal/intercept-method.md) | +| [](api/internal/on-method.md) | @getshort(../internal/on-method.md) | +| [](api/internal/setnext-method.md) | @getshort(../internal/setnext-method.md) | ### State methods | Name | Description | | :---------------------------------------------- | :------------------------------------------------- | -| [](../internal/getreactivestate-method.md) | @getshort(../internal/getreactivestate-method.md) | -| [](../internal/getstate-method.md) | @getshort(../internal/getstate-method.md) | -| [](../internal/getstores-method.md) | @getshort(../internal/getstores-method.md) | +| [](api/internal/getreactivestate-method.md) | @getshort(../internal/getreactivestate-method.md) | +| [](api/internal/getstate-method.md) | @getshort(../internal/getstate-method.md) | +| [](api/internal/getstores-method.md) | @getshort(../internal/getstores-method.md) | ## Pivot events | Name | Description | | :------------------------------------------------ | :---------------------------------------------- | -| [](../events/add-field-event.md) | @getshort(../events/add-field-event.md) | -| [](../events/apply-filter-event.md) | @getshort(../events/apply-filter-event.md) | -| [](../events/delete-field-event.md) | @getshort(../events/delete-field-event.md) | -| [](../events/move-field-event.md) | @getshort(../events/move-field-event.md) | -| [](../events/open-filter-event.md) | @getshort(../events/open-filter-event.md) | -| [](../events/render-table-event.md) | @getshort(../events/render-table-event.md) | -| [](../events/show-config-panel-event.md) | @getshort(../events/show-config-panel-event.md) | -| [](../events/update-config-event.md) | @getshort(../events/update-config-event.md) | -| [](../events/update-value-event.md) | @getshort(../events/update-value-event.md) | +| [](api/events/add-field-event.md) | @getshort(../events/add-field-event.md) | +| [](api/events/apply-filter-event.md) | @getshort(../events/apply-filter-event.md) | +| [](api/events/delete-field-event.md) | @getshort(../events/delete-field-event.md) | +| [](api/events/move-field-event.md) | @getshort(../events/move-field-event.md) | +| [](api/events/open-filter-event.md) | @getshort(../events/open-filter-event.md) | +| [](api/events/render-table-event.md) | @getshort(../events/render-table-event.md) | +| [](api/events/show-config-panel-event.md) | @getshort(../events/show-config-panel-event.md) | +| [](api/events/update-config-event.md) | @getshort(../events/update-config-event.md) | +| [](api/events/update-field-event.md) | @getshort(../events/update-field-event.md) | ## Pivot properties | Name | Description | | :------------------------------------------------- | :----------------------------------------------- | -| [](../config/columnshape-property.md) | @getshort(../config/columnshape-property.md) | -| [](../config/config-property.md) | @getshort(../config/config-property.md) | -| [](../config/configpanel-property.md) | @getshort(../config/configpanel-property.md) | -| [](../config/data-property.md) | @getshort(../config/data-property.md) | -| [](../config/fields-property.md) | @getshort(../config/fields-property.md) | -| [](../config/headershape-property.md) | @getshort(../config/headershape-property.md) | -| [](../config/limits-property.md) | @getshort(../config/limits-property.md) | -| [](../config/locale-property.md) | @getshort(../config/locale-property.md) | -| [](../config/methods-property.md) | @getshort(../config/methods-property.md) | -| [](../config/predicates-property.md) | @getshort(../config/predicates-property.md) | -| [](../config/readonly-property.md) | @getshort(../config/readonly-property.md) | -| [](../config/tableshape-property.md) | @getshort(../config/tableshape-property.md) | +| [](api/config/columnshape-property.md) | @getshort(../config/columnshape-property.md) | +| [](api/config/config-property.md) | @getshort(../config/config-property.md) | +| [](api/config/configpanel-property.md) | @getshort(../config/configpanel-property.md) | +| [](api/config/data-property.md) | @getshort(../config/data-property.md) | +| [](api/config/fields-property.md) | @getshort(../config/fields-property.md) | +| [](api/config/headershape-property.md) | @getshort(../config/headershape-property.md) | +| [](api/config/limits-property.md) | @getshort(../config/limits-property.md) | +| [](api/config/locale-property.md) | @getshort(../config/locale-property.md) | +| [](api/config/methods-property.md) | @getshort(../config/methods-property.md) | +| [](api/config/predicates-property.md) | @getshort(../config/predicates-property.md) | +| [](api/config/readonly-property.md) | @getshort(../config/readonly-property.md) | +| [](api/config/tableshape-property.md) | @getshort(../config/tableshape-property.md) | diff --git a/docs/api/overview/methods-overview.md b/docs/api/overview/methods-overview.md index f4081e4..0ee3131 100644 --- a/docs/api/overview/methods-overview.md +++ b/docs/api/overview/methods-overview.md @@ -8,7 +8,7 @@ description: You can have Methods overview of JavaScript Pivot in the documentat | Name | Description | | ------------------------------------------- | ----------------------------------------------- | -| [](../methods/gettable-method.md) | @getshort(../methods/gettable-method.md) | -| [](../methods/setconfig-method.md) | @getshort(../methods/setconfig-method.md) | -| [](../methods/setlocale-method.md) | @getshort(../methods/setlocale-method.md) | -| [](../methods/showconfigpanel-method.md) | @getshort(../methods/showconfigpanel-method.md) | +| [](api/methods/gettable-method.md) | @getshort(../methods/gettable-method.md) | +| [](api/methods/setconfig-method.md) | @getshort(../methods/setconfig-method.md) | +| [](api/methods/setlocale-method.md) | @getshort(../methods/setlocale-method.md) | +| [](api/methods/showconfigpanel-method.md) | @getshort(../methods/showconfigpanel-method.md) | diff --git a/docs/api/overview/properties-overview.md b/docs/api/overview/properties-overview.md index 6560d51..e9612e4 100644 --- a/docs/api/overview/properties-overview.md +++ b/docs/api/overview/properties-overview.md @@ -6,19 +6,19 @@ description: You can have Properties overview of JavaScript Pivot in the documen # Properties overview -To configure **Pivot**, refer to the [Configuration](../../../guides/configuration) section. +To configure **Pivot**, refer to the [Configuration](guides/configuration.md) section. | Name | Description | | -------------------------------------------------- | ------------------------------------------------ | -| [](../config/columnshape-property.md) | @getshort(../config/columnshape-property.md) | -| [](../config/config-property.md) | @getshort(../config/config-property.md) | -| [](../config/configpanel-property.md) | @getshort(../config/configpanel-property.md) | -| [](../config/data-property.md) | @getshort(../config/data-property.md) | -| [](../config/fields-property.md) | @getshort(../config/fields-property.md) | -| [](../config/headershape-property.md) | @getshort(../config/headershape-property.md) | -| [](../config/limits-property.md) | @getshort(../config/limits-property.md) | -| [](../config/locale-property.md) | @getshort(../config/locale-property.md) | -| [](../config/methods-property.md) | @getshort(../config/methods-property.md) | -| [](../config/predicates-property.md) | @getshort(../config/predicates-property.md) | -| [](../config/readonly-property.md) | @getshort(../config/readonly-property.md) | -| [](../config/tableshape-property.md) | @getshort(../config/tableshape-property.md) | +| [](api/config/columnshape-property.md) | @getshort(../config/columnshape-property.md) | +| [](api/config/config-property.md) | @getshort(../config/config-property.md) | +| [](api/config/configpanel-property.md) | @getshort(../config/configpanel-property.md) | +| [](api/config/data-property.md) | @getshort(../config/data-property.md) | +| [](api/config/fields-property.md) | @getshort(../config/fields-property.md) | +| [](api/config/headershape-property.md) | @getshort(../config/headershape-property.md) | +| [](api/config/limits-property.md) | @getshort(../config/limits-property.md) | +| [](api/config/locale-property.md) | @getshort(../config/locale-property.md) | +| [](api/config/methods-property.md) | @getshort(../config/methods-property.md) | +| [](api/config/predicates-property.md) | @getshort(../config/predicates-property.md) | +| [](api/config/readonly-property.md) | @getshort(../config/readonly-property.md) | +| [](api/config/tableshape-property.md) | @getshort(../config/tableshape-property.md) | diff --git a/docs/api/overview/table-events-overview.md b/docs/api/overview/table-events-overview.md index 89495be..89d48c1 100644 --- a/docs/api/overview/table-events-overview.md +++ b/docs/api/overview/table-events-overview.md @@ -6,11 +6,11 @@ description: You can have Table events overview of JavaScript Pivot in the docum # Table events overview -The [`getTable`](/api/methods/gettable-method) method of the Pivot API allows getting access to the underlying Table widget instance inside Pivot and execute the next Table events: +The [`getTable`](api/methods/gettable-method.md) method of the Pivot API allows getting access to the underlying Table widget instance inside Pivot and execute the next Table events: | Name | Description | | ------------------------------------------------- | ----------------------------------------------- | -| [](../table/close-row.md) | @getshort(../table/close-row.md) | -| [](../table/export.md) | @getshort(../table/export.md) | -| [](../table/filter-rows.md) | @getshort(../table/filter-rows.md) | -| [](../table/open-row.md) | @getshort(../table/open-row.md) | +| [](api/table/close-row.md) | @getshort(../table/close-row.md) | +| [](api/table/export.md) | @getshort(../table/export.md) | +| [](api/table/filter-rows.md) | @getshort(../table/filter-rows.md) | +| [](api/table/open-row.md) | @getshort(../table/open-row.md) | diff --git a/docs/api/table/close-row.md b/docs/api/table/close-row.md index a6e41f8..574073b 100644 --- a/docs/api/table/close-row.md +++ b/docs/api/table/close-row.md @@ -10,7 +10,7 @@ description: You can learn about the close-row event in the documentation of the @short: Fires when closing (collapsing) a row -To trigger the Table event, it's necessary to get access to the underlying Table widget instance inside Pivot via the [`getTable`](/api/methods/gettable-method) method. The tree mode should be enabled via the [`tableShape`](/api/config/tableshape-property) property. +To trigger the Table event, it's necessary to get access to the underlying Table widget instance inside Pivot via the [`getTable`](api/methods/gettable-method.md) method. The tree mode should be enabled via the [`tableShape`](api/config/tableshape-property.md) property. ### Usage @@ -39,6 +39,6 @@ The snippet below demonstrates how to open/close all rows with a button click: **Related articles**: -- [`getTable`](/api/methods/gettable-method) -- [Expanding/collapsing all rows](/guides/configuration/#expandingcollapsing-all-rows) +- [`getTable`](api/methods/gettable-method.md) +- [Expanding/collapsing all rows](guides/configuration.md#expandingcollapsing-all-rows) diff --git a/docs/api/table/export.md b/docs/api/table/export.md index 014bf2a..a99f976 100644 --- a/docs/api/table/export.md +++ b/docs/api/table/export.md @@ -10,7 +10,7 @@ description: You can learn about the export event in the documentation of the DH @short: Fires when exporting data -To trigger the Table event, it's necessary to get access to the Table instance inside Pivot via the [`getTable`](/api/methods/gettable-method) method. +To trigger the Table event, it's necessary to get access to the Table instance inside Pivot via the [`getTable`](api/methods/gettable-method.md) method. ### Usage @@ -89,7 +89,7 @@ The `export` action of the Table widget has the next parameters that you can con - `cellStyle` - a function that allows customizing the style and format of individual cells during export. It takes the value, row, and column objects as parameters and should return an object with style properties (e.g., alignment or format) - `headerCellStyle` - similar to cellStyle, but specifically for the header and footer cells. This function takes the text, header cell object, column object, and type ("header" or "footer") and returns style properties :::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 are exported as raw values with default format or the format defined via the [`fields`](api/config/fields-property.md) property. But if a template is defined for a field (see the [`tableShape`](api/config/tableshape-property.md) 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. ::: **Options specific for "csv" format:** @@ -104,7 +104,7 @@ In this snippet you can see how to export data: **Related articles**: -- [`getTable`](/api/methods/gettable-method) -- [Exporting data](/guides/exporting-data) -- [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields) +- [`getTable`](api/methods/gettable-method.md) +- [Exporting data](guides/exporting-data.md) +- [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields) diff --git a/docs/api/table/filter-rows.md b/docs/api/table/filter-rows.md index 1bf5513..af9fb0e 100644 --- a/docs/api/table/filter-rows.md +++ b/docs/api/table/filter-rows.md @@ -10,7 +10,7 @@ description: You can learn about the filter-rows event in the documentation of t @short: Fires when filtering data -To trigger the Table event, it's necessary to get access to the Table instance inside Pivot via the [`getTable`](/api/methods/gettable-method) method. +To trigger the Table event, it's necessary to get access to the Table instance inside Pivot via the [`getTable`](api/methods/gettable-method.md) method. ### Usage @@ -32,6 +32,4 @@ The snippet below demonstrates how to filter aggregated (visible) data in the ta - -**Related article**: [`getTable`](/api/methods/gettable-method) - +**Related article**: [`getTable`](api/methods/gettable-method.md) diff --git a/docs/api/table/open-row.md b/docs/api/table/open-row.md index 7e93ebf..5793df0 100644 --- a/docs/api/table/open-row.md +++ b/docs/api/table/open-row.md @@ -10,7 +10,7 @@ description: You can learn about the close-row event in the documentation of the @short: Fires when opening (expanding) a row -To trigger the Table event, it's necessary to get access to the Table instance inside Pivot via the [`getTable`](/api/methods/gettable-method) method. The tree mode should be enabled via the [`tableShape`](/api/config/tableshape-property) property. +To trigger the Table event, it's necessary to get access to the Table instance inside Pivot via the [`getTable`](api/methods/gettable-method.md) method. The tree mode should be enabled via the [`tableShape`](api/config/tableshape-property.md) property. ### Usage @@ -39,5 +39,5 @@ The snippet below demonstrates how to open/close all rows with a button click: **Related articles**: -- [`getTable`](/api/methods/gettable-method) -- [Expanding/collapsing all rows](/guides/configuration/#expandingcollapsing-all-rows) \ No newline at end of file +- [`getTable`](api/methods/gettable-method.md) +- [Expanding/collapsing all rows](guides/configuration.md#expandingcollapsing-all-rows) \ No newline at end of file diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index 70a66c2..be4eeee 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -6,34 +6,34 @@ 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 the Pivot table and the Configuration panel through the following API: -- 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.md) — define the structure of the Pivot table and how data is aggregated +- [`render-table`](api/events/render-table-event.md) — change the table configuration on the fly +- [`tableShape`](api/config/tableshape-property.md) — configure the look of the Pivot table +- [`columnShape`](api/config/columnshape-property.md) — configure the look and behavior of columns +- [`headerShape`](api/config/headershape-property.md) — configure the look and behavior of headers +- [`configPanel`](api/config/configpanel-property.md) — control the visibility of the Configuration panel +- [`setLocale`](api/methods/setlocale-method.md) — apply a locale (see [Localization](guides/localization.md)) +- [`data`](api/config/data-property.md), [`fields`](api/config/fields-property.md) — load data and field metadata +- [`predicates`](api/config/predicates-property.md) — pre-process data before aggregation +- [`methods`](api/config/methods-property.md) — define custom aggregation methods +- [`limits`](api/config/limits-property.md) — cap the number of rows and columns in the final dataset -All instructions about working with data see here: [Working with data](/guides/working-with-data) +For instructions on working with data, see [Working with data](guides/working-with-data.md). -You can configure and/or customize the following elements of the Pivot table: +You can configure the following Pivot table elements: - columns and rows - headers and footers - cells -- the table sizes +- table sizes -## Resizing the table +## Resize the table {#resizing-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.md) property to change the size of rows, columns, header, and footer. -The next sizes are applied by default: +The following code snippet shows the default sizes: ~~~jsx const sizes = { @@ -44,7 +44,7 @@ const sizes = { }; ~~~ -Example: +The following code snippet overrides the default sizes: ~~~jsx {4-11} const table = new pivot.Pivot("#root", { @@ -76,22 +76,21 @@ const table = new pivot.Pivot("#root", { ~~~ :::info -To set the width of specific column(s), apply the `width` parameter of the [columnShape property](/api/config/columnshape-property). +To set the width of specific columns, use the `width` parameter of the [`columnShape`](api/config/columnshape-property.md) property. ::: -## Autosizing columns to content +## Autosize columns to content -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 `autoWidth` parameter of the [`columnShape`](api/config/columnshape-property.md) property to calculate column widths automatically. All `autoWidth` sub-parameters are optional — for full descriptions see the [`columnShape`](api/config/columnshape-property.md) reference. -All parameters of `autoWidth` are optional and for detailed description of each parameter refer to the [columnShape](/api/config/columnshape-property) property. +The `autoWidth` object accepts the following parameters: -- 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 +- `columns` — object that selects which fields receive auto-calculated width +- `auto` — adjusts the width to the header, the cell content, or both +- `maxRows` — number of data rows analyzed to detect column size (default: 20) +- `firstOnly` — if `true` (default), analyzes each field only once. When multiple columns are based on the same field (e.g., `oil` with `count` and `oil` with `sum`), only the first column is analyzed and the others inherit its width -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. - -Example: +The following code snippet enables `autoWidth` for four fields and disables `firstOnly` so every column gets its own measurement: ~~~jsx {18-30} const table = new pivot.Pivot("#root", { @@ -127,13 +126,13 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Applying templates to cells +## Apply templates to cells {#applying-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.md) property to render cell values through a function. Each key is a field ID and each value is a function that returns a string. All columns based on the specified field receive 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 that shows the combined name of a state (full name plus abbreviation): ~~~jsx {10-15} const states = { @@ -141,14 +140,14 @@ const states = { "Colorado": "CO", "Connecticut": "CT", "Florida": "FL", -// other values, + // other values }; const table = new pivot.Pivot("#root", { tableShape: { templates: { - // set a template to customize values of "state" cells - state: v => v+ ` (${states[v]})`, + // customize values of "state" cells + state: v => v + ` (${states[v]})`, } }, fields, @@ -172,11 +171,11 @@ const table = new pivot.Pivot("#root", { }); ~~~ -### Adding a template via the template helper +### Add a template via the template helper {#adding-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. +To insert HTML content into body cells, use the [`pivot.template`](api/helpers/template.md) helper and assign the result to the `cell` property of the column object. Apply the template right before the table renders by intercepting the [`render-table`](api/events/render-table-event.md) event with the [`api.intercept`](api/internal/intercept-method.md) 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 (star or flag) to body cells based on the field (`id`, `user_score`): ~~~js function cellTemplate(value, method, row, column) { @@ -205,7 +204,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 +212,25 @@ widget.api.intercept("render-table", ({ config: tableConfig }) => { }); ~~~ -## Applying templates to headers +## Apply templates to headers {#applying-templates-to-headers} + +### Add templates via headerShape -### Adding templates via headerShape +To control the text format in headers, use the `template` parameter of the [`headerShape`](api/config/headershape-property.md) property. The parameter is a function that: -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: +- takes the field label, ID, and sublabel (the method name, if any) +- returns the processed value -- takes the field id, label and sublabel (the name of a method if any is applied) -- returns the processed value +The default template is: + +~~~js +template: (label, id, subLabel) => + label + (subLabel ? ` (${subLabel})` : "") +~~~ -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. +Without a custom template, `values`-area fields display the label and method (e.g., `Oil(count)`), and other-area fields display the `label` value. A [`predicates`](api/config/predicates-property.md) 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 converts header text to lowercase, producing labels such as `profit (sum)`: ~~~jsx {3-6} new pivot.Pivot("#pivot", { @@ -253,14 +258,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. +To insert HTML content into header cells, use the [`pivot.template`](api/helpers/template.md) helper and assign the result to the `cell` property of the header cell object. Apply the template right before the table renders by intercepting the [`render-table`](api/events/render-table-event.md) event with the [`api.intercept`](api/internal/intercept-method.md) method. -The example below shows how to add icons to: +The example below adds 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) +- header labels based on the field name (for example, `id` gets a globe icon) +- column headers based on cell value (colored arrow indicators based on the `status` value) ~~~jsx function rowsHeaderTemplate(value, field) { @@ -280,10 +285,10 @@ 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 + // header cells that display values from the "status" field const headerCell = c.header.find((h) => h.field === "status"); if (headerCell) { headerCell.cell = pivot.template(({ value }) => statusTemplate(value)); @@ -294,9 +299,11 @@ widget.api.intercept("render-table", ({ config: tableConfig }) => { }); ~~~ -## Making columns collapsible +## Make columns collapsible + +To allow users to collapse and expand columns under a shared header, set the `collapsible` parameter of the [`headerShape`](api/config/headershape-property.md) property to `true`. -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**. +The following code snippet enables collapsible header columns: ~~~jsx {4-6} const table = new pivot.Pivot("#root", { @@ -322,13 +329,15 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Freezing columns +## Freeze columns {#freezing-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. +Freeze columns on the left or the right so they stay visible while the rest of the table scrolls. Use the `split` parameter of the [`tableShape`](api/config/tableshape-property.md) property and set `left` or `right` to `true`. -### 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. +When `split.left` is `true`, the number of frozen columns equals the number of `rows` fields in the [`config`](api/config/config-property.md) property. In tree mode, only one column is frozen regardless of the `rows` field count. + +The following code snippet freezes one column on the left (one `rows` field is defined): ~~~jsx {19} const table = new pivot.Pivot("#root", { @@ -354,11 +363,11 @@ 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. +To set a custom split count, listen to the [`render-table`](api/events/render-table-event.md) event and override `tableConfig.split`. 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 following code snippet freezes all `rows` columns plus twice the number of `values` fields on the left: -~~~jsx {19-25} +~~~jsx {19-26} const table = new pivot.Pivot("#root", { fields, data, @@ -377,8 +386,8 @@ const table = new pivot.Pivot("#root", { ] } }); -table.api.on("render-table", (tableConfig) => { - const config = api.getState().config; +table.api.on("render-table", ({ config: tableConfig }) => { + const { config } = table.api.getState(); tableConfig.split = { left: config.rows.length + config.values.length * 2 @@ -386,9 +395,11 @@ table.api.on("render-table", (tableConfig) => { }); ~~~ -### Freezing columns on the right +### Freeze columns on the right {#freezing-columns-on-the-right} + +Set `split.right` to `true` to freeze total columns on the right. -The `right` parameter of the [`tableShape`](/api/config/tableshape-property) property allows fixing total columns on the right. +The following code snippet freezes the total column on the right: ~~~jsx {4-7} const widget = new pivot.Pivot("#pivot", { @@ -415,7 +426,9 @@ 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 freeze a custom number of columns on the right, listen to the [`render-table`](api/events/render-table-event.md) event and override `tableConfig.split`. Avoid splitting columns with colspans. + +The following code snippet freezes as many columns on the right as there are `values` fields: ~~~jsx {20-25} const widget = new pivot.Pivot("#pivot", { @@ -445,9 +458,11 @@ widget.api.on("render-table", ({ config: tableConfig }) => { }) ~~~ -## Sorting in columns +## Sort in columns + +Sorting in the UI is enabled by default — users click a column header to sort. To disable it, set the `sort` parameter of the [`columnShape`](api/config/columnshape-property.md) property to `false`. -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. +The following code snippet disables UI sorting: ~~~jsx {19} const table = new pivot.Pivot("#root", { @@ -473,12 +488,13 @@ const table = new pivot.Pivot("#root", { }); ~~~ -For more information about sorting data, refer to [Sorting data](/guides/working-with-data#sorting-data). +For more on default sort, custom comparators, and runtime updates, see [Sort data](guides/working-with-data.md#sorting-data). -## Enabling the tree mode +## Enable tree mode {#enabling-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. +Tree mode presents data hierarchically with expandable rows. Set the `tree` parameter of the [`tableShape`](api/config/tableshape-property.md) property to `true` (default `false`). The first field of the `rows` array in [`config`](api/config/config-property.md) becomes the parent row. + +The following code snippet enables tree mode with `studio` as the parent and `genre` as nested rows: ~~~jsx {3} const table = new pivot.Pivot("#root", { @@ -515,11 +531,11 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Expanding/collapsing all rows +## Expand or collapse all rows {#expandingcollapsing-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. +To expand or collapse all rows programmatically, enable tree mode via the [`tableShape`](api/config/tableshape-property.md) property. Then access the Table widget instance with the [`getTable`](api/methods/gettable-method.md) method and trigger the [`open-row`](api/table/open-row.md) or [`close-row`](api/table/close-row.md) event through the Table's `api.exec` method. -The example below shows how to expand/collapse all data rows with the button click in the table tree mode. +The example below renders Open all and Close all buttons that expand or collapse every branch in tree mode: ~~~jsx const table = new pivot.Pivot("#root", { @@ -553,21 +569,21 @@ const table = new pivot.Pivot("#root", { }); const api = table.api; -const table = api.getTable(); -// setting all table branches closed on the table config update +const tableInstance = api.getTable(); +// keep all table branches closed on render api.intercept("render-table", (ev) => { ev.config.data.forEach((r) => (r.open = false)); - // returning "false" here will prevent the table from rendering + // return false here to prevent the table from rendering // return false; }); function openAll() { - table.exec("open-row", { id: 0, nested: true }); + tableInstance.exec("open-row", { id: 0, nested: true }); } function closeAll() { - table.exec("close-row", { id: 0, nested: true }); + tableInstance.exec("close-row", { id: 0, nested: true }); } const openAllButton = document.createElement("button"); @@ -582,9 +598,11 @@ document.body.appendChild(openAllButton); document.body.appendChild(closeAllButton); ~~~ -## Changing text orientation in headers +## Change header text orientation + +To rotate header text from horizontal to vertical, set the `vertical` parameter of the [`headerShape`](api/config/headershape-property.md) property to `true`. -To change text orientation from default horizontal to vertical, use the [`headerShape`](/api/config/headershape-property) property and set its `vertical` parameter to **true**. +The following code snippet renders vertical header text: ~~~jsx {4-6} const table = new pivot.Pivot("#root", { @@ -610,13 +628,15 @@ const table = new pivot.Pivot("#root", { }); ~~~ -## Controlling visibility of Configuration panel +## Control Configuration panel visibility {#controlling-visibility-of-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. Users can toggle it through the **Hide Settings** / **Show Settings** button. Control the panel programmatically through the [`configPanel`](api/config/configpanel-property.md) property, the [`show-config-panel`](api/events/show-config-panel-event.md) event, or the [`showConfigPanel`](api/methods/showconfigpanel-method.md) method. -### Hiding Configuration panel +### Hide the Configuration panel -To hide the panel, set the value of the [`configPanel`](/api/config/configpanel-property) property to **false**. +To hide the panel on initialization, set the [`configPanel`](api/config/configpanel-property.md) property to `false`. + +The following code snippet initializes Pivot with the panel hidden: ~~~jsx // the configuration panel is hidden on init @@ -641,7 +661,9 @@ 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**. +To toggle the panel at runtime, trigger the [`show-config-panel`](api/events/show-config-panel-event.md) event with the [`api.exec`](api/internal/exec-method.md) method and set the `mode` parameter to `false`. + +The following code snippet hides the panel after initialization: ~~~jsx {19-22} const table = new pivot.Pivot("#root", { @@ -662,17 +684,17 @@ const table = new pivot.Pivot("#root", { ] } }); -//hide the configuration panel +// hide the configuration panel table.api.exec("show-config-panel", { mode: false }); ~~~ -### 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*). +To block the default toggle button entirely, intercept the [`show-config-panel`](api/events/show-config-panel-event.md) event with the [`api.intercept`](api/internal/intercept-method.md) method and return `false`. -Example: +The following code snippet disables the toggle button: ~~~jsx {20-22} const table = new pivot.Pivot("#root", { @@ -699,16 +721,16 @@ table.api.intercept("show-config-panel", () => { }); ~~~ -You can also control the visibility of the Configuration panel using the [`showConfigPanel()`](/api/methods/showconfigpanel-method) method. +For an alternative API, use the [`showConfigPanel`](api/methods/showconfigpanel-method.md) method. ### Actions with fields in the panel -In the Configuration panel it's possible to perform the next operations with fields: +The Configuration panel supports the following field operations: -- [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) +- [`add-field`](api/events/add-field-event.md) — add a field to an area +- [`delete-field`](api/events/delete-field-event.md) — remove a field from an area +- [`update-field`](api/events/update-value-event.md) — update a field's method or settings +- [`move-field`](api/events/move-field-event.md) — reorder fields within an area **Related samples:** - [Pivot 2. Adding text templates for table and header cells](https://snippet.dhtmlx.com/n9ylp6b2) @@ -716,5 +738,3 @@ In the Configuration panel it's possible to perform the next operations with fie - [Pivot 2. Expand and collapse all rows](https://snippet.dhtmlx.com/i4mi6ejn) - [Pivot 2. Frozen(fixed) columns on the left and right](https://snippet.dhtmlx.com/lahf729o) - [Pivot 2. Sorting](https://snippet.dhtmlx.com/j7vtief6) - - diff --git a/docs/guides/exporting-data.md b/docs/guides/exporting-data.md index effed77..c43d7de 100644 --- a/docs/guides/exporting-data.md +++ b/docs/guides/exporting-data.md @@ -6,34 +6,40 @@ description: You can explore how to export data in the documentation of the DHTM # Exporting 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. +Pivot exports table data in XLSX or CSV format through the underlying Table widget. Access the Table instance with the [`getTable`](api/methods/gettable-method.md) method, then trigger the [`export`](api/table/export.md) event with the Table's [`api.exec`](api/internal/exec-method.md) method. -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 example below accesses the Table instance and triggers the `export` event in CSV and XLSX formats: ~~~jsx -const widget = new pivot.Pivot("#root", { /*setting*/}); -widget.api.getTable().exec("export", { - options: { - format: "csv", - cols: ";" - } +const widget = new pivot.Pivot("#root", { /* settings */ }); + +widget.getTable().exec("export", { + options: { + format: "csv", + cols: ";" + } }); -widget.api.getTable().exec("export", { - options: { - format: "xlsx", - fileName: "My Report", - sheetName: "Quarter 1", - } + +widget.getTable().exec("export", { + options: { + format: "xlsx", + fileName: "My Report", + sheetName: "Quarter 1" + } }); ~~~ +:::tip +The [`getTable`](api/methods/gettable-method.md) method accepts an optional `wait` boolean parameter. Pass `true` to receive a promise that resolves once the Table API is available. Useful when the Table API must be ready during Pivot initialization. +::: + ## Example -In this snippet you can see how to export data: +The snippet below exports data: **Related articles**: -- [Date formatting](/guides/localization#date-formatting) -- [`export`](/api/table/export) \ No newline at end of file +- [Date formatting](guides/localization.md#date-formatting) +- [`export`](api/table/export.md) diff --git a/docs/guides/initialization.md b/docs/guides/initialization.md index a7252f8..c1f33c8 100644 --- a/docs/guides/initialization.md +++ b/docs/guides/initialization.md @@ -6,47 +6,49 @@ description: You can learn about the initialization in the documentation of the # Initialization -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 create Pivot on a page and enrich your application with Pivot table features. 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](#initialize-pivot). -## Including source files +## Include source files -See also how to download packages: [Downloading packages](/how-to-start#step-1-downloading-and-installing-packages). +A Pivot app requires two source files on the page. For instructions on downloading the package, see [Downloading packages](how-to-start.md#step-1-downloading-and-installing-packages). -To create a Pivot app, you need to include 2 source files on your page: +Include the following files: - *pivot.js* - *pivot.css* -Make sure that you set correct relative paths to the source files: +Set the 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"*: +Pivot renders into an HTML container element. Add a container and assign an ID, for example *"root"*: ~~~html title="index.html"
~~~ -## Initializing Pivot +## Initialize Pivot -Initialize Pivot with the **pivot.Pivot** constructor. It takes two parameters: +The `pivot.Pivot` constructor takes two parameters: -- an HTML container (the ID of the HTML container) +- the ID of the HTML container - an object with configuration properties +The following code snippet creates a Pivot instance in the *"root"* container with initial fields, data, and structure: + ~~~jsx // create Pivot const table = new pivot.Pivot("#root", { - //configuration properties + // configuration properties fields, data, config: { @@ -62,14 +64,23 @@ const table = new pivot.Pivot("#root", { }); ~~~ +The constructor returns a Pivot instance. Call API methods on the returned instance: + +- [`getTable`](api/methods/gettable-method.md) — get access to the underlying Table widget instance +- [`setConfig`](api/methods/setconfig-method.md) — update the current Pivot configuration +- [`setLocale`](api/methods/setlocale-method.md) — apply a new locale to Pivot +- [`showConfigPanel`](api/methods/showconfigpanel-method.md) — show or hide the Configuration panel + ## Configuration properties +The Pivot constructor accepts an object with configuration properties that control data, layout, and behavior. + :::info -The full list of properties to configure **Pivot** can be found [**here**](api/overview/properties-overview.md). +For the full list of properties to configure Pivot, see [Properties overview](api/overview/properties-overview.md). ::: ## Example -In this snippet you can see how to initialize **Pivot** with the initial data: +The snippet below initializes Pivot with the initial data: diff --git a/docs/guides/integration-with-angular.md b/docs/guides/integration-with-angular.md index f043e0d..a645503 100644 --- a/docs/guides/integration-with-angular.md +++ b/docs/guides/integration-with-angular.md @@ -7,79 +7,81 @@ 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). +Familiarity with the basic concepts and patterns of **Angular** is assumed. To refresh, see the [**Angular documentation**](https://v17.angular.io/docs). ::: -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 integrates with **Angular** as a regular component. For a full working setup, see the [**Angular Pivot demo 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/). +Install [**Angular CLI**](https://v1.angular.io/cli) and [**Node.js**](https://nodejs.org/en/) before you start. ::: -Create a new **my-angular-pivot-app** project using Angular CLI. Run the following command for this purpose: +The following command scaffolds a new Angular project named *my-angular-pivot-app*: -~~~json +~~~bash 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 prompted by the Angular CLI — this guide assumes a client-rendered app. ::: -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: +Change into the new project directory: -~~~json +~~~bash 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 with the [**yarn**](https://yarnpkg.com/) package manager: -~~~jsx +~~~bash yarn -yarn start // or yarn dev +yarn start # or: yarn dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app should run on a local port (for example, `http://localhost:3000`). -## Creating Pivot +## Create Pivot -Now you should get the DHTMLX Pivot source code. First of all, stop the app and proceed with installing the Pivot package. +Add the Pivot package to the project, then wrap Pivot in an Angular component. -### Step 1. Package installation +### Step 1. Install the package -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.md#installing-trial-pivot-via-npm-or-yarn) and follow the steps in the README. The trial Pivot package is valid for 30 days. -### Step 2. Component creation +### Step 2. Create the component -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. +Create an Angular component that mounts Pivot. Add a *pivot* folder under *src/app/* and create *src/app/pivot/pivot.component.ts*. Then follow these steps: #### Import source files -Open the file and import Pivot source files. Note that: +Open *src/app/pivot/pivot.component.ts* and import the Pivot package. The import path depends on the package edition: -- 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 up the container and mount Pivot -#### Set the container and initialize Pivot +To display Pivot on the page, define a container element in the component template, then initialize Pivot in the `ngOnInit` hook using the constructor. Destroy Pivot in the `ngOnDestroy` hook. -To display Pivot on the page, you need to set the container to render the component inside and initialize Pivot using the corresponding constructor: +The following code snippet defines a minimal Pivot Angular component: ~~~jsx {1,8,12-13,18-19} title="pivot.component.ts" import { Pivot } from '@dhx/trial-pivot'; @@ -87,13 +89,13 @@ import { Component, ElementRef, OnInit, ViewChild, OnDestroy, ViewEncapsulation @Component({ encapsulation: ViewEncapsulation.None, - selector: "pivot", // a template name used in the "app.component.ts" file as - styleUrls: ["./pivot.component.css"], // include a css file + selector: "pivot", // template name used in the "app.component.ts" file as + styleUrls: ["./pivot.component.css"], // include a CSS file template: `
`, }) export class PivotComponent implements OnInit, OnDestroy { - // initialize container for Pivot + // container reference for Pivot @ViewChild('container', { static: true }) pivot_container!: ElementRef; private _table!: Pivot; @@ -104,20 +106,20 @@ export class PivotComponent implements OnInit, OnDestroy { } ngOnDestroy(): void { - this._table.destructor(); // destruct Pivot + this._table.destructor(); // destroy Pivot on unmount } } ~~~ -#### 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: +To render Pivot correctly, create *src/app/pivot/pivot.component.css* with styles for the page and the Pivot container: ~~~css title="pivot.component.css" /* import Pivot styles */ @import "@dhx/trial-pivot/dist/pivot.css"; -/* specify styles for initial page */ +/* styles for the initial page */ html, body { margin: 0; @@ -125,16 +127,16 @@ body { height: 100%; } -/* specify styles for the Pivot container */ +/* styles for the Pivot container */ .widget { width: 100%; height: 100%; } ~~~ -#### 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: +To feed data into Pivot, prepare a dataset. Create *src/app/pivot/data.ts* and export the data and field metadata: ~~~jsx title="data.ts" export function getData() { @@ -172,7 +174,7 @@ export function getData() { "state": "Colorado", "expenses": 45, "type": "Decaf" - }, // othe data items + }, // other data items ]; const fields: any = [ @@ -192,7 +194,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 *src/app/pivot/pivot.component.ts*, import `getData`, and apply the dataset in `ngOnInit()`: ~~~jsx {2,18,20-21} title="pivot.component.ts" import { Pivot } from '@dhx/trial-pivot'; @@ -212,7 +214,7 @@ export class PivotComponent implements OnInit, OnDestroy { private _table!: Pivot; ngOnInit() { - const { dataset, fields } = getData(); // initialize data properties + const { dataset, fields } = getData(); // unpack data and field metadata this._table = new Pivot(this.pivot_container.nativeElement, { fields, data: dataset, @@ -236,17 +238,18 @@ 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 component is now ready to use. On mount, Pivot renders with the supplied data. For the full list of configuration properties, see the [Pivot API docs](api/overview/properties-overview.md). -#### 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/). +User actions in Pivot fire events that you can subscribe to. For the full list of events, see [Events overview](api/overview/events-overview.md). -Open the ***pivot.component.ts*** file and complete the `ngOnInit()` method as in: +The following code snippet extends `ngOnInit` with an `open-filter` event listener that logs the field ID when a user opens a filter: ~~~jsx {18-20} title="pivot.component.ts" // ... ngOnInit() { + const { dataset, fields } = getData(); this._table = new Pivot(this.pivot_container.nativeElement, { fields, data: dataset, @@ -263,7 +266,7 @@ ngOnInit() { }); this._table.api.on("open-filter", (ev) => { - console.log("The field id for which filter is activated:", ev.id); + console.log("The field id for which the filter is activated:", ev.id); }); } @@ -272,23 +275,23 @@ 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: +To embed `PivotComponent` in the app, 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"; @Component({ selector: "app-root", - template: `` // a template created in the "pivot.component.ts" file + template: `` // template created in the "pivot.component.ts" file }) export class AppComponent { name = ""; } ~~~ -Then create the ***app.module.ts*** file in the ***src/app/*** directory and specify the *PivotComponent* as shown below: +Then create *src/app/app.module.ts* and register `PivotComponent`: ~~~jsx {4-5,8} title="app.module.ts" import { NgModule } from "@angular/core"; @@ -305,7 +308,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: +Finally, open *src/main.ts* and replace its contents with the following bootstrap code: ~~~jsx title="main.ts" import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; @@ -315,8 +318,8 @@ platformBrowserDynamic() .catch((err) => console.error(err)); ~~~ -After that, you can start the app to see Pivot loaded with data on a page. +Start the app to see Pivot render the 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). +Pivot is now integrated with Angular. Customize the configuration to suit the project requirements. For the final example, see [**angular-pivot-demo 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..e8c4f6a 100644 --- a/docs/guides/integration-with-react.md +++ b/docs/guides/integration-with-react.md @@ -7,86 +7,90 @@ 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). +Familiarity with the basic concepts and patterns of [**React**](https://react.dev) is assumed. To refresh, see the [**React documentation**](https://react.dev/learn). ::: -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 integrates with **React** as a regular component. For a full working setup, see the [**React Pivot demo 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/). +Install [**Node.js**](https://nodejs.org/en/) before you start. [**Vite**](https://vite.dev/) is optional. ::: -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 a Vite-based one) named *my-react-pivot-app*. -~~~json +The following command bootstraps a Create React App project: + +~~~bash npx create-react-app my-react-pivot-app ~~~ -### Installation of dependencies +### Install dependencies -Go to the new created app directory: +Change into the new project directory: -~~~json +~~~bash 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 with your package manager: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- with [**yarn**](https://yarnpkg.com/): -~~~jsx +~~~bash yarn -yarn start // or yarn dev +yarn start # or: yarn dev ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- with [**npm**](https://www.npmjs.com/): -~~~json +~~~bash npm install npm run dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app should run on a local port (for example, `http://localhost:3000`). -## Creating Pivot +## Create Pivot -Now you should get the DHTMLX Pivot source code. First of all, stop the app and proceed with installing the Pivot package. +Add the Pivot package to the project, then wrap Pivot in a React component. -### Step 1. Package installation +### Step 1. Install the package -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.md#installing-trial-pivot-via-npm-or-yarn) and follow the steps in the README. The trial Pivot package is valid 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 that mounts Pivot. Add a new file *src/Pivot.jsx*. #### Import source files -Open the ***Pivot.jsx*** file and import Pivot source files. Note that: +Open *src/Pivot.jsx* and import the Pivot source files. The import paths depend on the package edition: -- 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***. +If the package ships minified assets, import *pivot.min.css* instead of *pivot.css*. -- 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. + +#### Set up the container and mount Pivot -#### Setting the container and adding Pivot +To display Pivot on the page, create a container `div`, then initialize Pivot in a `useEffect` hook using the constructor. -To display Pivot on the page, you need to create the container for Pivot, and initialize this component using the corresponding constructor: +The following code snippet defines a minimal Pivot React component: ~~~jsx {2,6,9-10} title="Pivot.jsx" import { useEffect, useRef } from "react"; @@ -94,14 +98,14 @@ import { Pivot } from "@dhx/trial-pivot"; import "@dhx/trial-pivot/dist/pivot.css"; // include Pivot styles export default function PivotComponent(props) { - let container = useRef(); // initialize container for Pivot + let container = useRef(); // container ref for Pivot useEffect(() => { // initialize the Pivot component const table = new Pivot(container.current, {}); return () => { - table.destructor(); // destruct Pivot + table.destructor(); // destroy Pivot on unmount }; }, []); @@ -109,12 +113,12 @@ 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: +To render Pivot correctly, add the following styles to the project's main CSS file: ~~~css title="index.css" -/* specify styles for initial page */ +/* styles for the initial page */ html, body, #root { @@ -123,16 +127,16 @@ body, margin: 0; } -/* specify styles for the Pivot container */ +/* styles for the Pivot container */ .widget { height: 100%; width: 100%; } ~~~ -#### 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: +To feed data into Pivot, prepare a dataset. Create *src/data.js* and export the data and field metadata: ~~~jsx title="data.js" export function getData() { @@ -170,7 +174,7 @@ export function getData() { "state": "Colorado", "expenses": 45, "type": "Decaf" - }, // othe data items + }, // other data items ]; const fields = [ @@ -190,7 +194,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 *src/App.js*, import the data, and pass it to the `` component as props: ~~~jsx {2,5-6} title="App.js" import Pivot from "./Pivot"; @@ -204,14 +208,14 @@ function App() { export default App; ~~~ -Go to the ***Pivot.jsx*** file and apply the passed **props** to the Pivot configuration object: +Open *src/Pivot.jsx*, destructure the props, and apply them to the Pivot configuration object: ~~~jsx {5,10-11} title="Pivot.jsx" import { useEffect, useRef } from "react"; import { Pivot } from "@dhx/trial-pivot"; import "@dhx/trial-pivot/dist/pivot.css"; -export default function PivotComponent(props) { +export default function PivotComponent({ fields, dataset }) { let container = useRef(); useEffect(() => { @@ -240,13 +244,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 component is now ready to use. On mount, Pivot renders with the supplied data. For the full list of configuration properties, see the [Pivot API docs](api/overview/properties-overview.md). -#### 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/). +User actions in Pivot fire events that you can subscribe to. For the full list of events, see [Events overview](api/overview/events-overview.md). -Open ***Pivot.jsx*** and complete the `useEffect()` method in the following way: +The following code snippet extends `useEffect` with an `open-filter` event listener that logs the field ID when a user opens a filter: ~~~jsx {19-21} title="Pivot.jsx" // ... @@ -268,7 +272,7 @@ useEffect(() => { }); table.api.on("open-filter", (ev) => { - console.log("The field id for which filter is activated:", ev.id); + console.log("The field id for which the filter is activated:", ev.id); }); return () => { @@ -278,8 +282,8 @@ useEffect(() => { // ... ~~~ -After that, you can start the app to see Pivot loaded with data on a page. +Start the app to see Pivot render the 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). +Pivot is now integrated with React. Customize the configuration to suit the project requirements. For the final example, see [**react-pivot-demo 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..f6880f5 100644 --- a/docs/guides/integration-with-svelte.md +++ b/docs/guides/integration-with-svelte.md @@ -7,68 +7,68 @@ 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/). +Familiarity with the basic concepts and patterns of **Svelte** is assumed. To refresh, see the [**Svelte documentation**](https://svelte.dev/). ::: -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 integrates with **Svelte** as a regular component. For a full working setup, see the [**Svelte Pivot demo 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/). +Install [**Node.js**](https://nodejs.org/en/) before you start. [**Vite**](https://vite.dev/) is optional. ::: -To create a **Svelte** JS project, run the following command: +The following command runs the Vite project scaffolding tool and lets you pick a Svelte template: -~~~json +~~~bash 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: +Change into the new project directory: -~~~json +~~~bash 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 with your package manager: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- with [**yarn**](https://yarnpkg.com/): -~~~jsx +~~~bash yarn -yarn start // or yarn dev +yarn start # or: yarn dev ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- with [**npm**](https://www.npmjs.com/): -~~~json +~~~bash npm install npm run dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app should run on a local port (for example, `http://localhost:3000`). -## Creating Pivot +## Create Pivot -Now you should get the DHTMLX Pivot source code. First of all, stop the app and proceed with installing the Pivot package. +Add the Pivot package to the project, then wrap Pivot in a Svelte component. -### Step 1. Package installation +### Step 1. Install the package -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.md#installing-trial-pivot-via-npm-or-yarn) and follow the steps in the README. The trial Pivot package is valid 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 that mounts Pivot. Add a new file *src/Pivot.svelte*. #### Import source files -Open the ***Pivot.svelte*** file and import Pivot source files. Note that: +Open *src/Pivot.svelte* and import the Pivot source files. The import paths depend on the package edition: -- 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***. +If the package ships minified assets, import *pivot.min.css* instead of *pivot.css*. -- 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 and mount Pivot -To display Pivot on the page, you need to create the container for Pivot, and initialize this component using the corresponding constructor: +To display Pivot on the page, add a container `div`, then initialize Pivot in the `onMount` lifecycle hook using the constructor. Destroy Pivot in the `onDestroy` hook. + +The following code snippet defines a minimal Pivot Svelte component: ~~~html {3,6,10-11,19} title="Pivot.svelte"
~~~ -#### 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: +To render Pivot correctly, add the following styles to the project's main CSS file: ~~~css title="main.css" -/* specify styles for initial page */ +/* styles for the initial page */ html, body, -#app { /* make sure that you use the #app root container */ +#app { /* use the #app root container */ height: 100%; padding: 0; margin: 0; } -/* specify styles for the Pivot container */ +/* styles for the Pivot container */ .widget { height: 100%; width: 100%; } ~~~ -#### Loading data +#### Load data -To add data into the Pivot, we need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +To feed data into Pivot, prepare a dataset. Create *src/data.js* and export the data and field metadata: ~~~jsx title="data.js" export function getData() { @@ -177,7 +179,7 @@ export function getData() { "state": "Colorado", "expenses": 45, "type": "Decaf" - }, // othe data items + }, // other data items ]; const fields = [ @@ -197,20 +199,20 @@ export function getData() { }; ~~~ -Then open the ***App.svelte*** file, import data, and pass it into the new created `` components as **props**: +Open *src/App.svelte*, import the data, and pass it to the new `` component as props: ~~~html {3,5,8} title="App.svelte" ~~~ -Go to the ***Pivot.svelte*** file and apply the passed **props** to the Pivot configuration object: +Open *src/Pivot.svelte*, declare the incoming props with `export let`, and apply them to the Pivot configuration object: ~~~html {6-7,14-15} 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***. +If the package ships minified assets, import *pivot.min.css* instead of *pivot.css*. -- 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. + +#### Set up the container and mount Pivot -#### Setting the container and adding Pivot +To display Pivot on the page, add a container `div`, then initialize Pivot in the `mounted` hook using the constructor. Destroy Pivot in the `unmounted` hook. -To display Pivot on the page, you need to create the container for Pivot, and initialize this component using the corresponding constructor: +The following code snippet defines a minimal Pivot Vue component: ~~~html {2,7-8,18} title="Pivot.vue" @@ -118,30 +120,30 @@ export default { ~~~ -#### 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: +To render Pivot correctly, add the following styles to the project's main CSS file: ~~~css title="style.css" -/* specify styles for initial page */ +/* styles for the initial page */ html, body, -#app { /* make sure that you use the #app root container */ +#app { /* use the #app root container */ height: 100%; padding: 0; margin: 0; } -/* specify styles for the Pivot container */ +/* styles for the Pivot container */ .widget { width: 100%; height: 100%; } ~~~ -#### 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: +To feed data into Pivot, prepare a dataset. Create *src/data.js* and export the data and field metadata: ~~~jsx title="data.js" export function getData() { @@ -179,7 +181,7 @@ export function getData() { "state": "Colorado", "expenses": 45, "type": "Decaf" - }, // othe data items + }, // other data items ]; const fields = [ @@ -199,7 +201,7 @@ export function getData() { }; ~~~ -Then open the ***App.vue*** file, import data, and initialize it via the inner `data()` method. After this you can pass data into the new created `` component as **props**: +Open *src/App.vue*, import the data, and expose it through the `data()` option. Then pass the values to the new `` component as props: ~~~html {3,7-13,18} title="App.vue" @@ -136,38 +134,42 @@ Second, add the path to the source data file: ~~~ -Create Pivot and load data: +The following code snippet creates Pivot and loads data from the prepared 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 data from a server + +To load data from a server endpoint, send a request with the native `fetch` method (or any equivalent), then pass the response to [`setConfig`](api/methods/setconfig-method.md), which updates the Pivot configuration and preserves previously set options. + +The following code snippet initializes Pivot with empty data, fetches data and fields from a server, then applies them with `setConfig`: ~~~jsx -const table = new pivot.Pivot("#root", {fields:[], data: []}); +const table = new pivot.Pivot("#root", { fields: [], data: [] }); const server = "https://some-backend-url"; Promise.all([ fetch(server + "/data").then((res) => res.json()), fetch(server + "/fields").then((res) => res.json()) ]).then(([data, fields]) => { - table.setConfig({data, fields}); + table.setConfig({ data, fields }); }); ~~~ -## 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. +Pivot accepts CSV data after you convert it to JSON with an external JS parsing library. The converted data behaves the same as native JSON. -To convert data, you should use an external parsing library for JS to convert data from CSV to JSON. +The example below uses the external [PapaParse](https://cdnjs.cloudflare.com/ajax/libs/PapaParse/5.4.1/papaparse.min.js) library to load and convert data on a button click. The `convert()` helper 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 of CSV field names +- `meta` — an object mapping field names to 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 +The following code snippet creates Pivot, defines the `convert()` helper, and applies parsed CSV data through [`setConfig`](api/methods/setconfig-method.md) on a button click: ~~~jsx const table = new pivot.Pivot("#root", { @@ -238,7 +240,7 @@ function fromCSV() { "when" ]; - // date fields must be explicitly marked for proper conversion + // mark date fields explicitly for proper conversion const meta = { when: "date" }; const dataURL = "https://some-backend-url"; @@ -263,7 +265,7 @@ document.body.appendChild(importButton); ## Example -In this snippet you can see how to load JSON and CSV data: +The snippet below loads JSON and CSV data: @@ -272,4 +274,4 @@ In this snippet you can see how to load JSON and CSV data: - [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.md#date-formatting) diff --git a/docs/guides/localization.md b/docs/guides/localization.md index 2c3be82..81f60af 100644 --- a/docs/guides/localization.md +++ b/docs/guides/localization.md @@ -6,15 +6,15 @@ 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. +Pivot lets you localize every label in the interface. Create a new locale or modify a built-in one, then apply the locale to Pivot via the [`locale`](api/config/locale-property.md) property or the [`setLocale`](api/methods/setlocale-method.md) method. ## Default locale -The **English** locale is applied by default: +Pivot applies the English locale by default. The following code snippet shows the structure of the built-in `en` locale: ~~~jsx const en = { - //pivot + // pivot pivot: { sum: "Sum", min: "Min", @@ -49,7 +49,7 @@ const en = { "Hide settings": "Hide settings" }, - //query + // query query: { "Add filter": "Add filter", "Add Filter": "Add Filter", @@ -84,7 +84,7 @@ const en = { "not between": "not between" }, - //calendar + // calendar calendar: { monthFull: [ "January", @@ -138,65 +138,73 @@ const en = { clockFormat: 24, }, - //core + // core core: { - ok:"OK", - cancel:"Cancel", + ok: "OK", + cancel: "Cancel", select: "Select", "No data": "No data" }, - //formats + // formats formats: { dateFormat: "%d.%m.%Y", timeFormat: "%H:%i" - } + }, lang: "en-US", }; ~~~ -## Applying locales +## Apply a locale -You can access built-in locales via the pivot object. Pivot provides three built-in locales: en, de, cn. +Pivot exposes three built-in locales through the `pivot.locales` object: `en`, `de`, and `cn`. Pass a built-in locale to the [`locale`](api/config/locale-property.md) property during initialization. -Example: +The following code snippet initializes Pivot with the German locale: ~~~jsx -new pivot.Pivot({ +new pivot.Pivot("#root", { // other properties locale: pivot.locales.de, }); ~~~ -To apply a custom locale, you need to: +To apply a custom locale: + +- create a locale object (or modify a built-in one) and provide translations for all text labels (in any language) +- apply the locale to Pivot via the [`locale`](api/config/locale-property.md) property or the [`setLocale`](api/methods/setlocale-method.md) method -- 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 +The following code snippet creates Pivot, then applies a custom Korean locale at runtime 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 = { /* object with locale */ }; widget.setLocale(ko); ~~~ -## Date formatting +:::tip +Call [`setLocale`](api/methods/setlocale-method.md) without arguments (or with `null`) to reset Pivot to the default English locale. +::: -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". +## Format dates {#date-formatting} -Example: +Pivot accepts dates as `Date` objects. Parse string values to `Date` before passing data to Pivot. The default `dateFormat` is `"%d.%m.%Y"`, taken from the current locale. + +To change the format for all date fields, set a new value for `dateFormat` in the `formats` object of the [`locale`](api/config/locale-property.md) property. + +The following code snippet parses string dates into `Date` objects, then initializes Pivot with a custom `dateFormat` and updates the format at runtime via `setConfig`: ~~~jsx {17} function setFormat(value) { table.setConfig({ locale: { formats: { dateFormat: value } } }); } -// date string to Date +// convert date strings to Date objects const dateFields = fields.filter((f) => f.type == "date"); if (dateFields.length) { dataset.forEach((item) => { @@ -232,11 +240,11 @@ 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.md) property. See [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields). -## Date and time format specification +## Date and time format characters -Pivot uses the following characters for setting the date and time format: +Pivot uses the following characters to define the date and time format: | Character | Definition |Example | | :-------- | :------------------------------------------------ |:------------------------| @@ -262,22 +270,24 @@ 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 present September 20, 2024 at 16:47:08.128 as *2024-09-20 16:47:08.128*, use the format `"%Y-%m-%d %H:%i:%s.%S"`. + +## Format numbers {#number-formatting} -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". +Pivot localizes all `number` fields based on the `lang` value of the current locale. The widget uses the [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) specification. The default settings limit fraction digits to 3 and apply group separation to the integer part. -## Number formatting +To skip formatting for a specific numeric field or to set a custom format, use the `format` parameter of the [`fields`](api/config/fields-property.md) property. Set `format` to `false` to disable formatting, or to an object with format settings (see [Applying formats to fields](guides/working-with-data.md#applying-formats-to-fields)). -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)). +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 snippet below switches between several locales: diff --git a/docs/guides/stylization.md b/docs/guides/stylization.md index 3b2967c..bd88622 100644 --- a/docs/guides/stylization.md +++ b/docs/guides/stylization.md @@ -6,8 +6,12 @@ description: You can learn about the styling in the documentation of the DHTMLX # Styling +Pivot ships with a default theme and exposes CSS variables and utility classes for customization. Override the variables on the widget container (or any ancestor) to change colors, borders, and other visual properties. + ## Default style +The default Pivot theme is **Material**. The following CSS snippet shows the variables that the Material theme sets on the widget container: + ~~~css .wx-material-theme { --wx-theme-name: material; @@ -21,22 +25,21 @@ 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. +Future versions of Pivot may rename CSS variables. Check the variable names after upgrading and update them in your code to avoid display issues. ::: ## Built-in theme -The widget provides one built-in theme which is the **Material** theme. +Pivot provides one built-in theme: **Material**. Apply the theme either by adding the theme class to the widget container or by including the prebuilt skin stylesheet on the page. -You can apply the theme via adding the corresponding *CSS* classes to the widget container: +The following code snippet applies the Material theme by adding the `wx-material-theme` class to the widget container: -- **Material theme** ~~~html {}
~~~ -or just include the theme on the page from the skins folder: +The following code snippet includes the Material skin stylesheet directly: ~~~html {} @@ -44,7 +47,9 @@ or just include the theme on the page from the skins folder: ## Customize built-in theme -The example below demonstrates how to customize the **Material** theme that is applied to the Pivot table: +Override the Material theme variables on the `.wx-material-theme` selector to change colors, borders, and other visual properties. + +The example below overrides Material theme variables to render Pivot in a dark color scheme: ~~~html @@ -70,9 +75,9 @@ The example below demonstrates how to customize the **Material** theme that is a ## Custom style -You can change the appearance of Pivot by applying the corresponding CSS variables. +Change the appearance of Pivot by overriding the CSS variables on a custom class applied to the widget container. -The example below shows how to apply a custom style to Pivot: +The example below applies a custom style to Pivot via the `.demo` class: ~~~html
@@ -91,20 +96,23 @@ The example below shows how to apply a custom style to Pivot: ## Scroll style -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). +Apply a custom style to the Pivot scroll bar with the `.wx-styled-scroll` CSS class. Check browser compatibility before use: [caniuse: CSS Scrollbar](https://caniuse.com/css-scrollbar). + +The following code snippet enables the styled scroll bar on the widget container: ~~~html {} title="index.html" - +
~~~ ## Cell style -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. +To style body or footer cells, use the `cellStyle` parameter of the [`tableShape`](api/config/tableshape-property.md) property. To style header cells, use the `cellStyle` parameter of the [`headerShape`](api/config/headershape-property.md) property. In both cases, the `cellStyle` function returns a CSS class name that Pivot applies to the cell. + +The example below applies styles to body and header cells: -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) +- body cells receive a class based on cell values (e.g., `"Down"`, `"Up"`, `"Idle"` in the `status` field) and on total values (greater than 40 or less than 5) +- header cells receive a class based on the value of the `streaming` field — `status-down` for `"no"` and `status-up` for any other value ~~~jsx const widget = new pivot.Pivot("#pivot", { @@ -155,14 +163,15 @@ 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.md) property to apply a CSS class to cells that meet a condition. Each entry in `marks` pairs a CSS class name (the key) with a rule (the value). -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. +The rule is either a predefined string (`"max"` or `"min"`) or a custom function `(value, columnData, rowData) => boolean`. When the function returns `true`, Pivot adds the CSS class to the cell. -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 the CSS classes in your stylesheet before applying `marks`. + +The example below highlights cells with the minimum and maximum values, and uses a custom function to mark non-integer values greater than 2: ~~~jsx {18-26} const table = new pivot.Pivot("#root", { @@ -194,6 +203,8 @@ const table = new pivot.Pivot("#root", { }); ~~~ +The following code snippet defines the CSS classes referenced by the `marks` object above: + ~~~html title="index.html" ~~~ -It's also possible to customize the style of total columns via the ` .wx-total` CSS class: +To style total columns, override the `.wx-total` CSS class. + +The following code snippet styles total cells with a light background and a heavier font weight: ~~~html