Routing

Compared to the WordPress CMS, the decoupled approach allows you to establish any routing scheme required for your project, even if it does not match the back-end structure. While it's recommended to keep the routes in the front-end and back-end aligned to make previews or navigation easier, developers are given full freedom in terms of how links will be organized.

Routes

Routes are declared in frontend/src/pages in exactly the same way as in any other Gatsby.js projects. It may be useful to visit their documentation, but the most straightforward implementation is explained below.

Gatsby generates pages for each JavaScript file located inside frontend/src/pages. The structure of directories within this location will be reflected in the browser's URL. For example, frontend/src/pages/about-us/history.js will be converted into the /about-us/history/ route.

The example presented below will create a page /hello-world.

frontend/src/pages/hello-world.js

import * as React from "react";
 
export default function Index() {
  return <div>Hello world</div>;
}

Collection Routes

Regular routes can be useful for complex React.js implementations. However, considering our intention to serve as much content as possible from WordPress and Gutenberg, a more beneficial approach would be to automatically generate pages from WordPress entities, without specifying individual names in the file system.

The mentioned case is handled in Gatsby using Collection Routes. Collection route is a way to dynamically create pages for a group of related content, such as blog posts or products. It is possible to create multiple pages from a model based on a GraphQL collection of nodes. Source files located in frontend/src/pages should be put within curly braces {and}. The SiteBox framework exposes multiple WordPress-generated models to be consumed easily using the collection routes approach. To sum up:

Collection routes are a declarative approach to creating pages in Gatsby, which allow you to create dynamic pages based on collections of data.
With collection routes, you define a set of templates and GraphQL queries that are applied to a specific type of data, such as blog posts or products.
When you run gatsby develop or gatsby build, Gatsby automatically generates pages for each piece of data that matches the collection route.

For more details, navigate to the Queries page in the documentation.

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

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

frontend/src/pages/insights/{Posts.uri}.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) {3
      id
    }
  }
`;

For most use cases you’ll be able to use the File System Route API to create pages. Collection Route approach is not recommended when you operate with big amount of data which cause performance problems.

Create Pages

As mentioned above, whenever you are working with a large amount of data, you should consider using createPages instead of Collection routes. When building things like pagination or archive pages, the createPages method is an ideal tool for this purpose. Using it results in preserving page performance and optimizing it. You can find general information about this approach here.

Blocks Styles