Configuring Pivot

As a complex widget, Pivot consists of many stand-alone Webix views with their own API.
You can redefine inner views and also you can work with the specific Pivot settings.

Basic Configuration

You can use the following settings to provide the basic config of the widget:

• url (string) - the URL to fetch data from
• fields - defines data fields
• mode (string) - defines current display mode. The possible values are:
  • "tree" - treetable is displayed initially (by default)
  • "table" - table is displayed initially
  • "chart" - chart is displayed initially.
• structure - defines the current data structure. Contains the following settings:
  • rows (array) - an array of the rows. The rows are displayed in the treetable
  • columns (array) - an array of the columns. The columns are displayed above the datatable area. Equivalent to the groupBy property in the "chart" mode
  • values (array) - an array of value object settings. Each object includes the following fields:
    • name (string) - field name
    • operation (string, array) - operation name. Built-in (e.g. "sum") or custom one. Can be a single name or an array of names
    • format (function) - a formatting function for the value in the related column
    • color (string) - HEX color for chart series.
  • filters (array) - an array of fields that are used as filters.
  • groupBy (string) - name of the field to group values by. Used in the chart mode. Equivalent to the columns field in the "table" and "tree" modes.
• datatable - defines settings for the grid in the table and tree modes. Inside this object you can provide any setting valid for the Datatable widget. It also has the following settings of its own:
  • footer (boolean, string) - defines whether to show a sum of values in the column footer. Possible values are:
    • true
    • false (by default)
    • "sumOnly" - to calculate totals only for "sum" columns.
  • minX (boolean) - highlights the lowest value in a row
  • maxX (boolean) - highlights the highest value in a row
  • minY (boolean) - highlights the lowest value in a column
  • maxY (boolean) - highlights the highest value in a column
  • cleanRows (boolean) - defines whether to remove repetitions of values in the first columns (in the table mode).
  • totalColumn (boolean, string) - defines whether to show column(s) with totals for each value. Possible values are:
    • true
    • false
    • "sumOnly" - calculates totals only for columns the "sum" function is applied to.
  • transpose (boolean) - arranges math results on the row axis
• chart - defines settings for the chart in the chart mode. Inside this object you can provide any setting valid for the Chart widget. Here are some of the settings:
  • type (string) - chart type
  • scale (string) - chart scale
  • legend (object) - chart legend
  • scaleColor (string) - scale colors. Can be a hex code or a color name ("#999999", or "grey")
  • xAxis.lines (boolean) - if false, the X axis lines are not shown
  • yAxis.lines (boolean) - if false, the Y axis lines are not shown
  • labels (boolean) - if false, the labels are not shown
  • 3D (boolean) - sets 3D chart (pie and donut charts only)
• operations (object) - stores custom operations
• predicates (object) - defines custom predicates
• locale (object) - name of the language in use or an object with language settings
• readonly (boolean) - if true, user cannot configure Pivot via form. false by default
• compact (boolean) - compact mode. Not set undefined by default
• override (object) - a Map of modified inner classes and services used for customization.

webix.ui({
  view: "pivot",
  url: "https://docs.webix.com/pivot-backend/",
  mode: "chart",
  structure: {
    groupBy: "year",
    rows: ["form", "name"],
    values: [{ name: "oil", operation: ["min", "sum"] }],
  }
});

Related sample:  Pivot: Chart Mode

Reactive Configuration

The mode, structure, datatable, chart, and readonly properties are also accessible as reactive via the widget state. They store global app state and let developers track its changes. Any changes of a reactive property is immediately reflected in the widget. Apart from these properties there are a couple of others:

• config (boolean) - shows whether the configuration form is opened
• fields (array) - an array with field objects. Each object contains the following fields:
  • name (string) - field name
  • value (string) - field value
  • type (number) - field type. Possible values are:
    • "text" - if field value is a string
    • "number" - if field value is a number
    • "date" - if field value is a date.
  • predicate (string) - predicate of the field
  • prepare (function) - prepares raw data. Accepts a single parameter - raw value (e.g. "2007").

You can get the current state of the widget with the help of the getState method:

webix.ui({
    view:"pivot", 
    id:"pivot",
    url: "https://docs.webix.com/pivot-backend/"
});
 
const state = $$("pivot").getState();
/*
  {
    chart: {
      scale: "linear",
      type: "bar"
    },
    config: true,
    datatable: {
      footer: true,
      maxY: true
    },
    fields: [
      {name: "oil", value: "oil", type: 1, predicate: "date"},
      // other fields
    ],
    mode: "tree",
    readonly: false,
    structure: { ...structure config }
  }
*/

How to Listen to Changes of the Reactive Properties

You can use $observe handler to listen to changes and provide custom handlers for them:

$$("pivot")
  .getState()
  .$observe("structure", (structure, old) => {
    if (
      old &&
      structure.filters.length &&
      !structure.filters.find(o => o.external)
    )
      $$("filter").setValue("");
  });

Related sample:  Pivot: External Filters

In the sample above, the current state is accessed via JetApp instance which is available in the onInit event handler.

Back to top