woocommerce/plugins/woocommerce-admin/packages/navigation/README.md

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

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.

import { history } from '@woocommerce/navigation';

render() {
	return (
		<Router history={ history }>
			…
		</Router>
	);
}

getAdminLink(path) ⇒ String

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: String - Full admin URL.

Param	Type	Description
path	String	Relative path.

getPath() ⇒ String

Get the current path from history.

Returns: String - Current path.

stringifyQuery(query) ⇒ String

Converts a query object to a query string.

Returns: String - Query string.

Param	Type	Description
query	Object	parameters to be converted.

getTimeRelatedQuery(query) ⇒ Object

Gets time related parameters from a query.

Returns: Object - Object containing the time related queries.

Param	Type	Description
query	Object	Query containing the parameters.

getIdsFromQuery(queryString) ⇒ Array

Get an array of IDs from a comma-separated query parameter.

Returns: Array - List of IDs converted to numbers.

Param	Type	Description
queryString	string	string value extracted from URL.

getNewPath(query, path, currentQuery) ⇒ String

Return a URL with set query parameters.

Returns: String - Updated URL merging query params into existing params.

Param	Type	Description
query	Object	object of params to be updated.
path	String	Relative path (defaults to current path).
currentQuery	Object	object of current query params (defaults to current querystring).

getQuery() ⇒ Object

Get the current query string, parsed into an object, from history.

Returns: Object - Current query object, defaults to empty object.

onQueryChange(param, path, query) ⇒ function

This function returns an event handler for the given param

Returns: function - A callback which will update param to the passed value when called.

Param	Type	Description
param	string	The parameter in the querystring which should be updated (ex page, per_page)
path	string	Relative path (defaults to current path).
query	string	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	Object	object of params to be updated.
path	String	Relative path (defaults to current path).
currentQuery	Object	object of current query params (defaults to current querystring).