Skip to content

Commit 3aeb0eb

Browse files
oandregaloandregal
authored
Field API: update docs for operators (WordPress#73523)
1 parent 9071a2a commit 3aeb0eb

File tree

2 files changed

+45
-29
lines changed

2 files changed

+45
-29
lines changed

‎packages/dataviews/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
- Documentation: document `readOnly`, `description`, and `placeholder` properties. [#73515](https://github.com/WordPress/gutenberg/pull/73515)
1919
- DataForm Panel Layout: Focus the first input element when the panel opens. [#72322](https://github.com/WordPress/gutenberg/pull/72322)
2020
- DataForm: Pattern validation is now supported on all fields that browsers support it in. [#73156](https://github.com/WordPress/gutenberg/pull/73156)
21+
- Documentation: improve operators docs. [#73523](https://github.com/WordPress/gutenberg/pull/73523)
2122

2223
### Bug fixes
2324

‎packages/dataviews/README.md‎

Lines changed: 44 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1705,7 +1705,7 @@ Configuration of the filters. Set to `false` to opt the field out of filtering
17051705
- Optional.
17061706
- If `false`, the field will not be available for filtering.
17071707
- If an object, it can have the following properties:
1708-
- `operators`: the list of operators supported by the field. See "operators" below. A filter will support the `isAny` and `isNone` multi-selection operators by default.
1708+
- `operators`: the list of operators supported by the field. See "operators" below.
17091709
- `isPrimary`: boolean, optional. Indicates if the filter is primary. A primary filter is always visible and is not listed in the "Add filter" component, except for the list layout where it behaves like a secondary filter.
17101710
17111711
By default, fields have filtering enabled by using the field's `Edit` function:
@@ -1798,34 +1798,49 @@ Or multi-selection operators:
17981798
17991799
The next table lists all available operators:
18001800
1801-
| Operator | Selection | Description | Example |
1802-
| -------------------- | -------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
1803-
| `is` | Single item | `EQUAL TO`. The item's field is equal to a single value. | Author is Admin |
1804-
| `isNot` | Single item | `NOT EQUAL TO`. The item's field is not equal to a single value. | Author is not Admin |
1805-
| `isAny` | Multiple items | `OR`. The item's field is present in a list of values. | Author is any: Admin, Editor |
1806-
| `isNone` | Multiple items | `NOT OR`. The item's field is not present in a list of values. | Author is none: Admin, Editor |
1807-
| `isAll` | Multiple items | `AND`. The item's field has all of the values in the list. | Category is all: Book, Review, Science Fiction |
1808-
| `isNotAll` | Multiple items | `NOT AND`. The item's field doesn't have all of the values in the list. | Category is not all: Book, Review, Science Fiction |
1809-
| `lessThan` | Single item | `LESS THAN`. The item's field is numerically less than a single value. | Age is less than 18 |
1810-
| `greaterThan` | Single item | `GREATER THAN`. The item's field is numerically greater than a single value. | Age is greater than 65 |
1811-
| `lessThanOrEqual` | Single item | `LESS THAN OR EQUAL TO`. The item's field is numerically less than or equal to a single value. | Age is less than or equal to 18 |
1812-
| `greaterThanOrEqual` | Single item | `GREATER THAN OR EQUAL TO`. The item's field is numerically greater than or equal to a single value. | Age is greater than or equal to 65 |
1813-
| `contains` | Text | `CONTAINS`. The item's field contains the given substring. | Title contains: Mars |
1814-
| `notContains` | Text | `NOT CONTAINS`. The item's field does not contain the given substring. | Description doesn't contain: photo |
1815-
| `startsWith` | Text | `STARTS WITH`. The item's field starts with the given substring. | Title starts with: Mar |
1816-
| `on` | Date | `ON`. The item's field is on a given date (date equality using proper date parsing). | Date is on: 2024-01-01 |
1817-
| `notOn` | Date | `NOT ON`. The item's field is not on a given date (date inequality using proper date parsing). | Date is not on: 2024-01-01 |
1818-
| `before` | Date | `BEFORE`. The item's field is before a given date. | Date is before 2024-01-01 |
1819-
| `after` | Date | `AFTER`. The item's field is after a given date. | Date is after 2024-01-01 |
1820-
| `beforeInc` | Date | `BEFORE (Inc)`. The item's field is before a given date, including the date. | Date is before 2024-01-01, including 2024-01-01 |
1821-
| `afterInc` | Date | `AFTER (Inc)`. The item's field is after a given date, including the date. | Date is after 2024-01-01, including 2024-01-01 |
1822-
| `inThePast` | Date | `IN THE PAST`. The item's field is within the last N units (days, weeks, months, or years) from now. | Orders placed in the past 7 days |
1823-
| `over` | Date | `OVER`. The item's field is older than N units (days, weeks, months, or years) from now. | Orders placed over 7 days ago |
1824-
| `between` | Multiple items | `BETWEEN`. The item's field is between two values. | Item count between (inc): 10-180 |
1825-
1826-
`is`, `isNot`, `on`, `notOn`, `lessThan`, `greaterThan`, `lessThanOrEqual`, `greaterThanOrEqual`, `before`, `after`, `beforeInc`, `afterInc`, `contains`, `notContains`, and `startsWith` are single-selection operators, while `isAny`, `isNone`, `isAll`, and `isNotAll` are multi-selection. `between` is a special operator that requires two values and it's not supported for preset layout. A filter with no operators declared will support the `isAny` and `isNone` multi-selection operators by default. A filter cannot mix single-selection & multi-selection operators; if a single-selection operator is present in the list of valid operators, the multi-selection ones will be discarded, and the filter won't allow selecting more than one item.
1827-
1828-
1801+
| Operator | Description | Example |
1802+
| -------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
1803+
| `after` | `AFTER`. The item's field is after a given date. | Date is after: 2024-01-01 |
1804+
| `afterInc` | `AFTER (Inc)`. The item's field is after a given date, including the date. | Date is on or after: 2024-01-01 |
1805+
| `before` | `BEFORE`. The item's field is before a given date. | Date is before: 2024-01-01 |
1806+
| `beforeInc` | `BEFORE (Inc)`. The item's field is before a given date, including the date. | Date is on or before: 2024-01-01 |
1807+
| `between` | `BETWEEN`. The item's field is between two values. | Count between (inc): 10 and 180 |
1808+
| `contains` | `CONTAINS`. The item's field contains the given substring. | Title contains: Mars |
1809+
| `greaterThan` | `GREATER THAN`. The item's field is numerically greater than a single value. | Age is greater than: 65 |
1810+
| `greaterThanOrEqual` | `GREATER THAN OR EQUAL TO`. The item's field is numerically greater than or equal to a single value. | Age is greater than or equal to: 65 |
1811+
| `inThePast` | `IN THE PAST`. The item's field is within the last N units (days, weeks, months, or years) from now. | Orders in the past: 7 days |
1812+
| `isAll` | `AND`. The item's field has all of the values in the list. | Category is all: Book, Review, Science Fiction |
1813+
| `isAny` | `OR`. The item's field is present in a list of values. | Author is any: Admin, Editor |
1814+
| `isNone` | `NOT OR`. The item's field is not present in a list of values. | Author is none: Admin, Editor |
1815+
| `isNot` | `NOT EQUAL TO`. The item's field is not equal to a single value. | Author is not Admin |
1816+
| `isNotAll` | `NOT AND`. The item's field doesn't have all of the values in the list. | Category is not all: Book, Review, Science Fiction |
1817+
| `is` | `EQUAL TO`. The item's field is equal to a single value. | Author is: Admin |
1818+
| `lessThan` | `LESS THAN`. The item's field is numerically less than a single value. | Age is less than: 18 |
1819+
| `lessThanOrEqual` | `LESS THAN OR EQUAL TO`. The item's field is numerically less than or equal to a single value. | Age is less than or equal to: 18 |
1820+
| `notContains` | `NOT CONTAINS`. The item's field does not contain the given substring. | Description doesn't contain: photo |
1821+
| `notOn` | `NOT ON`. The item's field is not on a given date (date inequality using proper date parsing). | Date is not: 2024-01-01 |
1822+
| `on` | `ON`. The item's field is on a given date (date equality using proper date parsing). | Date is: 2024-01-01 |
1823+
| `over` | `OVER`. The item's field is older than N units (days, weeks, months, or years) from now. | Orders over: 7 days ago |
1824+
| `startsWith` | `STARTS WITH`. The item's field starts with the given substring. | Title starts with: Mar |
1825+
1826+
Some operators are single-selection: `is`, `isNot`, `on`, `notOn`, `lessThan`, `greaterThan`, `lessThanOrEqual`, `greaterThanOrEqual`, `before`, `after`, `beforeInc`, `afterInc`, `contains`, `notContains`, and `startsWith`. Others are multi-selection: `isAny`, `isNone`, `isAll`, and `isNotAll`. A filter cannot mix single-selection & multi-selection operators; if a single-selection operator is present in the list of valid operators, the multi-selection ones will be discarded, and the filter won't allow selecting more than one item.
1827+
1828+
Valid operators per field type:
1829+
1830+
- array: `isAny`, `isNone`, `isAll`, `isNotAll`.
1831+
- boolean: `is`, `isNot`.
1832+
- color: `is`, `isNot`, `isAny`, `isNone`.
1833+
- date: `on`, `notOn`, `before`, `beforeInc`, `after`, `afterInc`, `inThePast`, `over`, `between`.
1834+
- datetime: `on`, `notOn`, `before`, `beforeInc`, `after`, `afterInc`, `inThePast`, `over`.
1835+
- email: `is`, `isNot`, `contains`, `notContains`, `startsWith`, `isAny`, `isNone`, `isAll`, `isNotAll`.
1836+
- integer: `is`, `isNot`, `lessThan`, `greaterThan`, `lessThanOrEqual`, `greaterThanOrEqual`, `between`, `isAny`, `isNone`, `isAll`, `isNotAll`.
1837+
- media: none.
1838+
- number: `is`, `isNot`, `lessThan`, `greaterThan`, `lessThanOrEqual`, `greaterThanOrEqual`, `between`, `isAny`, `isNone`, `isAll`, `isNotAll`.
1839+
- password: none.
1840+
- email: `is`, `isNot`, `contains`, `notContains`, `startsWith`, `isAny`, `isNone`, `isAll`, `isNotAll`.
1841+
- text: `is`, `isNot`, `contains`, `notContains`, `startsWith`, `isAny`, `isNone`, `isAll`, `isNotAll`.
1842+
- url: `is`, `isNot`, `contains`, `notContains`, `startsWith`, `isAny`, `isNone`, `isAll`, `isNotAll`.
1843+
- fields with no type: any operator.
18291844
18301845
### `format`
18311846

0 commit comments

Comments
 (0)