Available React Hooks#

The following React hooks are available for use:

useCollection#

useCollection(collection, isEmpty, serializer, additionalDeps)

This hook attaches a Backbone collection to a React state and returns a serialized collection object together with loading and isError collection states.

Arguments:

  1. Collection - Backbone collection object

  2. isEmpty - Custom function that will determine if the collection is empty. Most of the time you can just check if collection.length === 0, but sometimes you may need to do additional things depending on the use case.

  3. Serializer - Optional serializer function. If it’s not passed collection will be serialized with collection.toJSON()

  4. additionalDeps - Additional useEffect dependencies that will trigger collection refetch on change. By default, the only dependency is the dashboard state object, but you can pass additional ones if needed.

useWidgetCollection#

useWidgetCollection(wodgetProps, collection, isEmpty, serializer, additionalDeps)

This hook attaches a Backbone collection to a React state and returns an object with all properties needed for a widget. You can use this hook when setting up the main collection for the widget.

It uses the useCollection hook but also adds additional data and structure that helps with passing properties to widget containers and the widgets themselves.

Arguments:

  1. wodgetProps - An object representing widget properties to be passed down.

  2. Collection: Backbone collection object

  3. isEmpty: Custom function determining if the collection is empty. Mostly, you can check if collection.length === 0, though sometimes additional configuration is needed depending on the use case.

  4. Serializer: Optional serializer function. If not passed, then collection will be serialized with collection.toJSON()

  5. additionalDeps: Additional useEffect dependencies that trigger collection refetch on change. By default, the only dependency is the dashboard state object, though you can pass additional ones if needed.

useDrilldown#

useDrilldown(search, widgetModel)

This hook drills down the dashboards by adding queries and facets to dashboard state and widget selection. When called, it will return the four drill-down functions documented below.

Arguments:

  1. search: Dashboard state object available in the widget props or Global variable.

  2. widgetModel: Widget configuration model available in the props and context of the widget.

Example: const { addFacetValue, removeFacetValue, clearSelection, removeQueryFromSelection,  } = useDrilldown(dashboardState, widgetModel);

Functions#

The following functions are returned by useDrilldown:

addFacetValue#

addFacetValue(facet, value)

This hook adds a facet or query to the dashboard state and widget selection. If only a value is provided, it will add that value as a query. If both are provided, it will add a facet-value pair.

Arguments:

  1. Facet: A string representing a facet.

  2. Value: A string representing a facet value, or query if the facet is empty.

Example:

const { addFacetValue } = useDrilldown(props.dashboardState, props.widgetModel);
addFacetValue('source', props.sources[0]?.id);

removeFacetValue#

removeFacetValue(facet, value, silent)

This hook removes a facet or query from the dashboard state and widget selection. If only a value is provided, it will remove that value as a query. If both are provided, it will remove the identified facet-value pair.

Arguments:

  1. Facet: A string representing a facet.

  2. Value: A string representing a facet value, or query if the facet is empty.

  3. Silent: If true, the function call will not trigger any events.

removeFacetValue#

clearSelection() will remove the full selection for the current widget model from both the dashboard and widget selections. There are no arguments.

removeQueryFromSelection#

removeQueryFromSelection(silent)

This hook will remove the first selection for the current widget model from both the dashboard and widget selections.

Argument:

Silent: if true, the function call will not trigger any events.

useContainerDimensions#

useContainerDimensions(ref) This hook will return the width and the height of an HTML element.

Dimensions are updated on load, on mount/un-mount, when resizing the window, and when the ref changes.

Argument:

Ref: React ref object representing html element. For more information, see the Refs and the DOM reference page.

Example:

const elementRef = React.useRef(null);
const { containerWidth, containerHeight } = useContainerDimensions(carouselRef);
return <SomeComponent ref={elementRef}>