Filterbar

Description

WuiVue's <wui-filterbar> component is a flexible filterbar with built-in filter panels like single or multi-select or user input filters like number or text inputs. The filtbar also provides searchbar filter options if the searchbar prop is set. Other features are support for options provider functions (remote search for filter options), slots for custom filter panels, and keyboard support.

Example: Basic usage

<template>
  <div>
    <wui-filterbar :filters="filters" @update="handleFilterUpdate" />
  </div>
</template>

<script>
  export default {
    data() {
      return {
        filters: [
          {
            // The key must be unique
            key: "status",
            // Translated label to display
            label: "Status",
            // Predicate editor config
            predicate: {
              // Multi-select filter (list of checkboxes)
              type: "MULTI_SELECT",
              // Here you define your options the user can choose from
              options: [
                { value: "DRAFT", text: "Draft" },
                { value: "PENDING", text: "Pending" },
              ],
              // Whether or not a comparison operator selectbox should be displayed
              // Boolean or String with operator category set (see section "Comparison operator types")
              // Possible operator types: "NUMERIC", "STRING_SHORT", "STRING_LONG"
              operator: true,
              // Displays a search input field at te top of the predicate editor
              // Usefull if you show many options
              searchbar: true,
            },
            // Whether or not the filter can be chosen only once or multiple times
            once: true,
          },
          {
            key: "creditor",
            label: "Creditor",
            predicate: {
              type: "MULTI_SELECT",
              // Options provider function
              options: this.creditorsOptionsProvider,
              // Will display a searchbar
              searchbar: true,
            },
            once: true,
          },
          {
            key: "creation_date",
            label: "Creation date",
            predicate: {
              // Singel select filter (list of radio buttons)
              type: "SINGLE_SELECT",
              options: [
                { text: "Last 7 days", value: "LAST_7_DAYS" },
                { text: "Last 30 days", value: "LAST_30_DAYS" },
                { text: "Last 90 days", value: "LAST_90_DAYS" },
              ],
            },
            once: true,
          },
          {
            key: "name",
            label: "Name",
            predicate: {
              // Renderst a text input field incl. select for string comparison operators
              type: "STRING",
            },
          },
          {
            key: "price",
            label: "Price",
            predicate: {
              // Renders an input field with currency symbol at the end
              // incl. select for numeric operators
              type: "MONEY",
              currencyCode: "EUR",
              currencySymbol: "€",
            },
          },
          {
            key: "number_of_items",
            label: "Number items",
            predicate: {
              // Renders an input field for numbers with currency symbol at the end
              // incl. select for numeric operators
              type: "NUMBER",
            },
          },
          {
            key: "filled_out_pc",
            label: "A value in %",
            predicate: {
              // Renders an input field for numbers with percentage symbol at the end
              // incl. select for numeric operators
              type: "PERCENT",
            },
          },
        ],
      };
    },
    methods: {
      async creditorsOptionsProvider() {
        await Promise.resolve([
          { value: "creditor_1", text: "Creditor 1" },
          { value: "creditor_2", text: "Creditor 2" },
        ]);
      },
      handleFilterUpdate(selectedFilters) {
        console.log("handleFilterUpdate, selectedFilters: ", selectedFilters);
      },
    },
  };
</script>

<!-- wui-filterbar.vue -->

Filters configuration

filters is the filters data in an array format, where each filter configuration is a filter category the user can choose. Example format:

const filters = [
  {
    // The key must be unique
    key: "status",
    // Translated label to display
    label: "Status",
    // Predicate editor config (the popup where the user can choose an option or enter custom values, see configuration options below)
    predicate: {},
    // Whether or not the filter can be chosen only once or multiple times
    once: true,
  },
];

<wui-filterbar> automatically samples the key props to extract filter nameslabels if no label prop is set. Filter names names are automatically "humanized" by converting kebab-case, snake_case, and camelCase to individual words and capitalizes each word. Example conversions:

• buying_channel becomes Buying Channel
• buying-channel becomes Buying Channel
• status becomes Status
• PRICE remains PRICE
• hasRestrictions becomes Has Restrictions

These filter names will be displayed in the filter suggest dropdown menu (in the order they appear in the filters array) and in the header of the predicate editor popup.

Predicate editor configuration

The predicate editor appears once the user selects a filter category from the filter suggest menu, or when she clicks on a filter chip with her selected filter options. The editor will be configured via the filter's property predicate.

Example configuration with all options

const predicate = {
  // Mandatory, possible options see below
  type: "MULTI_SELECT"
  // Only mandatory when 'type' is 'MULTI_SELECT' or 'SINGLE_SELECT', otherwise will be ignored
  // Can be an array or a function reference (see below)
  options: [
    {
      value: "DRAFT",
      text: "Draft"
    }
  ],
  // Optionally, you can customize the list item output by using a formatter callback function.
  // Only applicable if `type` is `SINGLE_SELECT` or `MULTI_SELECT`
  formatter: (text, value, option) => `${text} (insert_number_of_hits_here)})`
  // Whether or not the operator selectbox will be shown
  // Boolean or String with operator category set (see below)
  // Possible operator types: "NUMERIC", "STRING_SHORT", "STRING_LONG"
  operator: true,
  // Whether or not a search input field for searching filter options is shown in the predicate editor
  // Only available when 'type' is 'MULTI_SELECT' or 'SINGLE_SELECT', otherwise will be ignored
  searchbar: false
  // Only mandatory when 'type' is set to 'MONEY'
  currencyCode: "EUR",
  currencySymbol: "€",
}

Predicate editor types

The predicate.type property is mandatory, the following types are available:

Options based editors

• SINGLE_SELECT - a list of options rendered as radio inputs
• MULTI_SELECT - a list of options rendered as checkbox inputs

User input based editors

• STRING - renders a text input with string comparison operators selectbox
• NUMBER - renders a text input with numeric comparison operators selectbox
• MONEY - renders a text input with currency symbol at the end and a numeric comparison operators selectbox
• PERCENT - renders a text input with percentage symbol at the end and a numeric comparison operators selectbox

The biggest difference between option-based editor types and user input types is that with type SINGLE_SELECT or MULTI_SELECT you also have to pass the filter options via the options prop.

Filter options

There are two ways to provide filter options the user can choose from. Either by passing an array to the options prop or by passing a function reference (see "Using options provider function" below).

Because the filterbar uses wui-form-checkbox or wui-form-radio under the hood, all fields of the options array are supported:

• value The selected value which will be set on v-model
• disabled Disables item for selection
• text Display text, or html Display basic inline html

If both html and text are provided, html will take precedence. Only basic/native HTML is supported in the html field (components will not work, use scoped slots for that).

Example: options based filter using an Array

const options = [
  { value: "value_1", text: "Value 1" },
  { value: "value_2", text: "Value 2", disabled: true },
  { value: { v: "value_3" }, text: "Value 3" },
  { value: "value_4", html: "<strong>Value 4</strong>" },
];

If searchbar is set to true, a search input field is rendered and the user will be able to search for options in your predicate.options Array.

Infinite scrolling

With SINGLE_SELECT or MULTI_SELECT a maximum of 20 options are displayed. If more than 20 options are passed through, the predicate editor automatically activates infinite scrolling.

Example 1 - providing an array with 50 options

You have an array with 50 options:

const options = {
  options: [
    { value: "value_1", text: "Value 1" },
    //  ... all other 48 options go here
    { value: "value_50", text: "Value 50" },
  ],
};

Once the predicate editor opens, only the first 20 options are shown to the user (only 20 items are rendered in HTML). As soon as the user starts scrolling and gets to the end of the list, another 10 options from the already existing options array are rendered and displayed.

Example 2 - using a provider function

Instead of an array, you use a provider function, which returns an array of 1000 options.

const options = {
  options: (ctx) => {
    // Sample function that makes an API call and returns 1000 items
    // return [...1000 items]
  },
};

As in example 1, only the first 20 options are displayed here. As soon as the user starts scrolling and gets to the end of the list, another 10 options from the already existing array are displayed.

Note: the provider function is not called again on infinite scrolling as long as the predicate editor is open. The provider function is only called when the predicate editor opens or the user changes the search term.

Important note

The predicate.options array is not reactive by purpose, which means that later changes in the filters[].predicate.options object do not affect the display and status of filters and filter options in the filterbar. To provide reactive filter options, use an options provider function instead (see below).

Searching filter options

Filter options can be searched/filtered by the user if you set the prop predicate.searchbar of the desired filter to true. This will render a search input field in the predicate editor of the filter.

The built-in search has no effect if an options provider function is specified instead of an array of options. The entered query string by the user is passed to your provider function as a context parameter.

Optional placeholder text for searchbar

You can customize the value of the placeholder attribute by passing an Object instead of a Boolean via the searchbar prop:

const predicate: {
  type: "MULTI_SELECT",
  options: [{ value: "val_1", text: "Val 1" }],
  searchbar: {
    placeholder: "My custom placeholder text"
  }
}

Using options provider function

As mentioned, it is possible to use a function to provide the filter options, by specifying a function reference via the filters[].predicate.options prop.

The provider function is called with the following signature:

provider(ctx, [callback]);

The ctx is the context object associated with the filter's state, and contains the following properties:

The second argument callback is an optional parameter for when using the callback asynchronous method.

Example: returning an array of filter options (synchronous):

function myProvider() {
  let items = [];

  // Perform any items processing needed

  // Must return an array
  return items || [];
}

Example: Using callback to return data (asynchronous):

function myProvider(ctx, callback) {
  const params = "?query=" + ctx.query;

  this.fetchData("/some/url" + params)
    .then((data) => {
      // Pluck the array of filter options off our axios response
      const options = data.options;
      // Provide the array of options to the callback
      callback(options);
    })
    .catch(() => {
      callback([]);
    });

  // Must return null or undefined to signal wui-filterbar that callback is being used
  return null;
}

Example: Using a Promise to return data (asynchronous):

function myProvider(ctx) {
  const promise = axios.get("/some/url?query=" + ctx.query);

  // Must return a promise that resolves to an array of filter options
  return promise.then((data) => {
    // Pluck the array of options off our axios response
    const options = data.options;
    // Must return an array of options or an empty array if an error occurred
    return options || [];
  });
}

Example: Using an async function (semi-synchronous):

async function myProvider(ctx) {
  try {
    const response = await axios.get(`/some/url?query=${ctx.query}`);
    return response.items;
  } catch (error) {
    return [];
  }
}

Note: The options provider function is called every time the predicate editor opens.

Options provider filtering

By default, the options provider function is responsible for filtering the data, before passing it to the predicate editor for display.

The provider function is triggered as soon as the predicate editor gets mounted (usually when displayed to the user) as well as soon as the user enters a term in the search field in the predicate editor (predicate.searchbar must be set to true).

Comparison operator types

With the predicate parameter operator you can give users more options when filtering. If operator is set to true, a selectbox with pre-configured comparison operator choices for each filter type is displayed. The following comparison operators are available:

// Default for all numeric predicate editors ('NUMBER', 'MONEY', 'PERCENT')
const NUMERIC = [
  "GREATER_THAN",
  "GREATER_THAN_OR_EQUAL",
  "EQUAL",
  "UNEQUAL",
  "LESS_THAN",
  "LESS_THAN_OR_EQUAL",
];

// Default for 'STRING' predicate editor
const STRING_LONG = [
  "CONTAINS",
  "CONTAINS_NOT",
  "CONTAINS_CASE_SENSITIVE",
  "CONTAINS_NOT_CASE_SENSITIVE",
  "EQUALS",
  "STARTS_WITH",
];

// Onyl default for 'SINGLE_SELECT' and 'MULTI_SELECT' predicate editors when 'operator' is set to 'true', otherwhise no operator selectbox is rendered
const STRING_SHORT = ["CONTAINS", "CONTAINS_NOT"];

You can also specify one of the available operator categories to render a predefined set of operators.

Example filter configuration with a custom set comparison operator category

const filters = [
 {
   key: "status",
   label: "Status",
   predicate: {
     type: "MULTI_SELECT",
     options: [
       { value: "DRAFT", "Draft" },
       { value: "PENDING", "Pending" }
     ],
     // Will render a selectbox with a list of string based comparison operators (6 in total, see above)
     operator: "STRING_LONG"
   }
 }
]

For user-input-based predicate editors (predicate.type is set to NUMBER, MONEY, PERCENT and STRING), the operator selection is shown by default. You can hide the selectbox by setting operator to false.

Custom predicate editor

A custom predicate editor for each filter category is possible using scoped slots.

Scoped predicate editor slots

Scoped predicate editor slots give you the opportunity to build your own custom predicate editor for a particular filter. Scoped predicate editor slots use the following naming syntax: 'predicate(' + filter key + ')'.

Example: Custom predicate editor rendering with scoped slots

<template>
  <div>
    <wui-filterbar :filters="filters">
      <template #predicate(status)="{ predicate }">
        <strong>Your custom predicate editor for 'status' filter goes here.<strong><br />
        <button @click="predicate.updateModel([{ value: 'DRAFT_TEST', text: 'Draft Test' }])">
          Submit
        </button>
        Scoped props: <pre>{ predicate }</pre>
      </template>
    </wui-filterbar>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        filters: [
          {
            key: "status",
            label: "Status",
            predicate: {
              // Type is still mandatory
              type: "MULTI_SELECT",
              options: [
                { value: "DRAFT", text: "Draft" },
                { value: "PENDING", text: "Pending" },
              ],
            },
            once: true,
          },
        ],
      };
    },
  };
</script>

<!-- wui-filterbar-slots.vue -->

Example 2: Custom predicate editor - filter by restrictions

<template>
  <div>
    <wui-filterbar :filters="filters">
      <!-- We render our custom radio buttons in the `predicate-before(restrictions)` slot -->
      <!-- This slot has no overflow-y scroll -->
      <template #predicate-before(restrictions)="{ predicate }">
        <wui-form validated="state" class="border-b-1 p-x-15 p-y-10">
          <wui-form-group v-slot="{ ariaDescribedby }" class="m-b-0">
            <wui-form-radio-group
              id="hasRestriction"
              :aria-describedby="ariaDescribedby"
              name="hasRestriction"
              :checked="predicate.localModel"
              stacked
              @input="handleRestrictonsInput($event, predicate)"
            >
              <wui-form-radio
                key="with_restrictions"
                :value="[
                  {
                    value: 'with_restrictions',
                    text: 'Has country restrictions',
                  },
                ]"
                class="m-t-0"
                >Has country restrictions</wui-form-radio
              >
              <wui-form-radio
                key="without_restrictions"
                :value="[
                  {
                    value: 'without_restrictions',
                    text: 'Has no country restrictions',
                  },
                ]"
                class="m-b-0"
                >Has no country restrictions</wui-form-radio
              >
            </wui-form-radio-group>
          </wui-form-group>
        </wui-form>
      </template>
      <!-- Here we render the checkbox list of our filter options in the dedicated scoped slot `predicate(restrictions)` -->
      <!-- This list has `overflow-y: scoll` set -->
      <template #predicate(restrictions)="{ predicate }">
        <!-- We use the `wui-filter-editor-list` component here to have more control over the input events and the behaviour in conjunction with the radio buttons above -->
        <!-- The `getFilteredOptions` function filters out the values set by once of the radios above. Otherwise the editor list would render an addintional checkbox at the top with the value of one of the radios. -->
        <wui-filter-editor-list
          ref="editor-input"
          name="restrictions"
          :options="getFilteredOptions(predicate.filteredOptions)"
          type="MULTI_SELECT"
          :state="predicate.validationState"
          :errorMessage="predicate.errorMessage"
          :checked="predicate.localModel"
          @input="handleRestrictonsInput($event, predicate)"
        >
          <template #before>
            <p class="p-y-10">Or should match with:</p>
          </template>
        </wui-filter-editor-list>
      </template>
    </wui-filterbar>
  </div>
</template>

<script>
  const isEmptyArray = (value) =>
    !Boolean(Array.isArray(value) && value.length);

  export default {
    computed: {
      filters() {
        return [
          {
            key: "restrictions",
            label: "Restrictions by country",
            predicate: {
              type: "MULTI_SELECT",
              options: this.countriesOptionsProvider,
            },
            once: true,
          },
        ];
      },
    },
    methods: {
      // Our custom filter options provider function
      // Is called everytime the predicate editor opens, or
      // when the user enters a search term (only when `predicate.searchable` is set to `true`)
      async countriesOptionsProvider() {
        return await Promise.resolve(
          [
            { count: 2, text: "BE", value: "BE" },
            { count: 13710, text: "CH", value: "CH" },
            { count: 31343, text: "DE", value: "DE" },
          ].map((res) => ({
            value: res.value,
            text: `${res.text} (${res.count})`,
          }))
        );
      },
      // Remove custom filter options "with_restrictions" and "without_restrictions"
      // to prevent the rendering of an additional checkbox (because by default the predicate editor renders all selected options at the top of the list)
      getFilteredOptions(filteredOptions) {
        return filteredOptions.filter(
          (option) =>
            !["with_restrictions", "without_restrictions"].includes(
              get(option, "value.value", "")
            )
        );
      },
      // Our custom logic to handle user inputs whether from our custom radios
      // or from the checkbox list below
      // @values: Array with the current selected options
      // @predicate: the object from the scoped slot which contains the `updateModel` function we need to call
      handleRestrictonsInput(values, predicate) {
        if (isEmptyArray(values)) {
          return;
        }

        // Store the custom value object from one of our radio options
        const withOrWithoutRestrictionsObject = values.find(
          (res) =>
            res &&
            (get(res, "value") === "with_restrictions" ||
              get(res, "value") === "without_restrictions")
        );

        // Store the String "with_restrictions" or "without_restrictions"
        const withOrWithoutRestrictionsValue = get(
          withOrWithoutRestrictionsObject,
          "value"
        );

        // If either "with_restrictions" or "without_restrictions" is set
        // we update the model with the value from the radio button only.
        // This will overwrite any existing selected options from the checkbox list and
        // automatically uncheck all checkbox options.
        if (values.length === 1 && withOrWithoutRestrictionsValue) {
          predicate.updateModel([withOrWithoutRestrictionsObject]);
        } else {
          // The `values` Array contains at least one item from the checkbox list.
          // We filter out any set values from our custom radio buttons which automatically
          // makes them unselected.
          predicate.updateModel(
            values.filter(
              (option) =>
                !["with_restrictions", "without_restrictions"].includes(
                  get(option, "value", "")
                )
            )
          );
        }
      },
    },
  };
</script>

<!-- wui-filterbar-custom-predicate-editor.vue -->

The slot's scope variable (predicate in the above sample) will have the following properties:

Example: Custom predicate option items rendering with editor-option-item scoped slot

<template>
  <div>
    <wui-filterbar :filters="filters">
      <template #predicate-option-item(display_creator.id)="{ predicate }">
        <div
          class="display--flex align-items-center w-full text--left p-x-10 p-y-5"
        >
          <div class="flex-shrink-0" style="width: 15px">
            <wui-fa-icon
              v-if="predicate.optionItem.checked"
              :icon="['far', 'check']"
            />
          </div>
          <div class="flex-shrink-0 m-l-10">
            <img
              v-if="predicate.optionItem.image"
              class="img-circle"
              :src="predicate.optionItem.image"
              :alt="predicate.optionItem.text"
              style="width: 30px; height: 30px"
            />
            <user-image
              v-else
              :id="predicate.optionItem.value"
              class="img-circle"
              :alt="predicate.optionItem.text"
              style="width: 30px; height: 30px"
            />
          </div>
          <div class="flex-grow-1 m-l-10">{ predicate.optionItem.text }</div>
        </div>
      </template>
    </wui-filterbar>
  </div>
</template>

<script>
  const creators = [
    {
      value: "bb463b8b-b76c-4f6a-9726-65ab5730b69b",
      text: "Ron Dare",
      image:
        "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/104.jpg",
    },
    {
      value: "8b86a4d7-bb95-4b65-a553-34fac1c60627",
      text: "Jerry Hahn PhD",
      image:
        "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/532.jpg",
    },
    {
      value: "cebf8879-9145-476a-9e41-77f3869c17dc",
      text: "Johnnie Kemmer",
      image:
        "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/428.jpg",
    },
    {
      value: "0456bade-487a-449d-94a8-d215ce323793",
      text: "Miss Rochelle Cronin",
      image:
        "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/1148.jpg",
    },
  ];

  const UserImage = {
    props: {
      id: {
        type: [String, Number],
        required: true,
      },
    },
    data() {
      return {
        imageSrc: "",
      };
    },
    created() {
      this.getLink();
    },
    methods: {
      async getLink() {
        try {
          const creator = creators.find((creator) => creator.value === this.id)
          this.imageSrc = creator.image;
        } catch (error) {
          // eslint-disable-next-line no-console
          console.error("Error while finding creator by id: ", this.id);
          return "";
        }
      },
    },
    render(h) {
      return this.imageSrc ? h("img", { attrs: { src: this.imageSrc } }) : h();
    },
  };

  export default {
    components: {
      UserImage,
    },
    data() {
      filters: [
        {
          key: "creator",
          label: "Creator",
          predicate: {
            // Type is still mandatory
            type: "MULTI_SELECT",
            options: creators,
          },
          once: true,
        },
      ],
    },
  };
</script>

<!-- wui-filterbar-custom-option-items-scoped-slot.vue -->

The slot's scope variable (predicate in the above sample) will have the additional property optionItem amongst all the other previously mentioned props. The scope of optionItem is:

Force refreshing of filterbar

You may also trigger the refresh of the filters configuration and selected filters by calling the refresh() method on the filterbar reference

<div>
  <wui-filterbar ref="filterbar" ...></wui-filterbar>
</div>

this.$refs.filterbar.refresh();

Note: The refresh() method resets all filters already selected by the user. Furthermore, the props filters and initialSelected are read and set again. You should update these props before you call the refresh() method in case you want to provide a new filters configuration or initial selected filters.

Initial selected filter options

If you want the filter bar to show pre-selected filter options during initialization, you can pass the filters and set values with the initialSelected prop. Either as an Array or as a Function that returns an Array.

If a function is used, the Filterbar UI only becomes interactive once a result has been returned. During the loading process, the filter bar is in a "busy" state and only an empty box with no content is displayed.

Example using an Array

const initialSelected = [
  {
    key: "status",
    value: [
      { value: "DRAFT", text: "Draft" },
      { value: "PENDING", text: "Pending" },
    ],
  },
];

Example using an asynchronous function

async function getInitialSelected() {
  try {
    const response = await axios.get("/some/url");
    // Musst return an Array with one or more objects with the same Array shape as in the example above
    return response.items;
  } catch (error) {
    return [];
  }
}

const initialSelected = this.getInitialSelected;

Note: Initially set filters are only displayed if there is a corresponding filter configuration for key in the filters prop. In the examples above, there must be a filter configuration for status.

Component reference

<wui-filterbar>

Properties

Slots

Events

<wui-filterbar-menu-suggest-input>

Component aliases

<wui-filterbar-menu-suggest-input> can also be used via the following aliases:

• <wui-filter-menu-suggest-input>
• <wui-filter-menu-suggest>
• <wui-filter-suggest-input>

Properties

v-model

Events

Importing individual components

You can import individual components into your project via the following named exports:

Example

import { WuiFilterbar } from "@wui/wui-vue/lib/filterbar";
Vue.component("wui-filterbar", WuiFilterbar);

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Example

import { FilterbarPlugin } from "@wui/wui-vue/lib/filterbar";
Vue.use(FilterbarPlugin);