Routing

Unlike WordPress CMS, decoupled approach allows to establish any routing scheme required on a project, even if it doesn't match back-end structure. Obviously, we strongly recommend to keep routes in front-end and back-end aligned to make previews or navigation easier, however developers are given a full freedom in terms of how links will be organised.

Routes

Routes are declared in frontend/src/pages in exactly the same way as in any Gatsby.js projects. It might be useful to visit their documentation, however the most straight-forward implementation is explained below.

Gatsby generates pages for each JavaScript file located inside frontend/src/pages. Structure of directories within this location will be reflected in browsers URL, so as a result for example frontend/src/pages/about-us/history.js will be converted into /about-us/history/ route.

Example presented below will create a page /hello-world

import * as React from "react"

export default function Index() {
  return <div>Hello world</div>
}

URL Generation

Regular routes are useful for complex React.js implementations, however considering the fact our intention is to serve as much content coming from WordPress and Gutenberg as possible, more beneficial approach would be to generate pages out of WordPress entities automatically, without specyfing individual names in the file system.

The mentioned case is handled in Gatsby using Collection Routes. It is possible to create multiple pages from a model based on GraphQL collection of nodes. Source files located in frontend/src/pages should be put within curly braces { and }. Statik framework exposes multiple WordPress generated models to be consumed easily using collection routes approach. For more details navigate to Queries page in the documentation.

Example presented below will create a page for a singular post that is returned for /insights/hello-world route in which hello-world is a slug defined in WordPress. Also, the example implements Gutenberg Blocks support which is explained more in detail on Blocks page.

The component is located in insights/{Posts.uri}.js file. Brackets holds GraphQL mapping to the uri, which is a Gatsby.js representation of a slug. If you would like to use /insights/3 format, in which 3 is an ID of a post, the file should be called insights/{Posts.wordpress_id}.js

import React from 'react';
import PropTypes from 'prop-types';
import { graphql } from 'gatsby';

const Post = props => {
  const {
    data: {
      post: {
        gutenbergBlocks,
      },
    },
  } = props;

  return (
    <main>
      {gutenbergBlocks && gutenbergBlocks.nodes && (
        <StatikBlocks blocks={gutenbergBlocks.nodes} />
      )}
    </main>
  );
};

Post.propTypes = {
  data: PropTypes.shape({
    post: PropTypes.shape({
      gutenbergBlocks: PropTypes.shape({
        nodes: PropTypes.array,
      }),
    }),
  }),
};

export default Post;

export const query = graphql`
  query PostQuery($id: ID!) {
    ...PostFragment
    post(id: $id) {
      id
    }
  }
`;

Front-end and back-end alignment

@TBC: Damian: Update permalinks on a WordPress side

Related tickets

• Good pracises: When it is better to define an individual route instead of collection routes?
• Good pracises: Building default templates for native WordPress post types.