From bf37c30b16f897786109477d5a89d8a77c5b6884 Mon Sep 17 00:00:00 2001 From: Jeff Stieler Date: Tue, 3 Sep 2019 12:35:49 -0700 Subject: [PATCH] Finish documentation for AdvancedFilters component. --- .../components/src/advanced-filters/README.md | 166 ++++++++++++++---- .../src/advanced-filters/docs/example.js | 4 +- 2 files changed, 130 insertions(+), 40 deletions(-) diff --git a/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md b/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md index b3f48e0c565..3696e931937 100644 --- a/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md +++ b/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md @@ -1,17 +1,18 @@ Advanced Filters -============ +=== Displays a configurable set of filters which can modify query parameters. Display, behavior, and types of filters can be designated by a configuration object. -## Example Config +## Usage Below is a config example complete with translation strings. Advanced Filters makes use of [interpolateComponents](https://github.com/Automattic/interpolate-components#readme) to organize sentence structure, resulting in a filter visually represented as a sentence fragment in any language. -```jsx +```js const config = { - title: _x( + title: __( + // A sentence describing filters for Orders + // See screen shot for context: https://cloudup.com/cSsUY9VeCVJ 'Orders Match {{select /}} Filters', - 'A sentence describing filters for Orders. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ', 'woocommerce-admin' ), filters: { @@ -20,19 +21,24 @@ const config = { add: __( 'Order Status', 'woocommerce-admin' ), remove: __( 'Remove order status filter', 'woocommerce-admin' ), rule: __( 'Select an order status filter match', 'woocommerce-admin' ), - /* translators: A sentence describing an Order Status filter. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ */ + // A sentence describing an Order Status filter + // See screen shot for context: https://cloudup.com/cSsUY9VeCVJ title: __( 'Order Status {{rule /}} {{filter /}}', 'woocommerce-admin' ), filter: __( 'Select an order status', 'woocommerce-admin' ), }, rules: [ { value: 'is', - /* translators: Sentence fragment, logical, "Is" refers to searching for orders matching a chosen order status. Screenshot for context: https://cloudup.com/cSsUY9VeCVJ */ + // Sentence fragment, logical, "Is" + // Refers to searching for orders matching a chosen order status + // Screenshot for context: https://cloudup.com/cSsUY9VeCVJ label: _x( 'Is', 'order status', 'woocommerce-admin' ), }, { value: 'is_not', - /* translators: Sentence fragment, logical, "Is Not" refers to searching for orders that don\'t match a chosen order status. Screenshot for context: https://cloudup.com/cSsUY9VeCVJ */ + // Sentence fragment, logical, "Is Not" + // Refers to searching for orders that don't match a chosen order status + // Screenshot for context: https://cloudup.com/cSsUY9VeCVJ label: _x( 'Is Not', 'order status', 'woocommerce-admin' ), }, ], @@ -45,61 +51,143 @@ const config = { }, }, }, - }; +}; ``` +When filters are applied, the query string will be modified using a combination of rule names and selected filter values. + +Taking the above configuration as an example, applying the filter will result in a query parameter like `status_is=pending` or `status_is_not=cancelled`. + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`config` | Object | `null` | (required) The configuration object required to render filters. See example above. +`path` | String | `null` | (required) Name of this filter, used in translations. +`query` | Object | `null` | The query string represented in object form. +`onAdvancedFilterAction` | Function | `null` | Function to be called after an advanced filter action has been taken. + + ## Input Components + ### SelectControl Render a select component with options. -```jsx -input: { - component: 'SelectControl', - options: [ - { label: 'Apples', key: 'apples' }, - { label: 'Oranges', key: 'oranges' }, - { label: 'Bananas', key: 'bananas' }, - { label: 'Cherries', key: 'cherries' }, - ], -} +```js +const config = { + ..., + filters: { + fruit: { + input: { + component: 'SelectControl', + options: [ + { label: 'Apples', key: 'apples' }, + { label: 'Oranges', key: 'oranges' }, + { label: 'Bananas', key: 'bananas' }, + { label: 'Cherries', key: 'cherries' }, + ], + }, + }, + }, +}; ``` `options`: An array of objects with `key` and `label` properties. + ### Search Render an input for users to search and select using an autocomplete. -```jsx -input: { - component: 'Search', - type: 'products', - getLabels: getRequestByIdString( NAMESPACE + 'products', product => ( { - id: product.id, - label: product.name, - } ) ), -} +```js +const config = { + ..., + filters: { + product: { + input: { + component: 'Search', + type: 'products', + getLabels: getRequestByIdString( NAMESPACE + 'products', product => ( { + id: product.id, + label: product.name, + } ) ), + }, + }, + }, +}; ``` `type`: A string Autocompleter type used by the [Search Component](https://github.com/woocommerce/woocommerce-admin/tree/master/packages/components/src/search). `getLabels`: A function returning a Promise resolving to an array of objects with `id` and `label` properties. + ### Date -under development. -### Date Range -under development. +Renders an input or two inputs allowing a user to filter based on a date value or range of values. -### Numerical Value -under development. +```js +const config = { + ..., + filters: { + registered: { + rules: [ + { + value: 'before', + label: __( 'Before', 'woocommerce-admin' ), + }, + { + value: 'after', + label: __( 'After', 'woocommerce-admin' ), + }, + { + value: 'between', + label: __( 'Between', 'woocommerce-admin' ), + }, + ], + input: { + component: 'Date', + }, + }, + }, +}; +``` -### Numerical Range -under development. -## AdvancedFilters Props +### Numeric Value -* `config` (required): The configuration object required to render filters -* `path` (required): The `path` parameter supplied by React-Router -* `query`: The url query string represented in object form +Renders an input or two inputs allowing a user to filter based on a numeric value or range of values. Can also render inputs for currency values. + +Valid rule values are `after`, `before`, and `between`. Use any combination you'd like. + +```js +const config = { + ..., + filters: { + quantity: { + rules: [ + { + value: 'lessthan', + label: __( 'Less Than', 'woocommerce-admin' ), + }, + { + value: 'morethan', + label: __( 'More Than', 'woocommerce-admin' ), + }, + { + value: 'between', + label: __( 'Between', 'woocommerce-admin' ), + }, + ], + input: { + component: 'Number', + }, + }, + }, +}; +``` + +Valid rule values are `lessthan`, `morethan`, and `between`. Use any combination you'd like. + +Specify `input.type` as `'currency'` if you'd like to render currency inputs, which respects store currency locale. diff --git a/plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js b/plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js index f73ae297ea4..ec408d5b1d8 100644 --- a/plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js +++ b/plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js @@ -6,7 +6,9 @@ import { AdvancedFilters } from '@woocommerce/components'; const { orderStatuses } = wcSettings; const path = ( new URL( document.location ) ).searchParams.get( 'path' ) || '/devdocs'; -const query = {}; +const query = { + component: 'advanced-filters', +}; const advancedFilters = { title: 'Orders Match {{select /}} Filters',