Subscribe to a Cross-Visual Filter

When a visual subscribes to a cross-visual filter, the visual is filtered by the link field in the filter if another visual creates a cross-visual filter for the same field.

When a visual publishes a link, that visual can apply cross-visual filters using the link field to other dashboard visuals that have subscribed to the link. Cross-visual filters can only be applied if the associated link is published. In addition, they can only be applied using the Filter option on the radial menu.

The following example shows how to subscribe to a cross-visual filter:

// An embedding application should listen for the 'composer-dashboard-ready' event 
// before attempting to publish or subscribe

const DASHBOARD_READY_EVENT = 'composer-dashboard-ready';
const pubSubReady = new Promise((resolve) => {
   function resolvePubSubReady() {
      resolve();
      document.removeEventListener(DASHBOARD_READY_EVENT, resolvePubSubReady);
   }
   document.addEventListener(DASHBOARD_READY_EVENT, resolvePubSubReady);
});

// The following covers an example of how to subscribe to a linkName and receive
// the latest value published

function subscriptionHandler(<message>, <publisherId>) {
   if (<message> === null) {
      alert(<publisherId> + ' cleared its publication');
   } else {
      const value = message.ranges[0].value;
      alert(<publisherId> + ' published ' + value);
   }
}
let unsubscribe;
pubSubReady.then(() => {
   // The returned unsubscribe function should be stored and called when the
   // subscriber should stop receiving messages.
   unsubscribe = window.Zoomdata.subscribe('<linkname>', subscriptionHandler);
});

The subscribe Method

The subscribe method attaches a subscription handler to a cross-source or same-source link (filter). Each time a new cross-visual filter is published to the link, the subscription handler is called and passed the newly published filter.

When you call the subscribe method, the unsubscribe function is returned. Run the unsubscribe function to remove the handler for the link. This guarantees that the handler will no longer be notified when new messages are published for the link.

Messages passed on the channel can be an arbitrary message object or null. Because the message objects are not restricted, the subscription handler should never assume its structure and always check that the message is in the structure the handler is expecting.

Messages that are null are interpreted as a clearing of the channel and should be handled by undoing any actions taken based on the last messages received by the handler. For example, when a Composer visual receives a null message in its filtering logic, it removes any filters created by previous messages on the given channel (link).

If a message is published to the channel before the subscribe method is called, the subscription handler is executed immediately with the latest message that was published on the channel.

The subscribe Properties

The properties for the subscribe method of the Zoomdata class are described in the following table.