[update] custom formats moved to working with data

Author: tbshag2

docs/api/config/fields-property.md

@@ -107,6 +107,6 @@ const table = new pivot.Pivot("#root", {
 **Related articles**: 
 
 - [Number formatting](/guides/localization/#number-formatting)
-- [Custom fields formatting](/guides/custom-formatting)
+- [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields)
 
 **Related sample:**  [Pivot 2. Defining fields formats](https://snippet.dhtmlx.com/77nc4j8v)

docs/api/events/render-table-event.md

@@ -48,7 +48,7 @@ The callback of the action takes the `config` object with the following paramete
      - `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](/guides/custom-formatting/#custom-date-formatting) or [number format](/guides/custom-formatting/#custom-number-formatting)
+    - `format` (string or object) - (required) date format or number format (refer to [Applying formats to fields](/guides/working-with-data/#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](/guides/custom-formatting/#custom-date-formatting) or [number format](/guides/custom-formatting/#custom-number-formatting)
+        - `format` (string or object) - date format or number format (refer to [Applying formats to fields](/guides/working-with-data/#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

docs/api/helpers/template.md

@@ -41,7 +41,7 @@ For body cells the function takes the next parameters:
      - `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](/guides/custom-formatting/#custom-date-formatting) or [number format](/guides/custom-formatting/#custom-number-formatting)
+    - `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))
     - `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](/guides/custom-formatting/#custom-date-formatting) or [number format](/guides/custom-formatting/#custom-number-formatting)
+        - `format` (string or object) - date format or number format (please refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields))
 
 For header cells the function parameters are the following:
 
@@ -66,7 +66,7 @@ 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](/guides/custom-formatting/#custom-date-formatting) or [number format](/guides/custom-formatting/#custom-number-formatting)
+    - `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))
 - `column` - (required) an object with column data (the same as for the body cell)
 
 ### Example

docs/guides/custom-formatting.md

@@ -232,7 +232,7 @@ 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 [Custom date formatting](/guides/custom-formatting/#custom-date-formatting).
+In case you need to set a custom format to a specific field, use the `format` parameter of the [`fields`](/api/config/fields-property) property. Refer to [Applying formats to fields](/guides/working-with-data/#applying-formats-to-fields).
 
 ## Date and time format specification
 
@@ -268,7 +268,7 @@ To present the 20th of June, 2024 with the exact time as *2024-09-20 16:47:08.12
 ## Number formatting
 
 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 [Custom number formatting](/guides/custom-formatting/#custom-number-formatting)). 
+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)). 
 
 ~~~jsx
 const fields = [

docs/guides/localization.md

@@ -12,7 +12,7 @@ This page describes how to aggregate data in Pivot. For the instructions about l
 
 Use the [`fields`](/api/config/fields-property) property to add fields to the Pivot table. To add a new field, you should add a new object to the `fields` array.  
 
-### Example
+Example:
 
 ~~~jsx
 const table = new pivot.Pivot("#root", {
@@ -28,11 +28,99 @@ const table = new pivot.Pivot("#root", {
 });
 ~~~
 
+## Applying formats to fields
+
+For the description of default formatting of date and numeric fields, which depends on locale, refer to [Date formatting](/guides/localization/#date-formatting) and [Number formatting](/guides/localization/#number-formatting).
+
+In case you need to set a custom format to a specific field, use the `format` parameter of the [`fields`](/api/config/fields-property) property. You can add text before and after numeric values using the `prefix` and `suffix` parameters. For example, to convert the value *12.345* to "12.35 EUR", `format` should contain the " EUR" suffix and maximumFractionDigits of 2:
+
+~~~js
+const fields = [
+     { id: "sales", type: "number", format: {suffix: " EUR", maximumFractionDigits: 2}},
+];
+~~~
+
+By default, the format for numeric values limits fraction digits to 3 and applies group separation for the integer part. You can cancel formatting by setting `format` to *false* in the `field` configuration:
+
+~~~js
+const fields = [
+     { id: "year", label: "Year", type: "number", format: false},
+];
+~~~
+
+In the example below, fields like marketing, profit, and sales are identified as currency-related. A formatting object is applied to these fields with:
+
+- prefix: "$" to display a dollar sign
+- *minimumFractionDigits* and *maximumFractionDigits* set to 2 for consistent decimal formatting
+
+~~~jsx
+// Initialize pivot with pre-defined dataset and fields
+new pivot.Pivot("#pivot", {
+    data,
+    config: {
+        rows: ["state", "product_type"],
+        columns: [],
+        values: [
+            { field: "marketing", method: "sum" },
+            // other values
+
+        ],
+    },
+    fields:[
+        // Custom format
+        { id: "marketing", label: "Marketing", type:"number", format:{
+                prefix: "$", minimumFractionDigits: 2, maximumFractionDigits: 2 }
+        }
+    ]
+});
+~~~
+
+To override the default locale-wide `dateFormat`, apply the `format` parameter of the [`fields`](/api/config/fields-property) property. Date format is a string, for example:
+
+~~~jsx
+const fields = [
+     { id: "date",  type: "date",  format: "%M %d, %Y"},
+];
+~~~
+
+In the example below we set the date format to "%d %M %Y %H:%i" for the "date" field only. The format displays day, full month name, year, hours, and minutes, e.g., "24 April 2025 14:30". In case you need to disable formatting of some fields, set the `format` parameter of the [`fields`](/api/config/fields-property) property to *false*. 
+
+~~~jsx
+// Convert date strings to Date objects
+const dateFields = fields.filter(f => f.type === "date");
+dataset.forEach(item => {
+    dateFields.forEach(f => {
+        const v = item[f.id];
+        if (typeof v === "string") {
+            item[f.id] = new Date(v);
+        }
+    });
+});
+
+// Initialize Pivot with field-specific date format
+new pivot.Pivot("#pivot", {
+    data,
+    config: {
+        rows: ["state"],
+        columns: ["product_type"],
+        values: [
+            { field: "date", method: "min" },
+            { field: "profit", method: "sum" },
+            { field: "sales", method: "sum" }
+        ]
+    },
+    fields:[
+        // Custom format: Day Month Year Hour:Minute
+        {id:"date", label:"Date", type:"date", "%d %M %Y %H:%i"}
+    ]
+});
+~~~
+
 ## Defining Pivot structure
 
 You can create the Pivot structure using the [`config`](/api/config/config-property) property that also defines how data is aggregated. By default, it has no predefined values. You need to specify this property to define the configuration of the Pivot table, namely, which fields should be applied as columns and rows. The property also allows adding data aggregation methods to be applied to the fields. Here you can also add filters. Please, refer to the [`config`](/api/config/config-property) property description for details.
 
-### Example
+Example:
 
 ~~~jsx {4-18}
 const table = new pivot.Pivot("#root", {
@@ -202,7 +290,7 @@ To interrupt data rendering and prevent the component from hanging, you can limi
 Limits are used for large dataset. Limits values are approximate values and do not show the exact values of the rows and columns.
 :::
 
-### Example
+Example:
 
 ~~~jsx
 const table = new pivot.Pivot("#root", {
@@ -280,7 +368,7 @@ const defaultMethods = {
 
 You can apply default methods using the `values` parameter of the [`config`](/api/config/config-property) property. See [Options for defining values](#options-for-defining-values) below.
 
-### Example
+Example:
 
 ~~~jsx
 const table = new pivot.Pivot("#root", {
@@ -311,7 +399,7 @@ You can define `values`in either of the two equally valid ways:
 - option one is a string representing a data field ID: `operation(fieldID)`
 - option two is an object containing the field ID and the method for data aggregation (both are required): `{ field: string, method: string }`
 
-### Example
+Example:
 
 ~~~jsx
 values: [
@@ -574,6 +662,8 @@ In this snippet you can see how to apply custom maths operations:
 <iframe src="https://snippet.dhtmlx.com/lv90d8q2?mode=result" frameborder="0" class="snippet_iframe" width="100%" height="600"></iframe> 
 
 **Related samples:**
-- [Pivot 2. Grand total for columns and rows](https://snippet.dhtmlx.com/f0ag0t9t)
+
 - [Pivot 2. Dataset with aliases](https://snippet.dhtmlx.com/7vc68rqd)
+- [Pivot 2. Defining fields formats](https://snippet.dhtmlx.com/77nc4j8v)
 - [Pivot 2. External filter](https://snippet.dhtmlx.com/s7tc9g4z)
+- [Pivot 2. Grand total for columns and rows](https://snippet.dhtmlx.com/f0ag0t9t)

docs/guides/working-with-data.md

@@ -15,7 +15,7 @@ Released on ...
 ### New functionality
 
 - [Ability to freeze columns on the right](/guides/configuration/#freezing-columns-on-the-right)
-- [Numbers are formatted](/guides/localization/#number-formatting) according to the current locale with [a new possibility to define custom number formats within templates](/guides/custom-formatting) (for date and numeric fields) via `format` added to the [`fields`](/api/config/fields-property) property
+- [Numbers are formatted](/guides/localization/#number-formatting) according to the current locale with [a new possibility to define custom number formats within templates](/guides/working-with-data/#applying-formats-to-fields) (for date and numeric fields) via `format` added to the [`fields`](/api/config/fields-property) property
 - [Ability to style header and table cells](/guides/stylization/#cell-style) via the `cellStyle` parameter of the [`tableShape`](/api/config/tableshape-property) and [`headerShape`](/api/config/tableshape-property) properties
 - Ability to insert HTML content to header and table cells via the [`pivot.template`](/api/helpers/template) helper by defining a template as a `cell` property of the header and column objects (table customization by intercepting the [render-table](/api/events/render-table-event) event)
 - [Excel and CSV export settings enhanced](/guides/exporting-data):

docs/news/whats-new.md

@@ -196,7 +196,6 @@ module.exports = {
             items: [
                 "guides/initialization",
                 "guides/configuration",
-                "guides/custom-formatting",
                 "guides/exporting-data",
                 "guides/loading-data",
                 "guides/localization",