Overview

A general overview of the features and functionality.

Introduction

The uiItem toolbar allows adding simple controls like dropdown, radio, checkbox, and standard button to any chart easily through a simple API. This coupled with the FP API Tutorial allows adding controls to manipulate the easily manipulate chart features and data.

By embedding UI controls inside a chart, it can add additional dimensions to the data visualization experience. Users can select different aspects of the data set to visualize. UiItem labels support micro charts and can be used like KPI indicators that select different data to display on the main chart.

Some possible uses of chart uiItems include:

Selection of data sets to compare
Selection of data to view such as a dropdown for months of the year
Change the visualization (chart/series type).
Enable or disable features such as AxisMarkers, or labels.

Let's look at a code snippet of a button that refreshes the chart data.

new JSC.Chart({
  toolbar_items: {
    Refresh: {
      events_click: function() {
        chart.options(getData());
      }
    }
  }
});

UiItems inherit from annotations and each uiItem can have a collection of uiItems that represent a nested hierarchy. The child items are defined through the items property:

{
  items: {
    ButtonA: {
      /*...*/
    },
    ButtonB: { items: { ChildOfB1: {}, ChildOfB2: {} } }
  }
}

UiItem Basic Properties

Each item can have a

Label
Icon
Type
States
Events
Items

Label

The label is defined through item.label. However, if no label or icon is defined to represent the item visually, the item name is used as the label text. To make the item have no visual representation, this can be overwritten with:

{ items: { OptionA: { label_text: "" } } }

This will make the item label invisible.

Tip: Labels can also display the item's value by using the '%value'

token in the label text. For example, a dropdown item uses '%value' label text to display the selected items.

Icon

The icon can be used by itself to represent the item visually or in combination with a label. The icon has a position property that specifies its position in relation to the label. In this example, the icon will appear to the right of the label:

{ label: { text: "Settings" }, icon: { name: "system/default/settings", position: "right" } }

This code will position the icon is on the right side of the label.

States

State properties can be set with options that the item will use when it is in the respective state.

Items can have the following states:

Normal
Hover
Select

The select state is used with items that represent a Boolean value or a button when it is depressed.

Type

The type property specifies the item behavior and value handling. It accepts a uiItemType. Some type settings are also used to define default presets that apply a number of settings for the item. See 'Shortcut Types' below.

select
selectMultiple
option
range
file

The type 'option' indicates an item with a Boolean value (true or false). It can exist at the root of uiItems hierarchy without a parent or with a parent item having type select or SelectMultiple.

Select and select multiple encompasses a set of child 'option' uiItems and indicates whether their values can be mutually exclusive or not. These child items will have their type set to 'option' by default.

Simple dropdown example

chart.options({
  toolbar: {
    items: { "simple dropdown": { type: "select", items: { optionA: {}, optionB: {}, optionC: {} } } }
  }
});

Shortcut Types

In addition to the above types, there are also these shortcuts which extend type 'option' type with additional styling settings:

checkbox
radio
toggle

Caution: The 'radio' type shortcut only defines the icon. It must be wrapped in a type: 'select' parent item in order to be grouped and work as mutually exclusive select state item.

Items

Child items are defined through the items property as keyed values as shown above.

These items are displayed with a box that is configured though the itemsBox property. One useful property is itemsBox.visible which indicates whether child items are visible by default or require a click on the parent item to display.

The items can all be set at the same time by setting the shared options on the defaultItem property.

Events

Items are able to trigger the following event names:

click
change
mouseover
mouseout

The event handlers are invoked with arguments (value, uiItem). The uiItem has a chart property which references the chart the item is part of.

When a click event handler is defined it indicates that the item might be a button. If other setting do not contradict this, the item will take on the appearance of a button.

Tip: The mouseover and mouseout events are available, but they should not be used to control styling. Instead, use the states settings.

The change event is fired when the item value changes.

Positioning

Items can be positioned inside or outside chart area on any side or corner of chart area box by setting the item.position property. See Box Positions Sample for example position values.

Items that use the same position are stacked to prevent overlaps. Since uiItems extend annotations, they utilize the same positioning system.

Documentation

Tutorials