In rstudio/crosstalk: Inter-Widget Interactivity for HTML Widgets

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

• FilterHandle
  • [new crosstalk.FilterHandle([group], [extraInfo])](#new_FilterHandle_new)
  • .filteredKeys ⇒ Array.<string> \| null
  • .setGroup(group)
  • .close()
  • .clear([extraInfo])
  • .set(keys, [extraInfo])
  • .on(eventType, listener) ⇒ string
  • .off(eventType, listener)
  • "change"

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

rstudio/crosstalk documentation built on Jan. 9, 2025, 8:29 p.m.