Layouts - Bloomreach Experience - Headless Digital Experience Platform

Layouts

Definitions

A layout is a configuration of containers and component instances into a hierarchy.

A container is a placeholder in a layout for one or more component instances added and configured by site editors in the Experience manager.

Layouts define the basic structure or template for a generic page layout. These layouts define the tree structure of component instances that should be present in all pages using that layout. These layouts are linked with specific documents via routes to generate individual pages.

One layout can extend another. Typically, a site configuration will contain a generic base layout that defines static components and containers for, for example, a header, a footer, and a main content area. More specific layouts then extend this base layout and add for example a certain number of rows or columns in the main content area and a number of containers for the site editors to place managed component instances in using the Experience manager app.

Consider the following example:

A "base" layout defines a "header", and "main" content area, and a "footer" using static components. The "header" and "footer" components have a container embedded so that site editors can place managed component instances in them.

A "content" layout extends the "base" layout, adds a container to the "main" component, and adds a "right" component with a container.

The resulting aggregated layout is as represented below in the right column. Site editors will be able to place managed component inside the "header", "main", "right", and "footer" components' embedded containers.

Layout definitions Aggregated layout
  • base
    • header (static component)
      • container
    • main (static component)
    • footer (static component)
      • container
  • content (extends "base")
    • main (static component)
      • container
    • right (static component)
      • container
  • content (aggregated)
    • header (static component)
      • container
    • main (static component)
      • container
    • right
      • container
    • footer (static component)
      • container

The example below shows the JSON representation of the "content" layout in the sample application:

{
    "name": "content",
    "label": null,
    "description": null,
    "parameters": {},
    "type": "page",
    "extends": "base",
    "components": [
        {
            "name": "main",
            "label": null,
            "description": null,
            "parameters": {},
            "xtype": null,
            "definition": null,
            "components": [
                {
                    "name": "container",
                    "label": null,
                    "description": null,
                    "parameters": {},
                    "xtype": "hst.nomarkup",
                    "type": "managed"
                }
            ],
            "type": "static"
        },
        {
            "name": "right",
            "label": null,
            "description": null,
            "parameters": {},
            "xtype": null,
            "definition": null,
            "components": [
                {
                    "name": "container",
                    "label": null,
                    "description": null,
                    "parameters": {},
                    "xtype": "hst.nomarkup",
                    "type": "managed"
                }
            ],
            "type": "static"
        }
    ]
}

Note that if you retrieve the JSON for the "base" layout (for example, using the Postman collection), you'll see it has a few more components than "base" in the simplified example above. The principle remains the same however: "content" extends "base" by adding additional components and containers.

For an overview of all layout properties, see the Layout schema in the Site Management API reference documentation.

Layout Operations

The Site Management API treats each page layout and all of its contents as a single entity. Thus, the API provides a coarse grained management approach and changes to nested containers and components can only happen by updating the entire layout. For updates, a GET request is usually executed first, to retrieve the whole hierarchy of a page layout (and also the latest X-Resource-Version header).

See Channel Layout Operations in the Site Management API reference documentation for a list of operations.

You can find examples of using the layout endpoints in the Postman collection.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?