@morningtrain/react-navigation

React Navigation

Concepts and features

Router

When referencing the router, we are actually talking about the RouterHelper class. There is a separate Router component that manages browser history and updates the page component when the route changes.

The RouterHelper class can be accessed using the useRouter hook.

import React from 'react'
import { useRouter } from '@morningtrain/react-navigation'

export default function MyComponent() {
  const router = useRouter()
  
  /// Any other logic in MyComponent
}

It has the following methods and properties:

baseUrl:
Getter to access the current base URL of the application. It includes the path to the project root. It defaults to location.origin.

currentUrl:
Getter to access the current complete URL.

currentRoute:
Getter to access the name of the currently active route.

currentParameters:
Getter to access the current parameters of the route.

routes:
Getter to access an object containing a map of all registered routes.

hasRedirectOnLoginRoute:
Getter to check if the router has a redirect on login route defined.

redirectOnLoginRoute:
Getter to access the currently defined redirect on login route.

hasRedirectOnLogoutRoute:
Getter to check if the router has a redirect on logout route defined.

redirectOnLogoutRoute:
Getter to access the currently defined redirect on logout route.

getOperationForRoute:
Method to get an Operation instance for the route name supplied as a parameter.

navigate:
Method to change the current route and initiate navigation.

It takes two parameters, routeName and parameters. Parameters is an object containing any route parameters that should be used when generating the URL.

onBeforeNavigate:
Method that can be passed a callback which will be triggered right before navigation is executed.

It is triggered from the navigate method.

The method returns a disposer function that will remove the callback from the router when called.

onNavigateStart:
Method that can be passed a callback which will be triggered when navigation is starting.

It is triggered from the navigate method.

The method returns a disposer function that will remove the callback from the router when called.

onNavigate:
Method that can be passed a callback which will be triggered when navigation is complete.

It is triggered from the navigate method.

The method returns a disposer function that will remove the callback from the router when called.

parameter:
Method that takes a string as the only parameter. It returns the route parameter matching the key.

hasParameter:
Method that takes a string as the only parameter. It returns true if a route parameter matching the key exists.

url:
Method that will take a relative path and an object of query parameters to generate a URL.

containsRoute:
Method that will take a route name as the only parameter and will return true if the route is registered.

getRoute:
Method that will return a registered route for the supplied route name.

route:
Method that takes route name, route parameters and query parameters as parameters.

The query parameters are deprecated as the route parameters and the query parameters are merged into a single object in recent versions.

It generates and returns a URL for a route that matches the supplied route name.

method:
Method that takes route name as the only parameter. It will return the route method of the matching route (GET, POST,...)

It returns null if either the route, or a method for the route are missing.

redirectTo:
Method that takes an url as the only parameter. It will redirect the browser to the provided URL.

redirectToRoute:
Method that takes route name and route parameters as parameters. It will generate an URL from the route and redirect the browser to the new URL.

Conditionals

This packages provides the following conditional components.

WhenRouteIs

The component WhenRouteIs will display its children whenever the current route matches the string passed to the prop route.

import React from 'react'
import { WhenRouteIs } from '@morningtrain/react-navigation'

export default function MyComponent() {
  return (
    <WhenRouteIs route={'app.dashboard'}>
      {/* Any child components only displayed on the dashboard */}
    </WhenRouteIs>
  )
}

WhenRouteIsNot

The component WhenRouteIsNot will display its children whenever the current route does not match the string passed to the prop route. It is the reverse component of WhenRouteIs.

import React from 'react'
import { WhenRouteIsNot } from '@morningtrain/react-navigation'

export default function MyComponent() {
  return (
    <WhenRouteIsNot route={'app.dashboard'}>
      {/* Any child components that will not be displayed on the dashboard */}
    </WhenRouteIsNot>
  )
}

WhenRouteHasParameter

This component will render its children when the currently active route has a parameter that matches the specified conditions.

import React from 'react'
import { WhenRouteHasParameter } from '@morningtrain/react-navigation'

export default function MyComponent() {
  return (
    <WhenRouteHasParameter name={'user'} matches={null} negate>
      {/* Any child components that will be displayed 
          when route parameter 'user' is not null */}
    </WhenRouteHasParameter>
  )
}

It takes 3 props:

name - Name of the parameter to look at.

matches - It will try to match the value to this prop directly. A function can be passed which will get the current value as a parameter. If the prop is not provided, then it will check if the value is neither null nor undefined.

negate - Boolean to reverse the conditional. Defaults to false.

Pipes

This package provides the following pipe components.
(see pipeline docs for extra details)

NavigateOnPipe

Pipe component that will trigger navigate on the router when piping.

This is the primary component that should be used for navigating.

It takes the following props:

href:
URL to navigate to - this should not be used together with route.

route:
Route to generate URL for.

routeParameters:
Object containing route parameters to use when generating the URL.

disableRouting:
Defaults to false. When true, it will do a traditional browser navigation and skip our router navigate method.

newTab:
Defaults to false. When true, it will open the generated URL in a new browser tab.

If the payload in the pipeline contains a click event, then it will be able to handle opening in a new tab automatically if CTRL, SHIFT, META(apple) or the middle mouse button is down while navigating. This will help simulate the browser normal behaviour when clicking on a link.