Advanced Filters: update README
This commit is contained in:
Paul Sealock
parent
4bc8c82820
commit
76bf741fc9
|
|
@ -1,73 +1,105 @@
|
|||
Advanced Filters
|
||||
============
|
||||
|
||||
Displays a configurable set of filters which can modify query parameters.
|
||||
Displays a configurable set of filters which can modify query parameters. Display, behavior, and types of filters can be designated by a configuration object.
|
||||
|
||||
## How to use:
|
||||
## Example Config
|
||||
|
||||
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
|
||||
import AdvancedFilters from 'components/advanced-filters';
|
||||
|
||||
filters = {
|
||||
status: {
|
||||
label: __( 'Order Status', 'wc-admin' ),
|
||||
addLabel: __( 'Order Status', 'wc-admin' ),
|
||||
rules: [
|
||||
{ value: 'is', label: __( 'Is', 'wc-admin' ) },
|
||||
{ value: 'is-not', label: __( 'Is Not', 'wc-admin' ) },
|
||||
],
|
||||
input: {
|
||||
component: 'SelectControl',
|
||||
options: [
|
||||
{ value: 'pending', label: __( 'Pending', 'wc-admin' ) },
|
||||
{ value: 'processing', label: __( 'Processing', 'wc-admin' ) },
|
||||
{ value: 'on-hold', label: __( 'On Hold', 'wc-admin' ) },
|
||||
const config = {
|
||||
title: _x(
|
||||
'Orders Match {{select /}} Filters',
|
||||
'A sentence describing filters for Orders. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ',
|
||||
'wc-admin'
|
||||
),
|
||||
filters: {
|
||||
status: {
|
||||
labels: {
|
||||
add: __( 'Order Status', 'wc-admin' ),
|
||||
remove: __( 'Remove order status filter', 'wc-admin' ),
|
||||
rule: __( 'Select an order status filter match', 'wc-admin' ),
|
||||
/* translators: A sentence describing an Order Status filter. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ */
|
||||
title: __( 'Order Status {{rule /}} {{filter /}}', 'wc-admin' ),
|
||||
filter: __( 'Select an order status', 'wc-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 */
|
||||
label: _x( 'Is', 'order status', 'wc-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 */
|
||||
label: _x( 'Is Not', 'order status', 'wc-admin' ),
|
||||
},
|
||||
],
|
||||
input: {
|
||||
component: 'SelectControl',
|
||||
options: Object.keys( orderStatuses ).map( key => ( {
|
||||
value: key,
|
||||
label: orderStatuses[ key ],
|
||||
} ) ),
|
||||
},
|
||||
},
|
||||
},
|
||||
product: {
|
||||
label: __( 'Product', 'wc-admin' ),
|
||||
addLabel: __( 'Products', 'wc-admin' ),
|
||||
rules: [
|
||||
{ value: 'includes', label: __( 'Includes', 'wc-admin' ) },
|
||||
{ value: 'excludes', label: __( 'Excludes', 'wc-admin' ) },
|
||||
{ value: 'is', label: __( 'Is', 'wc-admin' ) },
|
||||
{ value: 'is-not', label: __( 'Is Not', 'wc-admin' ) },
|
||||
],
|
||||
input: {
|
||||
component: 'FormTokenField',
|
||||
},
|
||||
},
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
render: function() {
|
||||
return (
|
||||
<AdvancedFilters config={ filters } />
|
||||
);
|
||||
## 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' },
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
`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,
|
||||
} ) ),
|
||||
}
|
||||
```
|
||||
|
||||
`type`: A string Autocompleter type used by the [Search Component](https://github.com/woocommerce/wc-admin/tree/master/client/components/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.
|
||||
|
||||
### Numerical Value
|
||||
under development.
|
||||
|
||||
### Numerical Range
|
||||
under development.
|
||||
|
||||
## AdvancedFilters Props
|
||||
|
||||
* `config` (required): The configuration object required to render filters
|
||||
* `filterTitle` (required): Name of this filter, used in translations
|
||||
* `path` (required): The `path` parameter supplied by React-Router
|
||||
* `query`: The query string represented in object form
|
||||
|
||||
## config object jsDoc
|
||||
|
||||
```js
|
||||
/**
|
||||
* @type filterConfig {{
|
||||
* key: {
|
||||
* label: {string},
|
||||
* addLabel: {string},
|
||||
* rules: [{{ value:{string}, label:{string} }}],
|
||||
* input: {
|
||||
* component: {string},
|
||||
* [options]: [*]
|
||||
* },
|
||||
* }
|
||||
* }}
|
||||
*/
|
||||
```
|
||||
* `query`: The url query string represented in object form
|
||||
|
|
|
|||
Loading…
Reference in New Issue