#Pages and Layouts Direct Access

In almost all cases, your Addon should create Pages and RepoLayouts for your users. Addons in general are meant to create things for your users to use as they wish, which includes remixing your Addon's Components, changing Attributes, adding their own Fields to Collections, and in the case of Pages and Layouts, using your Pages and RepoLayouts as an example or not at all.

These features should only be used in the case of something like an external site importer or migration tool.

Do not configure your Addon to automatically create Pages when it starts. It should be your users' choice whether they use Pages provided by your Addon and if so, what their title, path, and content should be.

Pages are not removed when your Addon is uninstalled.

#Page Schema

{

  // uneditable properties
  _id: '63ed535f146fc26146829ffb',
  managedByAddonId: '639b8f837f5fb8a39404280a',
  parentVersionId: '6503da44456b3c276ad4ab8c',
  updatedAt: 1671486365027,
  createdAt: 1671486531695,
  builtPaths: [],

  // basic properties
  title: '',
  type: '',
  path: '',
  description: '',
  layoutId: '',
  isEnabled: true,

  // body properties
  lang: 'pug',
  body: '',

  // style properties
  styleLang: 'stylus',
  style: '',

  // tags
  tags: [],

  // scripts
  script: '',
  usesDataScript: false,
  dataScript: '',

  // seo
  favicon: '',
  noindex: false,
  nofollow: false,
  canonicalUrl: '',
  ogType: '',
  ogTitle: '',
  ogImages: '',
  ogDescription: '',
  ogArticleAuthors: '',
  ogArticlePublishedTime: '',
  ogArticleModifiedTime: '',
  ogArticleExpirationTime: '',
  ogArticleSection: '',
  ogArticleTags: '',
  schemas: [],

}

#Uneditable Properties

#Basic Properties

#Body Properties

#Style Properties

#Tags

This is a list of Tags in the order they should be added to the Page. See Tags for more information.

#Scripts

#SEO Properties

Many of a Page's SEO properties relate to Open Graph.

#Creating Pages

You can create Pages using cms.createPage(), which will return a Page Draft. Only ever create Pages from direct user-interaction. Do not automatically create Pages for users when your Addon starts.

let pageDef = {
  title: 'My Page',
  path: '/my-page',
  description: 'A Demo Page',
  body: '.my-page\n  This is my demo page!',
  style: ".my-page\n  color {{ addons['demo-addon'].mainColor }}",
}

// use static-cms-addon
import cms from 'static-cms-addon'

let pageDraft = await cms.createPage(pageDef)
console.log(pageDraft.doc._id) // "63ed535f146fc26146829ffb"

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/page`, pageDef)
console.log(response.data.pageDraft.doc._id) // "63ed535f146fc26146829ffb"

You can also load the Page from a zip or folder using cms.loadPagePackage().

let pageDef = cms.loadPagePackage('pages/myPage.page.zip').page
let pageDraft = await cms.createPage(pageDef)

#Converting HTML and CSS

This API is only ever meant to be used for the purposes of importing external content or migrating from other sites. Because most external sites use HTML and CSS, you can specify convertBodyTo: 'pug' and convertStyleTo: 'stylus' when creating Pages. If the HTML and CSS provided is invalid and cannot be converted, it will still save the Page in the original language. lang and styleLang will be automatically set when using these options. Ex:

let pageDef = {
  title: 'My Page',
  path: '/my-page',
  description: 'A Demo Page',
  body: '<div class="my-page">This is my demo page!</div>',
  style: '.my-page {\n  color: red;\n}',
  convertBodyTo: 'pug',
  convertStyleTo: 'stylus',
}

// use static-cms-addon
import cms from 'static-cms-addon'

let pageDraft = await cms.createPage(pageDef)
console.log(pageDraft.doc._id) // "63ed535f146fc26146829ffb"

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/page`, pageDef)
console.log(response.data.pageDraft.doc._id) // "63ed535f146fc26146829ffb"

#Listing Pages

You can use cms.getPages() and cms.getPageDrafts() to get a list of the Pages in the CMS. This includes Pages your Addon has not created. Any Pages your Addon has created will have a managedByAddonId key with your Addon's ID as the value.

// use static-cms-addon
import cms from 'static-cms-addon'

let pages = await cms.getPages()
let pageDrafts = await cms.getPageDrafts()
console.log(pages.map(page => page.title)) // ['My Page', 'Another Page']
console.log(pages.map(pageDraft => pageDraft.doc.title)) // ['A Third Page']

// use axios
let response = await axios.get(`http://localhost:${cmsPort}/api/addon/${addonId}/page`)
console.log(response.data.pages.map(page => page.title)) // ['My Page', 'Another Page']
console.log(response.data.pageDrafts.map(pageDraft => pageDraft.doc.title)) // ['A Third Page']

#User Modification

Once you have created a Page, your Addon can no longer modify it or delete it. It is also not removed when your Addon is uninstalled. The user may decide to rename it, change its path, alter its content, or delete it. Remember, do not create Pages when your Addon starts or the user will become frustrated with your Addon and uninstall it.

#Rich Snippets

For details about adding Rich Snippets to Pages and Layouts, see Rich Snippets.