History

This package contains history utilities for the HizzleWP framework.

Usage example:

import { Router, Outlet, updatePath, useQuery, onQueryChange, useRoute } from '@hizzlewp/history';
import { Button } from '@wordpress/components';

/**
 * Display the home page.
 */
const Home = () => <div>Home Page</div>;

/**
 * Display the user's page layoute.
 */
const UserLayout = () => (
    <div>
        <h1>User's Page</h1>
        <Outlet path="/users" />
    </div>
);

/**
 * Display the user list.
 */
const UserList = () => {
    // Get the query parameters.
    const {page} = useQuery();

    // Get the users. You can use any data source you want.
    const users = useUsers({page });

    // Move to the next page.
    const onChangePage = onQueryChange('page');

    return (
        <div>
            <div>User List</div>
            {users.map((user) => (
                <Button key={user.id} onClick={() => updatePath(`/users/${user.id}`)}>
                    {user.name}
                </Button>
            ))}
            <Button onClick={() => onChangePage(page + 1)}>Next Page</Button>
        </div>
    );
};

/**
 * Display a user's detail.
 */
const UserDetail = () => {
    const { params } = useRoute();
    return <div>User Detail {params.get('id')}</div>;
};

// Define routes
const routes = [
  {
    path: '/',
    element: <Home />,
  },
  {
    path: '/users',
    element: <UserLayout />,
    children: [
      {
        path: '/users/:id',
        element: <UserDetail />,
      }
    ],
    index: <UserList />,
  },
];

// Use in app
const App = () => (
  <Router routes={routes}>
    <nav>
      <Button onClick={() => updatePath('/')}>Home</Button>
      <Button onClick={() => updatePath('/users')}>Users</Button>
    </nav>
    <Outlet />
  </Router>
);

addHistoryListener

Adds a listener that runs on history change.

Parameters

• listener Function: Listener to run on history change.

Returns

• Function: Function to remove listeners.

getHistory

Recreate history to coerce React Router into accepting path arguments found in query parameter hizzlewp_path, allowing a url hash to be avoided. Since hash portions of the url are not sent server side, full route information can be detected by the server.

Returns

• History: React-router history object with get location modified.

getNewPath

Return a URL with set query parameters.

Parameters

• query Object: object of params to be updated.
• path string: Relative path (defaults to current path).

Returns

• string: Updated URL merging query params into existing params.

getPath

Get the current path from history.

Returns

• string: Current path.

getQuery

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

Returns

• Record<string, QueryArgParsed>: Current query object, defaults to empty object.

goToParent

Navigates to the parent path.

navigateTo

A utility function that navigates to a page.

Parameters

• args Object: - All arguments.
• args.url string: - Relative path or absolute url to navigate to

onQueryChange

This function returns an event handler for the given param

Parameters

• param string: The parameter in the querystring which should be updated (ex paged, per_page)
• path string: Relative path (defaults to current path).
• query string: object of current query params (defaults to current querystring).

Returns

• Function: A callback which will update param to the passed value when called.

Outlet

Outlet component for rendering nested routes in the router.

This component is responsible for rendering the appropriate route element based on the current routing context. It handles nested routing by finding and rendering the next appropriate outlet or index route.

Usage

// Render the first outlet
<Outlet />

// Render a specific outlet by path
<Outlet path="/dashboard" />

Parameters

• props - The component props
• props.path - Don't provide for the first . Always provide for other paths otherwise your browser will hang.

Router

Router component

Type

• React.FC< RouterProps >

updatePath

Updates the path of the current page.

Parameters

• path string: Relative path (defaults to current path).

updateQueryString

Updates the query parameters of the current page.

Parameters

• 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).

usePath

A hook that returns the current path.

Returns

• string: The current path.

useQuery

Like getQuery but in useHook format for easy usage in React functional components

Returns

• Record<string, string>: Current query object, defaults to empty object.

useRoute

Undocumented declaration.