ApplyFacetsProvider

The ApplyFacetsProvider component wraps facet forms and provides the necessary context for interacting with facet widgets. With the component, you can:

• Assign "Apply All" and "Reset All" buttons for managing facet selections

• Automatically generate faceted search based on the facets returned in /v1/search results

• Expose context for programmatic control of wrapped facet widgets

Assign action buttons

By wrapping one or more facet widgets with ApplyFacetsProvider, you can assign "Apply All" and "Reset All" buttons to the wrapped widgets using the ApplyFacetsProps. (No ref values for the widgets are necessary as they are when you are using the ApplyFacets widget. The refs are created and managed internally.)

Here’s an example:

<ApplyFacetsProvider
  ApplyFacetsProps={{
    clearAllConfig: {},
    location: "bottom"
  }}
>
  <StringFacet
    title="Party"
    name="party"
    data={context.searchResponse?.facets?.party}
    onSelect={handleFacetClick}
    resetConfig={{}}
  />
  <DateRangeFacet
    title="Birthdate"
    name="dob"
    data={context.searchResponse?.facets?.dob}
    value={valueDateFacet}
    MaxInputConfig={{
      props: { label: 'End' }
    }}
    MinInputConfig={{
      props: { label: 'Start' }
    }}
    onSelect={selectDateRange}
    onReset={resetDateRange}
    resetConfig={{}}
  />
</ApplyFacetsProvider>

Since the StringFacet and DateRangeFacet widgets are wrapped by ApplyFacetsProvider, they are controlled by the "Reset All" button being configured in ApplyFacetsProps. Clicking the "Reset All" button resets the widgets to their initial state.

This is rendered:

See the ApplyFacets widget documentation for more about the widget action buttons.

Automatically generate faceted search

The ApplyFacetsProvider widget can automatically generate a set of facet widgets based on the results returned from MarkLogic /v1/search. The feature is configured with the BuilderConfig prop.

The widget will display facet widgets in the UI based on the facet types found in the data prop of BuilderConfig.

Consider a search application with this /v1/search results payload:

{
    "snippet-format": "snippet",
    "total": 3,
    "start": 1,
    "page-length": 10,
    "selected": "include",
    "results": [
        // Results objects
    ],
    "facets": {
        "party": {
            "type": "xs:string",
            "facetValues": [
                {
                    "name": "Democratic",
                    "count": 1,
                    "value": "Democratic"
                },
                {
                    "name": "Democratic-Republican",
                    "count": 1,
                    "value": "Republican"
                },
                {
                    "name": "Federalist",
                    "count": 1,
                    "value": "Democratic"
                }
            ]
        },
        "dob": {
            "type": "xs:date",
            "facetValues": [
                {
                    "name": "1911-02-06",
                    "count": 1,
                    "value": "1911-02-06"
                },
                {
                    "name": "1913-01-09",
                    "count": 1,
                    "value": "1913-01-09"
                }
            ]
        }
    },
    // Etc.
}

This payload includes party and dob facets. You can include the ApplyFacetsProvider in your React application to dynamically display facet widgets based on that payload:

const context = useContext(MarkLogicContext);

// ...

<ApplyFacetsProvider
  BuilderConfig={{
    data: context.searchResponse?.facets,
    useMarkLogicContext: {
      applySearchOnChange: true
    }
  }}
/>

A StringFacet widget and DateRangeFacet widget are displayed in the UI:

The application will use MarkLogicContext for managing facet state and update search results with each facet selection.

You can set additional props to customize the faceting display and behavior. For example, you can include the ApplyFacetsProps to display buttons to support multi-select of the facets.

<ApplyFacetsProvider
  ApplyFacetsProps={{
    applyAllConfig: {},
    clearAllConfig: {},
    location: "top",
  }}
  BuilderConfig={{
    data: context.searchResponse?.facets,
    useMarkLogicContext: {
      applySearchOnChange: false
    },
    order: {
      dob: 1,
      party: 2
    },
    overrides: {
      dob: {
        type: 'xs:date',
        props: {
          title: 'Date of Birth',
          MinInputConfig: {
            type: "input",
            props: {
              label: "Start",
              min: new Date(1700, 0, 1),
              defaultValue: new Date(1700, 0, 1)
            },
          },
          MaxInputConfig: {
            type: "input",
            props: {
              label: "End",
              max: new Date(2000, 11, 31),
              defaultValue: new Date(2000, 11, 31)
            },
          },
          resetConfig: {
            label: "Reset Dates",
            onReset: () => {
              context.updateSearch()
            }
          }
        },
      }
    }
  }}
/>

These ApplyFacetsProps settings will display "Apply All" and "Reset All" buttons. Users of the application can make multiple facet selections before applying those selections with the "Apply All" button. The "Reset All" button resets the widgets. (See the ApplyFacets documentation for details on the action buttons.)

Note: For multi-select to function correctly, you will also need to set the disableSearchOnChange prop to true in your application’s MarkLogicProvider.

The ApplyFacetsProps.location prop controls where the action buttons are rendered relative to the facet list. Valid values are 'top', 'bottom', 'both', or 'none'.

In the code in this section, the order prop controls the display order of the facets in the UI. The overrides prop allows you to customize the generated widgets. Each entry in overrides requires a type field (matching the facet type string, e.g. 'xs:date') and a props object with the widget props to override. In this example, the DateRangeFacet widget is customized, changing the title displayed in the UI and setting default start and end values. See the documentation for the different facet widgets and what overrides are available.

Additional BuilderConfig props:

• onChange — Callback triggered whenever a facet selection changes. Receives a dictionary of the current selections keyed by facet name.

• ignore — An array of facet names to exclude from the auto-generated UI. Useful for hiding internal or system facets that should not be displayed to users.

• hideWhenEmpty — When true, facet widgets with no facetValues are not rendered. Can also be an object with an except array listing facet names that should always be rendered even when empty (e.g. { except: ['alwaysVisible'] }).

The code renders:

Expose context for programmatic control

The ApplyFacetsProvider exposes a number of context methods for controlling the facet widgets. To access the context, use the useApplyFacetsContext hook within any child component:

import React from 'react';
import { useApplyFacetsContext } from 'ml-fasttrack';

const MyComponent = () => {
  const { facetRefs } = useApplyFacetsContext();

  // Use facetRefs as needed
  return <div>{JSON.stringify(facetRefs)}</div>;
};

export default MyComponent;

Important notes

• Ensure that useApplyFacetsContext is called within a component that is a descendant of ApplyFacetsProvider. If not, it will throw an error.

• The facetRefs object contains direct references to each of the Facet components within the provider. This allows for easy interaction with the components. For details on the context methods available, see Setting and resetting facet widgets.