107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
|
# Navigation
|
||
|
|
|
||
|
|
A collection of navigation-related functions for handling query parameter objects, serializing query parameters, updating query parameters, and triggering path changes.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
Install the module
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install @woocommerce/navigation --save
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
### history
|
||
|
|
|
||
|
|
A single history object used to perform path changes. This needs to be passed into ReactRouter to use the other path functions from this library.
|
||
|
|
|
||
|
|
```jsx
|
||
|
|
import { history } from '@woocommerce/navigation';
|
||
|
|
|
||
|
|
render() {
|
||
|
|
return (
|
||
|
|
<Router history={ history }>
|
||
|
|
…
|
||
|
|
</Router>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### getAdminLink(path) ⇒ <code>String</code>
|
||
|
|
Returns a string with the site's wp-admin URL appended. JS version of `admin_url`. This relies on a global object `wcSettings` with a property `adminUrl` set.
|
||
|
|
|
||
|
|
**Returns**: <code>String</code> - Full admin URL.
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| path | <code>String</code> | Relative path. |
|
||
|
|
|
||
|
|
### getPath() ⇒ <code>String</code>
|
||
|
|
Get the current path from history.
|
||
|
|
|
||
|
|
**Returns**: <code>String</code> - Current path.
|
||
|
|
|
||
|
|
### stringifyQuery(query) ⇒ <code>String</code>
|
||
|
|
Converts a query object to a query string.
|
||
|
|
|
||
|
|
**Returns**: <code>String</code> - Query string.
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| query | <code>Object</code> | parameters to be converted. |
|
||
|
|
|
||
|
|
### getTimeRelatedQuery(query) ⇒ <code>Object</code>
|
||
|
|
Gets time related parameters from a query.
|
||
|
|
|
||
|
|
**Returns**: <code>Object</code> - Object containing the time related queries.
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| query | <code>Object</code> | Query containing the parameters. |
|
||
|
|
|
||
|
|
### getIdsFromQuery(queryString) ⇒ <code>Array</code>
|
||
|
|
Get an array of IDs from a comma-separated query parameter.
|
||
|
|
|
||
|
|
**Returns**: <code>Array</code> - List of IDs converted to numbers.
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| queryString | <code>string</code> | string value extracted from URL. |
|
||
|
|
|
||
|
|
### getNewPath(query, path, currentQuery) ⇒ <code>String</code>
|
||
|
|
Return a URL with set query parameters.
|
||
|
|
|
||
|
|
**Returns**: <code>String</code> - Updated URL merging query params into existing params.
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| query | <code>Object</code> | object of params to be updated. |
|
||
|
|
| path | <code>String</code> | Relative path (defaults to current path). |
|
||
|
|
| currentQuery | <code>Object</code> | object of current query params (defaults to current querystring). |
|
||
|
|
|
||
|
|
### getQuery() ⇒ <code>Object</code>
|
||
|
|
Get the current query string, parsed into an object, from history.
|
||
|
|
|
||
|
|
**Returns**: <code>Object</code> - Current query object, defaults to empty object.
|
||
|
|
|
||
|
|
### onQueryChange(param, path, query) ⇒ <code>function</code>
|
||
|
|
This function returns an event handler for the given `param`
|
||
|
|
|
||
|
|
**Returns**: <code>function</code> - A callback which will update `param` to the passed value when called.
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| param | <code>string</code> | The parameter in the querystring which should be updated (ex `page`, `per_page`) |
|
||
|
|
| path | <code>string</code> | Relative path (defaults to current path). |
|
||
|
|
| query | <code>string</code> | object of current query params (defaults to current querystring). |
|
||
|
|
|
||
|
|
### updateQueryString(query, path, currentQuery)
|
||
|
|
Updates the query parameters of the current page.
|
||
|
|
|
||
|
|
| Param | Type | Description |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| query | <code>Object</code> | object of params to be updated. |
|
||
|
|
| path | <code>String</code> | Relative path (defaults to current path). |
|
||
|
|
| currentQuery | <code>Object</code> | object of current query params (defaults to current querystring). |
|