Synchronizing Dashboards components

In addition to sharing data via the data pool, Dashboards components can use the synchronization mechanism to aid visualization, navigation and highlighting of specific data.

How to synchronize Dashboards components?

To synchronize components, you need to specify the event you want to synchronize between each component. Additionally, both components must use the same connector from the dataPool , a prerequisite for all predefined synchronization types to work.

Not every component supports all synchronization types. This is an overview of which synchronization applies to each component type:

In addition to the predefined syncs, Dashboards offers the possibility to use custom synchronization. This is an example of how custom synchronization works.

Synchronization declaration

sync: {
    crossfilter: true
}

The above is a shortened way in which you cannot set additional options if a given type of synchronization provides them. Only those enabled by default are set.

If you would like to enable, say, the affectNavigator option for the crossfilter sync, you must use a declaration like this:

sync: {
    crossfilter: {
        enabled: true,
        affectNavigator: true
    }
}

The options above are only available for the Navigator Component . Each component can have its options for the predefined syncs. You can find their descriptions in the articles about these components (eg. the Highlight Sync options for the Highcharts Component ).

An example of synchronized components:

Dashboards.board('container', {
  dataPool: {
      connectors: [{
          id: 'Vitamin',
          type: 'CSV',
          options: {
              csv: `Food,Vitamin A,Iron
              Beef Liver,6421,6.5
              Lamb Liver,2122,6.5
              Cod Liver Oil,1350,0.9
              Mackerel,388,1
              Tuna,214,0.6`,
          },
      }]
  },
  components: [{
      connector: {
          id: 'Vitamin'
      },
      sync: {
          visibility: true,
          highlight: true,
          extremes: true
      },
      renderTo: 'dashboard-col-0',
      type: 'Highcharts'
  }, {
      renderTo: 'dashboard-col-1',
      connector: {
          id: 'Vitamin'
      },
      sync: {
          visibility: true,
          highlight: true,
          extremes: true
      },
      type: 'Highcharts'
  }]
});

Each synchronization has also handler and emitter options. The handler handles events coming to the component, while the emitter sends events from the component. In the case of synchronization types that communicate bilaterally (e.g. highlight), you can disable emitter or handler by setting their values to false. You can read about it more in API docs .

For example, a component with this set of highlight options will cause other components with this synchronization enabled to respond to hover. Still, this component will not respond to the hover of the others:

sync: {
    highlight: {
        enabled: true,
        handler: false
    }
}

Similarly, this set of options allows a component to have highlighted points, but it will not trigger highlighting in other components:

sync: {
    highlight: {
        enabled: true,
        emitter: false
    }
}

Synchronization groups

By default, all components with a given type of synchronization enabled and sharing the same connector are synchronized. If you want to synchronize only specific components, you can do so using the group option, which is available for each type of synchronization.

Example:

sync: {
    visibility: {
        enabled: true,
        group: 'group-name'
    }
}

Demo:

Custom synchronization

Each type of synchronization works thanks to defined functions such as handler and emitter. These functions are called when the component is loaded. Their main task is to register send (emitter) and receive (handler) events for a given component. The this keyword refers to the reference of the component for which sync is registered. The emitter and handler functions should return a function containing event unregistering to enable disabling sync or re-registering it with changed options after component.update method.

For each component, you can add or overwrite a custom definition of the existing synchronization  handler and/or emitter to expand its functionality. You can also define your synchronization from scratch.

sync: {
    customSync: {
        emitter: function() {
            registerEmitterEvents();
            return () => {
                unregisterEmitterEvents();
            }
        },
        handler: function() {
            registerHandlerEvents();
            return () => {
                unregisterHandlerEvents();
            }
        }
    }
}

Synchronization generally uses the dataCursor object, an entity common to the entire Dashboard. It is associated with the data table and allows you to create a relationship between the user interface states and the table cells, columns, or rows. The data cursor can emit and receive events.

To add synchronization to a custom component , define a static field predefinedSyncConfig which should contain two options:

• defaultSyncOptions - a record of default options per synchronization type (can be empty if we do not want to define options).
• defaultSyncPairs - a record of default emitter and handler definitions per defined synchronization type.

Additionally, after the component has finished rendering, you must run the this.sync.start() method to register the options and run the handlers and emitters.

class CustomComponent extends Component {
    static predefinedSyncConfig = {
        defaultSyncOptions: {
            customSync: {
                sampleOption: true
            }
        },
        defaultSyncPairs: {
            customSync: {
                emitter: function() {
                    ...
                },
                handler: function() {
                    ...
                }
            }
        }
    };
 
    constructor(cell, options) {
        super(cell, options);
        return this;
    }
 
    render() {
        super.render();
        this.sync.start();
        return this;
    }
}

The below example shows how custom sync  between a Highcharts Component  and a custom component  works: