dojo dragon main logo

Using MatchDetails

For every route that is matched on a route change, MatchDetails are injected into the both the Route and the Outlet widget. The MatchDetails object contains specific details for a matched route.

Note: All examples assume that the default HashHistory history manager is being used.

queryParams

  • queryParams: { [index: string]: string }: The query params from the matched route.

src/routes.ts

export default [
    {
        id: 'home',
        path: 'home',
        outlet: 'home'
    }
];
  • given the URL path /#home?foo=bar&baz=42, the queryParams object will look like:
{
    foo: 'bar',
    baz: '42'
}

params

  • params: { [index: string]: string }: The path params from the matched route.

src/routes.ts

export default [
    {
        id: 'home',
        path: 'home/{page}',
        outlet: 'home'
    }
];
  • given the URL path /#home/about, the params object will have look like:
{
    page: 'about';
}

isExact()

  • isExact(): boolean: A function that indicates if the route is an exact match for the path. This can be used to conditionally render different widgets or nodes.

src/routes.ts

export default [
    {
        id: 'home',
        path: 'home',
        outlet: 'home',
        children: [
            {
                id: 'about',
                path: 'about',
                outlet: 'about'
            }
        ]
    }
];
  • given the above route definition, if the URL path is set to /#home/about, then isExact() will evaluate to false for the Route with the id "home" and true for a Route that is a child of the home Route with the id "about" as shown in the following file:

src/App.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import Route from '@dojo/framework/routing/Route';

const factory = create();

export default factory(function App() {
    return (
        <div>
            <Route
                id="home"
                renderer={(homeMatchDetails) => {
                    console.log('home', homeMatchDetails.isExact()); // home false
                    return (
                        <Route
                            id="about"
                            renderer={(aboutMatchDetails) => {
                                console.log('about', aboutMatchDetails.isExact()); // about true
                                return [];
                            }}
                        />
                    );
                }}
            />
        </div>
    );
});

isError()

  • isError(): boolean: A function indicates if the route is an error match for the path. This indicates after this route was matched, no other matches were found.

src/routes.ts

export default [
    {
        id: 'home',
        path: 'home',
        outlet: 'home',
        children: [
            id: 'about',
            path: 'about',
            outlet: 'about'
        ]
    }
];
  • given this route definition, if the URL path is set to /#home/foo then there is no exact route match, so the isError() method on the home Route's matchDetails object will yield true. Navigating to /#home or /#home/about however will cause the same method to return false since both routes are defined.

type

  • type: 'index' | 'partial' | 'error': The type of match for the route, either index, partial or error. Using type should not be necessary, instead favouring a combination of isExact and isError.
export default [
    {
        id: 'home',
        path: 'home',
        outlet: 'home',
        children: [
            id: 'about',
            path: 'about',
            outlet: 'about'
        ]
    }
];
  • given the above route definition, the following values of type would be provided to each route:
URL path Home route About route
/#home 'index' N/A
/#home/about 'partial' 'index'
/#home/foo 'error' N/A

router

  • router: RouterInterface: The router instance which can used to create links and initiate route changes. For more information see the router API.

src/routes.ts

export default [
    {
        id: 'home',
        path: 'home',
        outlet: 'home',
        children: [
            {
                id: 'home-details',
                path: 'details',
                outlet: 'home-details'
            }
        ]
    }
];

src/App.tsx

import { create, tsx } from '@dojo/framework/core/vdom';
import Route from '@dojo/framework/routing/Route';

const factory = create();

export default factory(function App() {
    return (
        <div>
            <Route
                id="home"
                renderer={(matchDetails) => {
                    const { params, queryParams, isExact, isError, router } = matchDetails;

                    const gotoHome = () => {
                        const link = router.link('home');
                        if (link) {
                            router.setPath(link);
                        }
                    };

                    if (isExact()) {
                        // The path `home` was matched
                        return <div>Home Page</div>;
                    }
                    if (isError()) {
                        // The `home` segment of the path was matched but the
                        // next segment was not matched for example, `home/other`
                        return (
                            <div>
                                <button onclick={gotoHome}>Goto Home</button>
                                <div>Unknown Page</div>
                            </div>
                        );
                    }
                    // The `home` segment of the path was matched and the next
                    // segment was also matched for example, `home/details`
                    return <div>Partial Match for Home</div>;
                }}
            />
        </div>
    );
});