Step 2 - Creating the model

Quick facts on Bar charts

The simplest of Bar charts shows a single series of data: a list of pairs of a category and a measure, where each category can only occur in one of the pairs.

Each pair (i.e. each category) is represented by a bar visual element, and is assigned a stripe of the horizontal space and all of the vertical space, in which the height of the bar encodes the measure value.

Thus, the simplest Bar chart has two main data-bound visual degrees of freedom, or, as they are called in the Visualization API, visual roles: Category and Measure. The values of the fields mapped to visual roles are visually encoded using visual variables/properties such as position, size, orientation or color.

Complete model code

Create a file named model.js and place the following code in it:

define([
  "module"
], function(module) {
  "use strict";

  return ["pentaho/visual/base/model", function(BaseModel) {
    // Create the Bar Model subclass
    var BarModel = BaseModel.extend({
      $type: {
        id: module.id,

        // CSS class
        styleClass: "pentaho-visual-samples-bar-d3",

        // The label may show up in menus
        label: "D3 Bar Chart",

        // The default view to use to render this visualization is
        // a sibling module named `view-d3.js`
        defaultView: "./view-d3",

        // Properties
        props: [
          // General properties
          {
            name: "barSize",
            valueType: "number",
            defaultValue: 30,
            isRequired: true
          },

          // Visual role properties
          {
            name: "category",
            base: "pentaho/visual/role/property",
            fields: {isRequired: true}
          },
          {
            name: "measure",
            base: "pentaho/visual/role/property",
            modes: [{dataType: "number"}],
            fields: {isRequired: true}
          },

          // Palette property
          {
            name: "palette",
            base: "pentaho/visual/color/paletteProperty",
            levels: "nominal",
            isRequired: true
          }
        ]
      }
    });

    return BarModel;
  }];
});

Remarks:

• The value of the AMD module is an array of dependencies and of a factory function of Bar model classes.
• Defines a visualization (model) whose id is the file’s AMD module identifier (depending on how AMD is configured, it can be, for example: pentaho-visual-samples-bar-d3/model).
• Inherits directly from the base visualization model, pentaho/visual/base/model.
• Specifies the styleClass, which will later be useful to style the component using CSS.
• Specifies the default view to use with this model (which you’ll create in a moment).
• Three main types of property exist: general, visual roles and palettes.

The following sections explain each of the model properties.

The barSize property

specification = {
  name: "barSize",
  valueType: "number",
  defaultValue: 30,
  isRequired: true
}

A general property which determines the constant width of bars. It is of valueType number, is required and has a defaultValue of 30. That’s as simple as it gets.

The category property

specification = {
  name: "category",
  base: "pentaho/visual/role/property",
  fields: {isRequired: true}
}

Represents the Category visual role. The property is of a special type, a visual role property.

The data property, which is inherited from the base visualization model, is given a dataset containing data for fields such as Product Family and Sales. The value of a visual role contains the names of the fields that are mapped to it, e.g.: {fields: ["productFamily"]}. So, the value of a visual role is an object with a list property named fields.

The modes attribute was not specified. It defaults to a single mode of the "string" data type. Thus, the visual role will accept being mapped to fields of type "string".

Because the default data type is "string", the visual role can be mapped to at most one "string" field (for it to accept more than one "string" field, it would need to have the “list of strings” data type: “["string"]). However, it is optional by default. To make it required, the special fields attribute is configured.

The measure property

specification = {
  name: "measure",
  base: "pentaho/visual/role/property",
  modes: [{dataType: "number"}],
  fields: {isRequired: true}
}

Represents the Measure visual role. Having a single mode with the "number" data type, the visual role accepts a single field of data type "number".

The palette property

specification = {
  name: "palette",
  base: "pentaho/visual/color/paletteProperty",
  levels: "nominal",
  isRequired: true
}

Represents a color palette (see pentaho/visual/color/paletteProperty).

The value of the property will default to the highest ranked system color palette that matches the level required by it.

Register the model module

Your visualization must be advertised to the platform so that applications like Analyzer and PDI can offer it to users. This is done by registering the visualization’s Model module with pentaho/typeInfo, as a subtype of pentaho/visual/base/model.

For such, edit the package.json file and make sure it looks like this:

{
  "name": "pentaho-visual-samples-bar-d3",
  "version": "0.0.1",

  "config": {
    "pentaho/typeInfo": {
      "pentaho-visual-samples-bar-d3/model": {
        "base": "pentaho/visual/base/model"
      }
    }
  },

  "dependencies": {
    "d3": "^4.11.0"
  },
  "bundleDependencies": [
    "d3"
  ],
  "devDependencies": {
    "@pentaho/viz-api": "https://github.com/pentaho/pentaho-platform-plugin-common-ui/releases/download/v3.0.0-beta3/pentaho-viz-api-v3.0.0.tgz"
  }
}

Note the added config property.

Additional model metadata

The model could still be enriched in several ways, such as:

• Providing localized labels/descriptions for the name of the visualization and that of its properties.
• Providing standard icons for supported Pentaho themes.

However, these are all accessory and can be done at a later stage. Now you can’t wait to see something shining on the screen, so let’s move on into creating the view.

Continue to Creating the view.