@bigbinary/neeto-filters v1.1.5

@bigbinary/neeto-filters

neetoFilters is the library that manages filters across neeto products.

Integrations

Installation

yarn add @bigbinary/neeto-filters

neetoFilters has a few peer dependencies that are required for the proper functioning of the package. Install all the peer dependencies using the below command:

yarn add @bigbinary/neeto-commons-frontend @bigbinary/neetoui @bigbinary/neeto-icons @honeybadger-io/react axios@0.27.2 classnames@2.3.1 dayjs@1.11.1 formik@2.2.0 mixpanel-browser@2.45.0 ramda@0.28.0 react-router-dom@5.3.0 react-router-nav-prompt@0.4.1 react-toastify@9.0.1 yup@0.32.11

Usage

1. NeetoFilters Component

import React from "react";

import Filters from "@bigbinary/neeto-filters";

import segmentsApi from "apis/segments";

const FilterComponent = ({ segment, loadTableContent }) => {
  const columns = [
    {
      node: "email",
      label: "Email Address",
      type: "text",
    },
    {
      node: "ticket",
      label: "Tickets",
      type: "number",
    },
    {
      node: "timezone",
      label: "Timezone",
      type: "timezone",
      inputType: "text"
      filters: ["is", "is_not", "greater_than", "less_than", "has_any_value", "is_unknown"],
    }
  ];

  const handleChange = payload => {
    loadTableContent(payload);
  };

  return (
    <Filters
      columns={columns}
      segment={segment}
      onChange={handleChange}
    />
  );
};

export default FilterComponent;

The types that are available by default are text, number, date, time, datetime, date_range, time_range, single_option, and multi_option. For adding types other than the default types, you can pass the filters prop along with the available logical filters as an array. You can change the input type for the filter by passing the inputType prop. By default the input type is text.

This is an example payload for the handleChange method. This will be passed on to the NeetoFilters::FilterService in the neeto-filters gem.

{
  "segment": {
    "id": "<uuid>",
    "name": "Backlog",
    "filters": [
      {
        "conditions": [
          {
            "node": "email",
            "label": "Email Address",
            "type": "text",
            "rule": "contains",
            "value": "bigbinary",
            "conditionsJoinType": "and"
          },
          {
            "node": "session",
            "label": "Sessions",
            "type": "number",
            "rule": "greater_than",
            "value": "10",
            "conditionsJoinType": "and"
          }
        ],
        "groupJoinType": "or"
      },
      {
        "conditions": [
          {
            "node": "ticket",
            "label": "Tickets",
            "type": "number",
            "rule": "greater_than",
            "value": "5",
            "conditionsJoinType": "and"
          }
        ],
        "groupJoinType": "and"
      }
    ]
  }
}

Handling combination of two columns

• Some columns like name are actually combination of two columns first_name and last_name. For this example, the node must be provided as "first_name,last_name". Here, both the nodes are separated by comma. On the Rails side, they will be separated by space by default.
• Note that this feature will not be supported for date_range and time_range types.

Props

1. columns: An array of objects that define the columns in which the filters need to be applied. It requires the following the following keys (The columns marked with * are required):

• node*: The name of the column in the entity table.
• label*: The label of the column that needs to be displayed in the Filters component.
• type*: The type of the column. It can be one of the following:
  • text: A text input.
  • number: A number input.
  • date: A date input.
  • time: A time input.
  • single_option: A single option select input.
  • multi_option: A multi option select input.
• inputType: If a new data type not in the above list needs to be added, you can pass the inputType prop along with the type prop. It can take the following values:
  • text: A text input.
  • number: A number input.
  • date: A date input.
  • time: A time input.
  • single_option: A single option select input.
  • multi_option: A multi option select input.
• filters: If a new data type not in the above list is added, you need to pass an array of strings that define the available logical filters for the column.
• hidden: If a column need not be shown in the dropdown, but should be filterable via the URL, pass a truthy value to the hidden prop.

2. onChange: A function that is called when the user updates the filters. It takes the segment as an argument.
3. hideActionButtons: A boolean that determines whether the action buttons (submit and delete) are hidden or not. It is set to true by default.
4. submitButtonProps: An object that defines the additional props for the submit button.
5. deleteButtonProps: An object that defines the additional props for the delete button.
6. segmentsEnabled: By default, neetoFilters calls the segments API to fetch all the stored segments. If neetoFilters is used without saving filters as segments, set the segmentsEnabled prop as false.

2. SegmentMenu Component

<MenuBar showMenu={isMenuBarOpen} title="Neeto Filters">
  <SegmentMenu entity="User" />
</MenuBar>

• The SegmentMenu component renders the list of all segments on the MenuBar. It provides the functionality of searching and managing the segments.
• It must only be used within the MenuBar component.
• It expects only one prop: entity. It is the name of the model on which the segments are defined on.

3. Controlling the filters programatically

• Filters can be programatically modified by updating the neeto-filters search param in the URL.
• For the example payload given above, the URL will be translated to:

  https://<base-url>/?neeto-filters=email-contains-bigbinary-text-and-session-greater_than-10-number-gor-ticket-greater_than-5-number

• The search param can be programatically built using the encodeFilters method exported by the package. It accepts the filters are argument and returns the search param associated with it.

• Here is a sample usage:

  const handleUpdateUrl = filters => {
    const searchParams = new URLSearchParams(window.location.search);
  
    if (searchParams.get("segmentId")) return;
  
    isEmpty(filters)
      ? searchParams.delete("neeto-filters")
      : searchParams.set("neeto-filters", encodeFilters(filters));
  
    history.push({ search: searchParams.toString() });
  };

• Similarly, there is a decodeFilters method which can be used to decode the URL and obtain the corresponding filters.

Development

Install all the dependencies by executing the following command

yarn install

Start the development server using the yarn start command.

In order to run the application you need to run the Rails server of the neetoFilters engine's dummy application as well. This is necessary to make sure that all the APIs and React Query hooks are working as per the requirement.

git clone https://github.com/bigbinary/neeto-filters-engine.git
./test/dummy/bin/setup
rails server

Building

The neetoFilters package gets auto-published to npm for every new merge to the master branch. You can checkout the publish workflow in git actions to get a live update.