Finish documentation for AdvancedFilters component.
This commit is contained in:
Jeff Stieler
parent
74330ef8f4
commit
bf37c30b16
|
|
@ -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,17 +51,36 @@ 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: {
|
||||
```js
|
||||
const config = {
|
||||
...,
|
||||
filters: {
|
||||
fruit: {
|
||||
input: {
|
||||
component: 'SelectControl',
|
||||
options: [
|
||||
{ label: 'Apples', key: 'apples' },
|
||||
|
|
@ -63,43 +88,106 @@ input: {
|
|||
{ 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: {
|
||||
```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.
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
|
|
|
|||
Loading…
Reference in New Issue