@moderntribe/faceted-loops

Faceted Loops

React hooks to fetch records with built-in filtering and pagination

Install

npm install --save @moderntribe/faceted-loops

or

yarn add @moderntribe/faceted-loops

Usage

See the example folder for a full working example.

import React, { Component } from 'react'
import { FacetedLoops } from '@moderntribe/faceted-loops'
import App from './App';

const INITIAL_DATA = {
  filters: [
    // ...
  ],
  records: [
    // ...
  ],
  meta: {
    // ...
  }
}

ReactDOM.render(
  <FacetedLoops initialData={INITIAL_DATA}>
    <App />
  </FacetedLoops>
, document.getElementById('root'))

Filters

Initially the widget will load the filters from a JavaScript object provided by backend. Once the filters or pagination are changed, the widget will request the filters (which must* be in the same format) from backend.

Every filter must have a unique ID and it's used to save the status of each filter in the url as query params.

  {
    type: 'search-box',
    id: "search-by-name",
    placeholder: 'Search here...'
  },
  {
    type: 'checkbox',
    id: 'coffee-tables',
    label: 'Coffee Tables',
    group: 'category'
  },
  {
    type: 'checkbox',
    id: 'lounge-chairs',
    label: 'Lounge Chairs',
    group: 'category'
  },

When a user type hello world in that search box, the url will change from tri.be to tri.be?search-by-name=hello%20world

Checkbox

[
  {
    type: 'checkbox',
    id: 'coffee-tables',
    label: 'Coffee tables',
    name: 'category'
    // group: "category"
  },
  {
    type: 'checkbox',
    id: 'chairs',
    label: 'Chairs',
    name: 'category'
    // group: "category"
  },
]

Examples of encoding:

• If a user doesn't select any: ?category= or nothing
• If a user select one: ?category=coffee-tables
• If a user select two: ?category=coffee-tables,chairs

Radio

[
  {
    type: 'radio-button',
    id: 'male',
    label: 'Male',
    name: 'gender'
    // group: "category"
  },
  {
    type: 'radio-button',
    id: 'female',
    label: 'Female',
    name: 'gender'
    // group: "category"
  }
]

Examples of encoding:

• If a user doesn't select any: ?gender= or nothing
• If a user select male: ?gender=male

Search box

{
  type: 'search-box',
  id: 'my-search-box',
  placeholder: 'Search by keyword',
  // group: "category"
}

Examples of encoding:

• If a user types 'Hello world': ?my-search-box=Hello%20world
• If a user types nothing: ?my-search-box= or nothing

Toggle

{
  type: 'toggle',
  id: 'in-stock',
  label: 'Coffee tables',
  // group: "category"
}

Examples of encoding:

• If a user toggle on: ?in-stock=1
• If a user toggle off: ?in-stock=0 or nothing

Records

These are the different items shown.

Initially the widget will load the records from a JavaScript object provided by backend. Once the filters or pagination are changed, the widget will request the records (which must be in the same format) from backend.

To get the new data, the widget uses the endpoint provided and adds the query params that the current route has. Eg:

• the endpoint is tri.be/wp-json/records
• the current route is tri.be?search-by-name=hello%20world
• the widget will get the data from tri.be/wp-json/records?search-by-name=hello%20world

Meta

Extra useful information that is received initially and in each request.

{
  pagination: {
    type: 'scroll', // 'scroll' | 'all' | 'paged'
    page: 1 // the current page number
    per_page: 5, // max number of records per page
    total_pages: 4
    total_results: 16, // number of records in the current page
  },
  groups: [ // extra information of the groups
    {
      id: 'category',
      label: 'Category'
    }
  ],
  endpoint: 'wp-json/my-endpoint', // API endpoint
  context: { // additional query parameters to pass
    extraParam: '1',
  }
}

Caveats

• The pagination type and the filters must be the same on every render

License

MIT © moderntribe