Add a page type

When adding a new page type to Spire CMS, in addition to the PageDefinition all pages require a PageTemplate. For any system pages a PageCreator is also required. A system page is a page that will be automatically created that cannot be added or deleted with CMS. A good example is the SignIn Page.

Enable PageTemplate and PageCreator

Update the start.tsx file that was created during blueprint creation in order to enable the inclusion of PageTemplates and PageCreators in the built JS code. By default, the following code is commented out. Uncomment the code as shown below.

// load all pages. Without this they won't be included in the bundle  
const pages = require.context("./Pages", true, /\.tsx$/);  
const onHotPageReplace = addPagesFromContext(pages);  
if (module.hot) {  
    module.hot.accept(pages.id, () => onHotPageReplace(require.context("./Pages", true, /\.tsx$/)));  
}

Create a PageTemplate

A PageTemplate is a JSON file that contains all of the initial data for a page. This mostly consists of the widgets on the page along with any values for fields. When adding a page through CMS, or using a PageCreator (explained below) the PageTemplate will be used as a starting point for the page.

The easiest way to get started with a PageTemplate is to copy an existing one, add the page to your site, then update the PageTemplate. After creating the PageDefinition do the following.

1. Copy ./wwwroot/AppData/PageTemplates/BuiltIn/Page/Standard.json to ./modules/blueprints/[Blueprint]/wwwroot/AppData/PageTemplates/[NewPageType]/Standard.json.
2. Edit the new file by setting the "Name" and "Type" values equal to the [NewPageType] set above.
3. Use Spire CMS to add the new page to your site.
4. Use Spire CMS to modify the page: add widgets, set any field values.
5. Click the bug icon next to edit.
6. Copy the contents of the Code For Page Template modal into your Standard.json file.

Special cases

Some widgets reference pages by their nodeId. The nodeId at the time a page template is generated will probably not be the same nodeId that is needed at the time a page template is used when creating a page. An example of this is if a page contains a LinkList widget and wants to create a link to the MyAccountPage.

This situation can be handled by using special keyword to dynamically find the nodeId for a page by name, or a nodeId for a page by type. Currently this needs to be done manually. The example below shows how to create a link to a page named About Us and a page with the type of MyAccountPage. Note that the parameters are case sensitive.

"links": [
  {
    "fields": {
      "destination": {
        "type": "Page",
        // this finds the nodeId for the page named "About Us"
        "value": "nodeIdForType('MyAccountPage')"
      },
      "openInNewWindow": false
    }
  },
  {
    "fields": {
      "destination": {
        "type": "Page",
        // this finds the nodeId for the page with a type of "MyAccountPage"
        "value": "nodeIdFor('About Us')"
      },
      "openInNewWindow": false
    }
  }
]

Override builtIn PageTemplates

Every page type that comes with Spire has a bundled PageTemplate that exists at ./wwwroot/AppData/PageTemplates/BuiltIn/[PageType]/Standard.json.

Changing that PageTemplate directly would work locally for dev, but will be ignored when a blueprint is built and deployed. The supported method for overriding a PageTemplate is to create the overridden version at
./modules/blueprints/[Blueprint]/wwwroot/AppData/PageTemplates/[PageType]/Standard.json.

Overriding a PageTemplate will not update any existing pages on a site. It will only affect site generation and new pages that are added through Spire CMS.

Create a PageCreator

A PageCreator is a JSON file that is used to tell Spire that a page needs to be created when the site starts up. PageCreators are required for system pages - pages that cannot be added/removed through CMS only edited. The SignIn page is an example of a system page. For this reason each page type can only have a single page creator defined. A PageCreator uses a PageTemplate to create each page.

A PageCreator will only be run if the type it is for does not yet exist in a site. They cannot be used to modify existing pages or add new children to an existing page.

The PageCreator JSON file needs to be created at ./modules/blueprints/[Blueprint]/wwwroot/AppData/PageCreators/[PageType].json.

An example of the JSON file is show below. Note that the comments are not valid for a json file.

{
  // required field that supplies the name of the page
  "name": "MyAccount",
  
  // required field that determines where in the site hierarchy
  // the page will be created
    "parentType": "HomePage",
  
  // optional field, for pages that have an editable url segment
  // this should be supplied
    "urlSegment": "MyAccount",
  
  // optional field, determines if the page will be excluded from
  // generated navigation. Generally only supported by content pages
    "excludeFromNavigation": true,
  
  // optional field, can be used to supply all the children of a page
  // in the same creator. Is also the only way to use page creators to
  // generate content pages. ParentType is not required when supplying children
    "pages": [],
  
  // optional field. This will default to [PageType]/Standard.json
    "template": "[PathToTemplate]",
}

The PageCreator defines the structure of a website by automatically creating all the system pages. For example to create the site with the following structure:

• / - HomePage
  • /MyAccount - MyAccountPage
    • /MyAccount/Orders - OrderHistoryPage

This could be accomplished using the following three PageCreators:

// HomePage.json
{
  "name": "Home"
}

// MyAccountPage.json
{
  "name": "MyAccount",
  "parentType": "HomePage",
  "urlSegment": "MyAccount"
}

// OrderHistoryPage.json
{
  "name": "Orders",
  "parentType": "MyAccountPage",
  "urlSegment": "Orders"
}

Override builtIn PageCreators

Most of the page types that come with Spire have a bundled PageCreator that exists at ./wwwroot/AppData/PageCreators/BuiltIn/[PageType].json.

Changing that PageCreator directly would work locally for dev, but will be ignored when a blueprint is built and deployed. The supported method for overriding a creator is to create the overridden version at
./modules/blueprints/[Blueprint]/wwwroot/AppData/PageCreators/[PageType].json.

Overriding a page creator will not update any existing pages on a site. It will only affect site generation or pages that do not yet exist.

Overriding PageCreators is only useful at the beginning of a project. It allows a developer to alter the structure of the website, but will only alter that structure if the website content is regenerated. Regenerating the website content means anything not in PageCreators or PageTemplates will be lost.