Overview

Chart Tutorials  

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 with custom functionality to a chart in a portable way that work across all devices.

By adding toolbar options and controls, a chart can become more flexible and provide a more accessible way to visualize data in different ways or display different data through the same chart interface. In essence, a single chart can carry a larger workload which can reduce the number of charts needed to accomplish the same goal when no UI options are available.

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.

Chart.options({
  toolbar: {
    items: { Refresh: { events: { click: () => 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: {
      /*...*/
    }
  }
}

🔗uiItem elements

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 invisible.

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. For example:

{
  label: { text: "Settings" },
  icon: { name: "system/default/settings", position: "ca: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. 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

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 two shortcuts which both wrap type 'option' with additional styling settings:

  • checkbox
  • radio

These types add the checkbox and radio icons to represent their true/false states.

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

Each item is able to fire the following events:

  • click
  • change
  • mouseover
  • mouseout

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.

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 the chart area on any side or corner of chart area box by setting the item.position property with an orientation value.

Items that use the same position are stacked so they wont simply overlap. Since uiItems extend annotations, they utilize the same positioning system.