Skip to main content

Layout Page

In the context of the CMS, a layout page is a page that contains elements common to many or all pages on the site. Examples of common elements are typically:

  • header
  • footer
  • navigation menu
  • color palette etc.

Let's imagine that our site is made up of several pages, for example:

  • home page
  • about page
  • contact page

and all these pages have the elements listed above in common. When defining the corresponding pages on the CMS backend you want to avoid repeating these elements for each page.

For this purpose it is sufficient to define a layout page, which is nothing more than a page in which only the elements common to multiple pages are placed. Note that in the CMS there is no explicit concept of layout page: a layout page will be the same as all the others, except for the components it contains. We recommend using a naming convention (e.g. "Main Layout") to distinguish these pages.

Associate Pages with Layout Pages

There are two ways to create this association:

  • CMS side: set a layout page in the page settings (therefore in the CMS side configuration)
  • frontend side: indicate the layout page in the frontend when retrieving the structure of a page

If a layout page is indicated in the frontend, this will override any CMS layout page. Which approach to use depends on the scenarios. CMS side binding is more common. The association might make sense frontend side in more advanced scenarios in which you want to allow some characteristics to be dynamically changed in the frontend of the layout, such as the palette.

To create the association on the CMS side, simply enter a page, open the Settings panel and choose the page layout via the appropriate attribute.

To create the association on the frontend side, when you request any page, you must also indicate its layout page at the same time. To do this, simply pass the layout option in the call to the useDiscoveryPage() hook, as in the following example:

const data = useDiscoveryPage('home', {
layout: 'globalLayout'
}) ?? {};

The layout option in the example has as its value the slug of the page that defines the layout on the CMS. Alternatively, you can use the page ID instead of the slug by specifying the key_type=_id option. In that case, the page itself will also be fetched by ID and not by slug.

If the layout of a page is requested, the object returned by the useDiscoveryPage() hook will have an additional layout property that is completely equivalent, in terms of structure, to a normal page, as in the example below:

{
"components": [
...
],
"details": {
...
},
"_id": "(page ID)",
"layout": {
"components": [
...
],
"details": {
...
},
"_id": "(layout ID)"
}
}

Example of using layout in ReactJS

To use the layout it is advisable to define a component that renders the common parts of the page (typically header, footer, etc.), as in the following example:

<DiscoveryContext.Provider value={data}>
<GlobalLayout layout={data.layout}>
<DiscoveryComponents />
</GlobalLayout>
</DiscoveryContext.Provider>

In the GlobalLayout component, to which the layout section returned by the hook is passed, it is possible to retrieve the data of the various subcomponents using a find by ID, example:

const header = layout.components.find(component =>
component._id === '0725f2cd-80bf-49b0-9490-feef3aba3c1f'
);

To retrieve the component IDs from the CMS pages: open the page, enter the component of interest and click on the "Clipboard" icon in the header at the top of the component form, i.e. the icon in the left corner immediately after the gear icon.

Please note that for layouts dynamic page construction is not supported: the layout structure must be coded in the ReactJS application and cannot be modified on the CMS. In the CMS, however, you can change the data that will appear in the layout, such as:

  • application logo
  • menu items
  • various texts and images etc.