Available React Hooks

Available React Hooks#

This page describes the React hooks available for use. .. note:: The following React hooks are available under the Hooks object for use, e.g. Hooks.useCollection.

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.

useCollectionRecreate#

useCollectionRecreate = (getCollection, props, config)

This hook recreates a collection based on a change in the parameters.

Arguments:

  1. GetCollection: Function to get a collection with parameters.

  2. WidgetProps: An object representing widget properties to be passed down.

  3. Config: An object representing widget config to be passed down.

useWidgetCollection#

useWidgetCollection(widgetProps, 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. widgetProps - 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.

useCommunityTypesCollection#

useCommunityTypesCollection = (props, collection, isEmpty, dashboardSection, serializer)

This hook calls the useWidgetCollection hook and provides a list of additional methods and parameters specific to CommunityTypesCollection.

Additional return parameters:

  1. GetModelById: Function to get a CommunityType by ID.

  2. Total: Number of Community Types.

Arguments:

  1. WidgetProps: 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. DashboardSection: The widget section in the Dashboard.

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

useCommunityCollection#

useCommunityCollection = (props, collection, isEmpty, dashboardSection, serializer, additionalDeps)

This hook calls the useWidgetCollection hook and provides a list of additional methods and parameters specific to CommunityCollection.

Additional return parameters:

  1. GetModelById: Function to get a Community by ID.

  2. Total: Number of Communities.

  3. LoadNextPage: Function to load the Collection next page (pagination).

Arguments:

  1. WidgetProps: 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. DashboardSection: The widget section in the Dashboard.

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

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

useCommunitySubscriptionsCollection#

useCommunitySubscriptionsCollection = (props, collection, isEmpty, dashboardSection, serializer)

This hook calls the useWidgetCollection hook and provides a list of additional methods and parameters specific to CommunitySubscriptionsCollection.

Additional return parameters:

  1. GetModelById: Function to get a CommunitySubscription by ID.

  2. Total: Number of CommunitySubscriptions.

  3. LoadNextPage: Function to load the Collection next page (pagination).

  4. Create: Function to create a new CommunitySubscription.

  5. RefetchCollection: Function to refetch the Collection.

  6. BulkCreate: Function to create multiple CommunitySubscriptions.

Arguments:

  1. WidgetProps - 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. DashboardSection - The widget section in the Dashboard

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

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

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.

useFacetsCollection#

useFacetsCollection = (props, collection, isEmpty, dashboardSection, serializer)

This hook calls the useWidgetCollection hook and provides a list of additional methods and parameters specific to FacetsCollection.

Additional return parameters:

  1. GetModelById: Function to get a Facet by ID.

  2. Indexed: List of Indexed Facets.

Arguments:

  1. WidgetProps: 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. DashboardSection: The widget section in the Dashboard.

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

useFeedbackMode#

useFeedbackMode = (dashboard)

This hook tracks the FeedbackMode in a dashboard and returns the boolean representing the current mode and a setFeedbackMode function to change it.

Argument:

Dashboard: Dashboard model, available in all the widgets props.

useItemsCollection#

useItemsCollection = (props, collection, overrides, apiOverrides, dashboardSection,additionalDeps, isEmpty, serializer)

This hook calls the useWidgetCollection hook, attaches additional events, and provides a list of additional methods and parameters specific to ItemsCollection.

Additional return parameters:

  1. LoadNextPage: Function to load the Collection next page (pagination).

  2. ActiveItem: The current active Item.

  3. SetActiveItem: Function to set the active Item.

  4. GetActiveItem: Function to get the active Item.

  5. ActiveEntity: The current active Entity.

  6. SetActiveEntity: Function to set the active Entity.

  7. GetActiveEntity: Function to get the active Entity.

  8. GetExcelUrl: Function to get the Excel URL.

  9. GetModelById: Function to get an Item by ID.

  10. OnEntityClick: Function to be called when an Entity is clicked.

Arguments:

  1. WidgetProps: An object representing widget properties to be passed down.

  2. Collection: Backbone collection object.

  3. Overrides: Object containing all the Widget Component Overrides.

  4. ApiOverrides: Object containing all the Widget API Overrides.

  5. DashboardSection: The widget section in the Dashboard.

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

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

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

useQueryEvaluator#

useQueryEvaluator = (additionalQuery, dashboard, user, search)

This hook evaluates the query and attaches events to the Dashboard Store and returns it as a string.

Arguments: 1. AdditionalQuery: Additional widget query as a string. 2. Dashboard: Dashboard model available in all the widget props. 3. User: User model. 4. Search: Search model, available in all the widget props.

useStoreKeyChange#

useStoreKeyChange = (dashboard, storeKey, event)

This hook tracks a store key based on a given event and returns the value.

Arguments:

  1. Dashboard: Dashboard model, available in all the widgets props.

  2. StoreKey: A string representing the store key.

  3. Event: A string representing the event.

useStateWithCallback#

useStateWithCallback = (initialValue)

This hook saves a state value and returns the current value and a function to update the value and use a specified callback function.

Argument:

InitialValue: The initial value of the state, can be of any type.

Example:

const [value, setValueAndCallback] = useStateWithCallback('firstValue');
setValueAndCallback('secondValue', (prevValue, newValue) => console.log(`Previous value: ${prevValue}, New value: ${newValue}`));

useWithoutCollection#

useWithoutCollection = (widgetProps)

This hook acts similarly to useCollection but it doesn’t use a collection. It can be used for widgets without specified collections.

Argument:

WidgetProps: An object representing widget properties to be passed down.

usePrevious#

usePrevious = (value)

This hook tracks the previous value of a given one and returns it.

Argument:

Value: Mutating value of any kind.

Contents