Skip to main content

Creating a CMS page

note

This page is a knowledge dump. It could use a cleanup.

caution

This document is a work in progress as the process for creating resolving a page is still being refined. Check out the Resolve pages and templates with fallback data sources proposal for more details.

To resolve a URL and determine the page type on page load we:

  1. Check if the incoming URL matches one defined in our static routes (eg Account pages, Cart, Checkout, etc). These are defined in apps/carrots-frontend/src/static-pages/routes.ts
  2. If not found we query the page datasource and call the resolvePageByUrl method (You can see it happening here: apps/carrots-frontend/src/graphql/resolvers/Query/pageByUrl.ts:31). In our case Magento is the source of truth for routes so the Magento API is called to resolve it.

So long as one of the two methods above (static routes or page.resolvePageByUrl) resolves a page type the next step is to determine the template. If neither method returns a page type an error is thrown and a HTTP response is sent to the client.

To resolve the page template we query the template datasource for the template based on the page type and url. See: apps/carrots-frontend/src/graphql/resolvers/Page.ts:27

As Contentful handles our page templates the Contentful API is used here. See: packages/datasource-contentful/src/template/DataSource.ts:293

Both the page type and the url are provided to the getTemplateByUrl method so developers can use both to determine how they want to resolve a template based on the project requirements.

In our implementation unless the page type is one of home page, products, category, cart, and 404 types the template is resolved using the page url. Using the Contentful API we query all Page content types with the matching url.

We also support defining a page template in static-pages/routes.ts for pages which don’t need to be customised by a client. If sections are defined on a static route the call to the template API is skipped.

So to answer your question on how to set up a new CMS page:

  1. Define the route in Magento:
    1. In Magento admin head to Content > Pages > Add a new page.
    2. Create a new page and add a url key matching the desired URL. Note though that this should end in .html (eg my-cool-cms-page.html)
  2. Define the page and template in Contentful:
    1. In Contentful head to Content > "Add entry" > Page
    2. Create a new Page entry and add the url key matching the desired URL. Note though that this should not end in .html (eg my-cool-cms-page)
    3. Under "Template" select "Add content" to create a template for your new page