npm package: @moderntribe/faceted-loops
Description: A react widget to render a loop of products with filters and pagination
Author: moderntribe
Latest version: 1.1.0

# Faceted Loops

[![NPM](https://img.shields.io/npm/v/@moderntribe/faceted-loops.svg)](https://www.npmjs.com/package/@moderntribe/faceted-loops) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
[![semantic-release](https://badgen.net/bundlephobia/minzip/@moderntribe/faceted-loops@latest)](https://bundlephobia.com/result?p=@moderntribe/faceted-loops@latest)



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


## Install

```bash
npm install --save @moderntribe/faceted-loops
```
or
```bash
yarn add @moderntribe/faceted-loops
```

## Usage

See the `example` folder for a full working example.

```jsx
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**.

```js
  {
    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

```js
[
  {
    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
```js
[
  {
    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
```js
{
  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

```js
{
  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.

```js
{
  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](https://github.com/moderntribe)