Documentation

Pivot Chart

Webix Pivot Chart is fully client-side Javascript tool for graphical representation of data. A plenty of configuration options allows users to use the tool for understanding, analyzing and researching large quantities of data and the relationships between them.

External resources

Design and Usage

Webix Pivot Chart consists of two functional parts:

  1. Webix chart reflecting specified data properties and conditions:

  2. Configuration window (appeared when the user clicks the 'Settings' button):

Configuration Window

The window reflects the current Pivot Chart structure and contains four sections. The elements inside sections are based on the data item's properties from the dataset and can be dragged to change Pivot Chart structure:

Sample data

[
    {"name": "China", "year": 2005, "continent": "Asia", "form": "Republic", 
    "gdp": 2256.919, "oil": 59.615, "balance": 134.098},
    //...
]
  • 'Fields' block presents all data properties of the dataset (such as name, year etc.) EXCEPT for those that are selected in the Filters and Group By blocks.
  • Fields dragged or initially set in the Values block define which data will be loaded to the chart. Each data property in the Values block presents an individual graph (see details).
  • A field dragged or initially set in the Group By block defines a data property that Values's properties will be grouped by. For example, if the user sets the "balance" property as Values's value (the 'sum' operation) and the "year" property as Group by's value then the chart will display the total balance of all contries for each year. Note, only one data property can be specified in the Group By block.
  • Fields dragged or initially set in the Filters block define data properties that will be used as filters for the chart. For each data property in the Filters block, Pivot Chart creates an individual input in the header of the chart (nearby the 'Settings' button) (see details).

Balance amoung Sections

You cannot drag one and the same element to different sections; instead, use each element either for grouping or for filtering or don't use it at all (it remains in Fields). However, Values section is more indendent since elements dragged to it are still available in other sections except Filters.

Data Operations

Current data operations come together with values they are assigned to in the Values section. Right there they can be changed with a couple of clicks.

  • Sum - sums all values of this property and shows the sum;
  • Max - picks and shows the max value of this property;
  • Min - picks and shows the min value of this property;
  • Count - counts the number of occurrencies of this property and shows it.

In addition to the above-mentioned prebuilt operation types, you can as well create a custom one.

Filtering Options

Webix Pivot Chart uses two filters:

  • text - filtering is performed by symbols you type in the text field. It supports base math comparison operators, so you can type something like "< 100", "> 2.5" or "= 12".
    If there is no operator, a filter will use text match for filtering;
  • select - filtering is performed by options that are automatically gathered from the dataset (all unique values of this property). For instance, if you choose Continents, then all unique continent names from the dataset become options.

Logarithmic scale

When difference between compared values is significant, smaller values can be hardly recognizable on the chart. To prevent it and make all values available for analysis, you can use logarithmic scale instead of default linear one.
To enable the logarithmic scale, check the "Logarithmic scale" checkbox in the configuration window.

Initialization

Since Pivot Chart tool comes as an add-on to Webix library you need to include both Webix and Pivot Chart scripts and CSS files on your page to make everything work. Make sure you specify relative paths to these files:

<html>
 <head>
  <!-- js files -->
  <script src="codebase/webix.js" type="text/javascript"></script>
  <script src="codebase/pivotchart.js" type="text/javascript"></script>
  <!-- css files -->
  <link rel="stylesheet" href="codebase/webix.css" type="text/css" charset="utf-8">
  <link rel="stylesheet" href="codebase/pivotchart.css" type="text/css" charset="utf-8">
 </head>
 <body>
   <div id = "testA"></div>  <!-- containter for Pivot Chart-->
 </body>
</html>

The initialization of Pivot Chart doesn't differ from that of other Webix components and is done with webix.ui() constructor function where you enumerate all the necessary properties:

webix.ui({
    container:"testA",
    id:"pivot",
    view:"pivot-chart",
    structure:{
        groupBy: "continent",
        values: [
            {name:"balance", operation:"max", color: "#eed236"},
            {name:"oil", operation:"max", color: "#36abee"}
        ],
        filters:[{name:"year", type:"select"}]
    },
    url: "../common/data.json"
});

Properties

  • id - string, number - component ID, should be unique within a page. In Webix, any component is referred to by its ID, $$("id"), to perform various operations with it;
  • container - string - ID of an HTML container Pivot Chart will be put to (optional);
  • fieldMap - object - can be used to define custom labels for fields (optional) (details);
  • data or url - string - defines dataset (details);
  • structure - object - defines initial display and analysis pattern (details);
  • chart - object - defines the chart configuration options that you want to redefine, i.e. object with a set of redefined properties (details);
  • chartType - string - sets the default chart type;
  • chartMap - object - can be used to redefine default types of a chart ('bar', 'line', 'radar') or add a new one ('stacked bar' or 'area') (details);
  • filterWidth - number - sets the width of filters (both input and label) in the header of the chart;
  • filterLabelWidth - number - sets the width of the filters' labels;
  • filterLabelAlign - string - sets the horizontal alignment of the filters' labels;
  • editButtonWidth - number - sets the width of the "Settings" button;
  • singleLegendItem - boolean - specifies whether the legend should be displayed if it contains only 1 item;
  • palette - array - specifies the pop-up color pallete of the Values' values
    palette:[ ["#e33fc7","#a244ea",...],["#d3ee36","#eed236",.. ],.. ] - each inner array specifies a row in the pallete

Structure Object

  • values - array of fields that will be used as pivot's data (will be displayed in datatable cells);
  • filters - array of fields that will be used as filters and will be displayed above the datatable columns;
  • groupBy - the name of the field that will be used to group values by.

Loading Data

Pivot Chart supports both inline and external (including server-side) data in any of the supported data types: XML, JSON, JSArray and CSV.

Inline Data

Inline Data (JSON)

var pivot_dataset = [
    {"name": "China", "year": 2005, "form": "Republic", "gdp": 181.357, "oil": 1.545},
    {"name": "China", "year": 2006, "form": "Republic", "gdp": 212.507, "oil": 1.732},
    //...
]

To load inline data during component init, make use of data property:

webix.ui({
    view:"pivot-chart",
    id:"pivot",
    data:pivot_dataset
});

To load inline data after component init on some event, for instance, use the parse function:

$$("pivot").parse(pivot_dataset);

External Data

Either you get data from an external file or by a server-side script,use the following pattern:

  • If you load the data during component init, specify the path to this file/script as value of url:
{
    view:"pivot-chart",
    url:"../load.php" // or "../data.json"
}
  • If you load data after the component has been inited (e.g. on some event), use the load function:
$$("pivot").load("../load.php");
//or
$$("pivot").load("../data.json");

In essence, Pivot Chart complies to standard Webix Data Loading rules.

Configuring Pivot Chart

Defining chart properties

To redefine the default properties of the chart, such as a legend or width of bars, you can use the chart object. Any property that you specify in the chart object will redefine the analogous one in the default configuration object:

view:"pivot-chart",
chart: {
    scale: "logarithmic",
    barWidth: 25,
    legend: {
        layout: "x",
        align: "center",
        valign: "bottom"
    }
}

Note, you can use any property available for the Chart component (a list of properties).

Defining Operation on Data

Operations are set within Pivot Chart structure object in values array. Name refers to data item property, color - to the color of the related graph:

view:"pivot-chart",
id:"pivot",
structure:{
    values:[
        {name:"gdp",operation:"sum",color:"#eed236"},//gdp values will be summed
        {name:"oil",operation:"max",color:"#36abee"}//max oil value will be shown
    ]
}

There are 4 prebuilt operations over data:

  • sum - default, shows the sum of values of this property;
  • max - shows the max value of this property found in the dataset;
  • min - shows the min value of this property found in the dataset;
  • count - shows the number of occurencies of this property in the dataset.

If needed, you can add your own operation:

view:"pivot-chart",
groupMethods:{
    abssum: function(template, data){
        data = data || this;
        var summ = 0;
        for (var i = 0; i < data.length; i++)
            summ+= Math.abs(template(data[i])*1);
        return summ;
    }
},

And use it as:

values:[ name:"oil", operation:"abssum"]

Filters

Filters are set within Pivot Chart structure object in filters array. Name refers to data item property used for filtering:

view:"pivot-chart",
structure:{
    values:[
        {name:"name",type:"select"},
        {name:"continent", type:"text"}
    ]
}

There are two types of filters:

  • select - filters by options automatically gathered from a dataset (all unique values of this property). For instance, if you choose Continents, then all unique continent names from the dataset become options;
  • text - filters by symbols in the text field. It supports base math comparison operators, so you can type something like "< 100", "> 2.5" or "= 12"
    If there is no operator, filter will use text match for filtering.

Renaming fields

By default Pivot Chart uses data item properties for column names. But if you have dataset structured like below, the default pattern becomes unsuitable:

[{ a1:100, a2:1.34 }, ...]

In this case, you can use the fieldMap property to set beautiful names for columns instead of a1 and a2:

webix.ui({
    view:"pivot",
    fieldMap:{ "a1" : "GDP", "a2" : "Grow ratio" },
    //...
});

Adding chart types

By default, Pivot Chart gives users a possibility to present data in 3 types of a chart: 'bar', 'line', 'radar'. If you need you can redefine the default types or add a new one.

Note, just types 'stacked bar' and 'area' can be additionally added to the Pivot Chart.

To add a new chart's type to Pivot Chart, use the chartMap property:

Adding a new chart's type

view:"pivot-chart",
chartMap: {
    "Area Radar": function(color){ //adds a new chart type 'Area Radar'
        return {
            type: "radar",
            alpha: 0.4,
            disableItems: true,
            fill: color,
            line:{
                color: color,
                width:1
            }
        }
    },
    "Line": function(color){ //redefines the default 'Line' type
        type:"line",
        offset:false,
        preset:"plot"
    }
}

The chart's type is identified by its name ("Area Radar" and "Line" in the code above). The names of the default types you can check in the 'Chart type' control of the Configuration window.

Localization

By defaut all names and titles in Pivot Chart have English names, but you can change it by setting a custom locale for the page.

webix.i18n.pivot = {
    apply: "Anwenden",
    bar: "Balken",
    cancel: "Abbrechen",
    groupBy: "Gruppieren nach",
    chartType: "Diagramm Typ",
    count: "zahl",
    fields: "Felder",
    filters: "Filtern",
    logScale: "Logarithmischen Skala",
    line: "Linien",
    max: "max",
    min: "min",
    operationNotDefined: "Operation ist nicht definiert",
    radar: "Netzdiagramm",
    select: "auswahl",
    settings: "Einstellungen",
    sum: "summe",
    text: "text",
    values: "Werte",
    valuesNotDefined: "Werte oder Gruppenfeld ist nicht definiert",
    windowMessage: "[ziehen Felder auf gewunschten Sektor]"
};
 
 
//and then init Pivot Chart and see you custom names
webix.ui({
    view:"pivot",
    //...
});

API

Getting and Setting Configuration Object

//get current configuration
var config = $$("pivot").getStructure();
 
//set configuration
$$("pivot").setConfiguration(config);

Format of a config object is the same as "structure" parameter of the constructor:

var config = {
    groupBy: "year",
    values: [{name:"balance", operation:"sum", color: "#eed236"}],
    filters:[{name:"name", type:"select"}]
}

Data export

You can export result to PDF or Excel:

$$("pivot").toPDF();
$$("pivot").toExcel();

Getting Chart Object

You can access the Chart object by using the next code:

var chart = $$("pivot").$$("chart");

This allows you use any of Chart events or API methods.

Back to top