Visualization definition

Slots

Slots define the aspects in the visualization that can hold your data. For example, in a bar visualization you might have two slots, one for the categorical tuples and one for values. A slot must at least have a name (for internal reference) and a type (categorical or continuous). A typical slots definition might look as follows:

<slots>
    <slot name="categories" caption="Categories" type="cat" optional="false" />
    <slot name="values" caption="Values" type="cont" optional="false" />
    <slot name="series" caption="Color" type="cat" optional="true" channel="color" />
</slots>

The name and type attributes are mandatory and hold the internal name and type of the slot.

The caption attribute contains the name that can be used in an application’s UI. You can either specify a literal string here, or a reference to a localized string such as $nls.categories. For more information, see Localization.

The optional attribute indicates whether the visualization is able to render anything meaningful without any data mapped to that slot. For instance, in the previous example the series slot is marked optional. This means that if the user does not map data into this slot, the visualization renders only one default series.

Finally, the channel attribute indicates that the hosting application can use a specific encoding to represent a legend for that slot. Possible values for channel are colorand size. For more information, see Legends.

DataSets

A DataSet defines the collection of slots that form the edges of your data. Currently, only one data set is supported by RenderBase, so your typical DataSets entry in VizDef.xml looks as follows:

<dataSets>
    <dataSet name="data">
        <ref slot="categories" />
        <ref slot="series" />
        <ref slot="values" />
    </dataSet>
</dataSets>

Each slot that you defined in the slots section must be listed in a data set.

Properties

A visualization can expose properties that allow the user of the visualization to control various aspects of the behavior of the visualization. Each property is defined at least by a name and a type. Depending on the property type, other attributes can be applied. A visualization can organize properties into logical groups. It is up to the host application if it wants to show the property grouping in the UI. An example:

<properties>
    <group name="general">
        <!-- Boolean property with default value = true -->
        <boolean name="labels.visible" defaultValue="true" />
        <!-- Positive numeric value; allow null to indicate 'automatic' tick count -->
        <number name="ticks.count" minValue="0" allowNull="true" />
        <!-- String property; allow null to indicate 'automatic' title -->
        <string name="title.text" allowNull="true" />
        <!-- Font property; host receives a Font structure to change individual font aspects -->
        <font name="title.font" defaultValue="10px arial" />
    </group>
</properties>

The following attributes can be applied to a property:

• name: The name of the property. Used to refer to the property in the rendering service code.
• caption: The label that appears in the UI for the property. Can be a literal string, or a localization ID: a string prefixed with $nls..
• defaultValue: The default value that a property gets when it is initialized. If the defaultValue is not specified and allowNull is true, then the default value will be null.
• allowNull: Flag that indicates whether a host application is allowed to set a null value. Often used to indicate automatic values. For example, for a scale.
• minValue: Only for number properties, defines the minimum allowed value.
• maxValue: Only for number properties, defines the maximum allowed value.
• slot: Only for palette properties, links a palette to a slot. The palette type and slot type must match. If you omit the palette type, the slot type is taken.
• type: Only for palette properties, defines the type of the palette: cat or cont.

The following property types are available:

• string: Holds a textual value.
• number: Holds a numerical value. Minimum and maximum value can optionally be specified through the minValue and maxValue attributes.
• boolean: Holds a Boolean value.
• enum: Holds a static list of values from which a user of the visualization can choose one. The list of possible values can be specified in <possibleValue> elements. See the example code further down.
• color: Holds a color value. The defaultValue of a color can be a cascading stylesheet (css) representation of a color, including named colors (‘red’, ‘green’).
• font: Holds a css font definition.
• palette: holds a palette reference. A palette is defined by a name and possibly a defaultValue. If no defaultValue is specified, a built-in palette is assigned. Default values for a palette are defined by a semi-color separated list of colors.

<!-- font property example -->
<font name="axis.title" defaultValue="bold 16px Arial" />

<!-- enum property example -->
<enum name="shape" caption="Shape">
    <possibleValue caption="Circle">circle</possibleValue>
    <possibleValue caption="Square">square</possibleValue>
</enum>

<!-- palette property example -->
<palette name="color" type="cat" defaultValue="red;green;blue" />
<palette name="range" type="cont" defaultValue="red 0%;green 50%;blue 100%" />

Capabilities

If your visualization must be able to respond to highlights and selections, then specify the following section in your vizdef.xml file:

<capabilities>
    <decorations>
        <decoration name="selected" type="boolean" target="datapoint" />
        <decoration name="hasSelection" type="boolean" target="dataset" />
        <decoration name="highlighted" type="boolean" target="datapoint" />
    </decorations>
</capabilities>

This section tells the host application that data points can be selected and highlighted. If you do not want your visualization to use the built-in support for highlighting and selection, then you can choose not to include this section in your vizdef.xml file.

Localization

The vizdef.xml file holds information that a host application can use to render a user interface. For example, the vizdef.xml file holds all properties that a visualization exposes and a host application can read these properties and show them to the end in a properties panel.

To allow localization of property names and descriptions, a special notation was introduced that maps the value of an attribute to an index of a resource table. For example, look at the following property definition:

<boolean name="labels.visible" caption="$nls.labels.visible" defaultValue="true" />

The caption is user-facing and can be localized. Instead of hardcoding a value in this attribute, use an ID: $nls.labels.visible. A resource table is then used to look up this ID and find the actual caption in the correct language.

The resource table that contains these localized strings is formatted according to the requirejs i18n.js plug-in. For customvis to correctly find and process your localizations, you must have a file and folder structure similar to the following example:

./nls/de/Resources.js
./nls/nl/Resources.js
./nls/Resources.js

This example contains a base, or root, language in ./nls and German and Dutch translations in ./nls/de and ./nls/nl. The root Resources.js file looks as follows:

define(
{
    "root":
    {
        "labels.visible" : "Show Labels",
        "labels.font"    : "Label Font"
    },
    "nl": true,
    "de": true
} );

Each of the language-specific files has the following content:

define(
{
    "labels.visible" : "Toon Labels",
    "labels.font"    : "Label Lettertype"
} );

The resource entries found here are not limited to strings used in the VizDef. You can also include entries that are used in your rendering code. For more information, see Localization.

For more information on REQUIREJS API, see the requirejs documentation.