@nebula.js/sn-grid-chart

    1.9.4 • Public • Published

    @nebula.js/sn-grid-chart

    The grid chart uses symbols of varying size sorted in a grid to visualize a measure across two dimensions. The measure is the metric that determines the size of the symbol in each crossing.

    Requirements

    Requires @nebula.js/stardust version 1.2.0 or later.

    Installing

    If you use npm: npm install @nebula.js/sn-grid-chart. You can also load through the script tag directly from https://unpkg.com.

    Usage

    import { embed } from '@nebula.js/stardust';
    import gridChart from '@nebula.js/sn-grid-chart';
    
    // 'app' is an enigma app model
    const nuked = embed(app, {
      types: [
        {
          // register grid chart
          name: 'sn-grid-chart',
          load: () => Promise.resolve(gridChart),
        },
      ],
    });
    
    // Rendering a simple grid chart
    nuked.render({
      element: document.querySelector('.grid'),
      type: 'sn-grid-chart',
      fields: ['Country', 'Year', '=Sum(Population)'],
      properties: {
        title: 'The historical populations of some European countries',
      },
    });

    More examples

    Change symbol size and shape

    The size and shape of the symbols can be modified.

    // Rendering a grid chart with customized symbols
    nuked.render({
      element: document.querySelector('.grid'),
      type: 'sn-grid-chart',
      // fields: ['Country', 'Year', '=Sum(Population)'],
      properties: {
        title: 'The historical populations of some European countries',
        dataPoint: {
          rangeBubbleSizes: [0.25, 0.85],
          symbol: 'star',
        },
      },
    });

    Customize the look of the chart

    You can color the symbol by measure and add a legend to show more information about the measure. The axis titles can be hidden and the gridlines can be shown to further improve the look.

    // Rendering a customized grid chart
    nuked.render({
      element: document.querySelector('.grid'),
      type: 'sn-grid-chart',
    
      // Define all `fields` in `properties`
      properties: {
        title: 'The historical populations of some European countries',
        qHyperCubeDef: {
          qDimensions: [
            {
              qDef: { qFieldDefs: ['Country'] },
            },
            {
              qDef: { qFieldDefs: ['Year'] },
    
              qAttributeExpressions: [
                {
                  qExpression: 'Sum(Population)',
                  id: 'colorByAlternative',
                },
              ],
            },
          ],
          qMeasures: [
            {
              qDef: {
                qDef: 'Sum(Population)',
              },
            },
          ],
          qMode: 'T',
          qAlwaysFullyExpanded: true,
        },
        color: {
          auto: false,
          mode: 'byMeasure',
          measureScheme: 'dg',
          reverseScheme: true,
        },
        legend: {
          show: true,
          dock: 'auto',
          showTitle: true,
        },
        xAxis: {
          show: 'label',
          dock: 'near',
          gridLines: true,
        },
        yAxis: {
          show: 'label',
          dock: 'near',
          gridLines: true,
        },
      },
    });

    Grid chart plugins

    A plugin can be passed into a grid chart to add or modify its capability or visual appearance. A plugin needs to be defined before it can be rendered together with the chart.

    // Step 1: define the plugin
    
    // Modifying the look of the existing point component
    const pointPlugin = {
      info: {
        name: 'point-plugin',
        type: 'component-definition',
      },
      fn: ({ layout, keys }) => {
        const componentDefinition = {
          type: 'point',
    
          // Provide the same name as the exisiting point component to override it
          key: keys.COMPONENT.POINT,
          settings: {
            strokeWidth: '2px',
            stroke: 'dimgray',
    
            // Using data property 'd' and layout as input for helper functions
            size: (d) => getSizeInLogarithmScale(d, layout),
            fill: (d) => getColorBasedOnMedian(d),
          },
        };
        return componentDefinition;
      },
    };
    
    // Step 2: passing the plugin definition into the render function
    
    // Rendering a grid chart with plugins
    nuked.render({
      element: document.getElementById('object'),
      type: 'sn-grid-chart',
      fields: ['Country', 'Year', '=Sum(Population)'],
      plugins: [pointPlugin],
      properties: {
        title: 'The historical population of some European countries',
        xAxis: { show: 'labels', gridLines: true },
        yAxis: { show: 'labels', gridLines: true },
      },
    });

    The plugin definition is an object, with two properties info and fn. The fn returns a picasso.js component. To build this component, some important chart internals are passed into the argument object of fn.

    // Structure of the argument object of fn
    const pluginArgs = {
      layout,
      keys: {
        SCALE: {
          X,
          Y,
        },
        COMPONENT: {
          X_AXIS,
          Y_AXIS,
          POINT,
        },
        COLLECTION: {
          MAIN,
        },
      },
    };

    With plugins, you can either add new components or modify existing components of the grid chart.

    Add new components

    The new component can be a standard Picasso component or a custom Picasso component. Here we demo a custom component which add labels next to the grid bubbles.

    // Implementing a custom labels plugin, so that we can use it later
    const labelsPluginDefinition = {
      info: {
        componentName: 'custom-labels-plugin',
        name: 'custom-labels-plugin',
        type: 'custom-component',
      },
      fn: () => {
        const implementation = {
          require: ['chart', 'renderer'],
          render() {
            const { items } = this.chart.component('point-component').data;
            const scale = this.chart.scales();
            const { width, height } = this.rect;
            const labels = items.map((item) => ({
              type: 'text',
              text: item.size.label,
              x: (scale.x(item.x.value) + scale.x.bandwidth() * 0.5) * width,
              y: (scale.y(item.y.value) + scale.y.bandwidth() * 0.2) * height,
              anchor: 'middle',
              fill: 'dimgray',
            }));
            return labels;
          },
        };
        return implementation;
      },
    };
    
    // Using the labels plugin, defined above
    const labelsPlugin = {
      info: {
        name: 'labels',
        type: 'component-definition',
      },
      fn: ({ keys }) => {
        const componentDefinition = {
          // The type has to match with the componentName of the labels plugin definition above
          type: 'custom-labels-plugin',
          key: 'my-labels',
        };
        return componentDefinition;
      },
    };

    Modify existing components

    As an example, the positions and the appearance of the axes can be modified completely by plugins.

    To overide an existing component, fn should returns a picasso.js component that has the same key as the existing component (keys.COMPONENT.X_AXIS in this example)

    // Modifying the look and the position of the x-axis
    const xAxisPlugin = {
      info: {
        name: 'x-axis-plugin',
        type: 'component-definition',
      },
      fn: ({ keys, layout }) => {
        const componentDefinition = {
          type: 'axis',
    
          // Provide the same name as the exisiting x-axis component to override it
          key: keys.COMPONENT.X_AXIS,
          layout: { dock: 'top' },
          settings: {
            labels: {
              fontFamily: 'Cambria, serif',
              fontSize: '15px',
              fill: 'dimgray',
            },
            line: { stroke: 'gray' },
          },
        };
        return componentDefinition;
      },
    };
    
    // y-axis plugin can be defined with similar code
    // ...

    Plugins disclaimer

    • The plugins API is still experimental.
    • We can not guarantee our charts to be compatible with all different settings, especially when modifying existing components.

    Install

    npm i @nebula.js/sn-grid-chart

    DownloadsWeekly Downloads

    546

    Version

    1.9.4

    License

    MIT

    Unpacked Size

    4.04 MB

    Total Files

    19

    Last publish

    Collaborators

    • niekvanstaveren
    • likang6688
    • ccm33
    • nilzona
    • qlikossbuild
    • veinfors
    • tobias-astrom-qlik