FilterHandle

Use this class to contribute to, and listen for changes to, the filter set for the given group of widgets. Filter input controls should create one FilterHandle and only call set. Output widgets that wish to displayed filtered data should create one FilterHandle and use the filteredKeys property and listen for change events.

If two (or more) FilterHandle instances in the same webpage share the same group name, they will contribute to a single “filter set”. Each FilterHandle starts out with a null value, which means they take nothing away from the set of data that should be shown. To make a FilterHandle actually remove data from the filter set, set its value to an array of keys which should be displayed. Crosstalk will aggregate the various key arrays by finding their intersection; only keys that are present in all non-null filter handles are considered part of the filter set.

Kind: global class

new crosstalk.FilterHandle([group], [extraInfo])

Param Type Description
[group] string The name of the Crosstalk group, or if none, null or undefined (or any other falsy value). This can be changed later via the setGroup method.
[extraInfo] Object An object whose properties will be copied to the event object whenever an event is emitted.

filterHandle.filteredKeys ⇒ Array.<string> | null

Kind: instance property of FilterHandle
Returns: Array.<string> | null - - Either: 1) an array of keys that made it through all of the FilterHandle instances, or, 2) null, which means no filter is being applied (all data should be displayed).

filterHandle.setGroup(group)

Changes the Crosstalk group membership of this FilterHandle. If set() was previously called on this handle, switching groups will clear those keys from the old group’s filter set. These keys will not be applied to the new group’s filter set either. In other words, setGroup() effectively calls clear() before switching groups.

Kind: instance method of FilterHandle

Param Type Description
group string The name of the Crosstalk group, or null (or undefined) to clear the group.

filterHandle.close()

Close the handle. This clears this handle’s contribution to the filter set, and unsubscribes all event listeners.

Kind: instance method of FilterHandle

filterHandle.clear([extraInfo])

Clear this handle’s contribution to the filter set.

Kind: instance method of FilterHandle
Emits: change

Param Type Description
[extraInfo] Object Extra properties to be included on the event object that’s passed to listeners (in addition to any options that were passed into the FilterHandle constructor).

filterHandle.set(keys, [extraInfo])

Set this handle’s contribution to the filter set. This array should consist of the keys of the rows that should be displayed; any keys that are not present in the array will be considered filtered out. Note that multiple FilterHandle instances in the group may each contribute an array of keys, and only those keys that appear in all of the arrays make it through the filter.

Kind: instance method of FilterHandle
Emits: change

Param Type Description
keys Array.<string> Empty array, or array of keys. To clear the filter, don’t pass an empty array; instead, use the clear method.
[extraInfo] Object Extra properties to be included on the event object that’s passed to listeners (in addition to any options that were passed into the FilterHandle constructor).

filterHandle.on(eventType, listener) ⇒ string

Subscribe to events on this FilterHandle.

Kind: instance method of FilterHandle
Returns: string - - A token to pass to off to cancel this subscription.

Param Type Description
eventType string Indicates the type of events to listen to. Currently, only "change" is supported.
listener FilterHandle~listener The callback function that will be invoked when the event occurs.

filterHandle.off(eventType, listener)

Cancel event subscriptions created by on.

Kind: instance method of FilterHandle

Param Type Description
eventType string The type of event to unsubscribe.
listener string | FilterHandle~listener Either the callback function previously passed into on, or the string that was returned from on.

“change”

Kind: event emitted by FilterHandle
Properties

Name Type Description
value object The new value of the filter set, or null if no filter set is active.
oldValue object The previous value of the filter set.
sender FilterHandle The FilterHandle instance that changed the value.