Synchronizing components

Components may require synchronization that aids in visualizing, navigating and highlighting specific data.

How to synchronize the 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 defined in the dataPool, which is necessary for all predefined synchronization types to work.

List of synchronization types for each component type:

Component's typehighlightextremesvisibilitycrossfilter
HTMLnononono
Highchartsyesyesyesno
DataGridyesyesyesno
KPInoyesnono
Navigatornoyesnoyes

In addition to the predefined syncs, you can define your own custom synchronization. See here how to do it.

Sync declaration

sync: {
    crossfilter: true
}

The above is a shortened way that 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, for example, 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 own 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 overwriting their value 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, but 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
    }
}

Sync groups

By default, all components with a given type of synchronization enabled and sharing the same connector are synchronized. If you want to divide synchronized components into groups, 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 sending (emitter) and receiving (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 own synchronization from scratch.

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

Synchronization most often uses the dataCursor object, which is common to the entire board. It points to a data table and allows you to create a relationship between the states of the user interface and the table cells, columns, or rows. The 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 should 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 demo below shows a custom sync connecting the Highcharts Component with a custom component:

Edit this page