react-pathway

React-pathway is a router/decision making toolkit for React apps. Specifically, it provides you with four useful components that, when used properly, will make it easy to make decisions about when to render other components.

What's in the box

The components that come with react-pathway are as follows:

• <When /> - Allows you to render a component under a given condition. The component can be specified in the form of a prop or as a child element within When.
• <Switch /> - Takes a series of When components as children and renders only the first one that has a truthy condition.
• <Otherwise /> - Can be used as a Switch child whose condition is guaranteed to be truthy.
• <Redirect /> - When rendered, will redirect the page to another pathname.

Note that When and Otherwise are only allowed a single child element.

Let's look at a couple of examples

First, let's render two components:

import { When } from 'react-pathway';

const FooComponent = props => {
  return (
    <div>
      <When isTrue={true} component={BarComponent} />
      <When isTrue={true} component={BazComponent} />
    </div>
  )
}

Next, let's render only one component:

import { When } from 'react-pathway';

const FooComponent = props => {
  return (
    <div>
      <When isTrue={true} component={BarComponent} />
      <When isTrue={false} component={BazComponent} />
    </div>
  )
}

Next, let's render only one component again, but let's do it with child elements instead of props this time:

import { When } from 'react-pathway';

const FooComponent = props => {
  return (
    <div>

      <When isTrue={true}>
        <BarComponent />
      </When>

      <When isTrue={false}>
        <BazComponent />
      </When>

    </div>
  )
}

Next, let's use Switch to guarantee that only one component gets rendered.

import { Switch, When } from 'react-pathway';

const FooComponent = props => {
  return (
    <Switch>
      <When isTrue={true} component={BarComponent} />
      <When isTrue={true} component={BazComponent} />
    </Switch>
  )
}

Because we used Switch here, only the first truthy When component will render. So we'll end up seeing the BarComponent but not the BazComponent. If neither one was truthy, we wouldn't see anything render at all.

Next, let's use Otherwise to guarantee that something will always get rendered.

import { Switch, When, Otherwise } from 'react-pathway';

const FooComponent = props => {
  return (
    <Switch>
      <When isTrue={false} component={BarComponent} />
      <When isTrue={false} component={BazComponent} />
      <Otherwise component={ElseCaseComponent} />
    </Switch>
  )
}

The Otherwise component works exactly like When except it doesn't take any truthiness props. It's always truthy. So it's good to put at the bottom of a series of Switch children. Also, it's only allowed to be used as a Switch child. If you try to use it any other way, you'll get an error.

Other truthiness props

So far we've only looked at the isTrue prop but there are a couple of others you can use as well. Note that When and Otherwise components only allow you to use one truthiness prop at a time. If you try to put more than one of them on a single element, you'll get an error.

This one renders whenever the value is truthy:

<When isTrue={true} component={FooComponent} />

This one renders whenever the value is falsy:

<When isFalse={false} component={FooComponent} />

This one renders whenever location.pathname matches the provided path:

<When path="/foo" component={FooComponent} />

This one renders whenever the provided path is found at the end of location.pathname:

<When subPath="/foo" component={FooComponent} />

More advanced routing

You are allowed to use these components anywhere. So when it comes to routing, you have options.

On the one hand, you could write some very simple routing at the top level like this:

<Switch>
  <When path="/" component={HomeContainer} />
  <When path="/about" component={AboutContainer} />
  <When path="/contact" component={ContactContainer} />
  <Otherwise component={FourOhFourContainer} />
</Switch>

But then within your hypothetical AboutContainer, you could also do something like this:

render() {
  return (
    <div className="about-container">
      <Nav />
      <Sidebar />
      <Switch>
        <When subPath="/company" component={AboutCompanyComponent} />
        <When subPath="/team/*" component={AboutTeamComponent} />
      </Switch>
    </div>
  )
}

In this case, we'll render the AboutCompanyComponent only when the full path is "/about/company". As for the AboutTeamComponent, that one will get rendered with the path is "/about/team" or "/about/team/billy" or even "/about/team/members/billy". The little /* piece at the end indicates that we should allow further sub pathing.

So the trick with the path attribute is that either the whole path has to match, or, if you do something like path="/foo/*", then the match has to be found at the beginning of the path.

If you use subPath, you will also get a positive match if the full path matches. However, you will also get a positive match if what you specify is found at the end of the path. To illustrate:

path="/foo"

• will match https://example.com/foo
• won't match https://example.com/foo/bar
• won't match https://example.com/bar/foo

path="/foo/*"

• will match https://example.com/foo
• will match https://example.com/foo/bar
• won't match https://example.com/bar/foo

subPath="/foo"

• will match https://example.com/foo
• will match https://example.com/bar/foo
• won't match https://example.com/bar/foo/baz
• won't match https://example.com/foo/bar

subPath="/foo/*"

• will match https://example.com/foo
• will match https://example.com/bar/foo
• will match https://example.com/bar/foo/baz
• will match https://example.com/foo/bar

Lastly, let's choose some components per path, but redirect when we don't get a match:

<Switch>
  <When path="/" component={HomeContainer} />
  <When path="/about" component={AboutContainer} />
  <When path="/contact" component={ContactContainer} />
  <Otherwise>
    <Redirect to="/" />
  <Otherwise />
</Switch>

Note that the to attribute on the Redirect component can take an actual path name like "/foo" or a hash path name like "#foo". The Switch component keeps track of the location object so it can rerender if it needs to whenever the hash path changes. It will also make sure that anything nested below it gets a cool location object passed in as a prop.

In order to handle hash paths with When, you'll probably want to use the isTrue attribute, for example isTrue={location.hash === '#foo'}.

Contributing

Just clone it, run yarn or npm install and you're ready to go.

The source code is located in src and a convenient dev environment is located in dev.

Run gulp build to compile the source into the bin directory.

Run gulp serve to start up the dev server and serve up whats in dev/client. As part of the process, this will compile the source and drop it into bin so that you can pull from there.