Layouts and Sub-layouts¶

A layout is the frame a page is shown in: the navigation rail, the header, the footer, and the empty space in between where the page's own content goes. Every page of a portal is based on one layout of the portal's design. Pages that share a layout share the same frame, so you build the navigation once and every page gets it.

A simple portal needs one layout. A larger one might have a main layout and a second one that adds a side panel for dashboard pages. This page explains how a layout marks the space for page content, how layouts nest, and what a layout can share with its pages.

Placeholders and content fills¶

A layout marks the places a page may fill with content placeholders. A placeholder is a named region. When you edit a page, a placeholder shows up as the area where the page's widgets go.

Say you build a layout with a sidebar on the left and a placeholder called main on the right. Every page on that layout shows the sidebar, and each page puts its own widgets into main. The page's widgets for a placeholder are called that page's content fill. A page has one fill per placeholder, and you see them as the page's top-level items in Elements.

A few things to know about placeholders:

• A layout can have as many placeholders as it needs, with any names. A typical page shell has one, often called main. A dashboard shell might add a side or toolbar region.
• Widgets you place inside a placeholder in the layout editor become its default content. A new page starts with a copy of them, which the page author can change or delete. The copy is made once, when the page is created. Later changes to the defaults don't reach existing pages.
• A placeholder the page leaves empty shows nothing. On the page canvas it offers an Add content for "name" button that creates the fill.
• A widget placed on a page outside every fill has nowhere to go and is not shown.

Everything else in the layout, outside the placeholders, belongs to the layout and can't be edited from a page.

Sub-layouts¶

Layouts can nest. A sub-layout has a Parent Layout and is drawn inside one of the parent's placeholders, filling it the way a page would. The sub-layout then declares placeholders of its own for the page to fill.

This lets you share the outer frame while offering pages different inner arrangements. A common setup:

Shell                 navigation rail, header, user menu
├── Full width        fills Shell's "main" with a single "content" region
└── With side panel   fills Shell's "main" with a "content" and a "side" region

A page based on With side panel is drawn inside that sub-layout, which is drawn inside Shell. Each layer adds its frame around the next.

To create a sub-layout, right-click a layout in Page Layouts and choose Add sub-layout, or set Parent Layout in the Layout ribbon tab. You can also drag a layout onto another in the tree to nest it, or between rows to reorder siblings. The order only affects the tree and the Add page menu.

A sub-layout fills a parent placeholder by holding a content fill with the placeholder's name. What you place in that fill is the sub-layout's own frame. The placeholders you put inside it are what pages see.

When layouts stack, these rules apply:

• A page sees the whole chain. Its canvas draws the root layout first, each sub-layout inside its parent, and the page's own fills innermost.
• The page fills what no layout filled. When a page is created, it gets one content fill for every placeholder in the chain that a layout hasn't already filled. A placeholder a sub-layout fills is the sub-layout's business, and the page gets no fill for it.
• Same name, innermost wins. If two layouts in the chain declare a placeholder with the same name, the page fills the one closest to it.
• Names are only labels. Two layouts may share a name. Pages and designs tell layouts apart by an internal key, so renaming a layout breaks nothing. A layout can't become its own descendant, and the Parent Layout list only offers valid parents.

What a layout can share¶

A layout can declare parameters and data sources in its Layout ribbon tab. Every page based on it, directly or through a sub-layout, sees them as if they were its own.

This is how you put a year filter in the header and have every page respect it, or load the signed-in user's profile once instead of on every page.

• The nearest declaration wins. A page looks for a name on itself first, then on its layout, then on that layout's parent, up to the root. A page can therefore override a layout parameter by declaring its own with the same name.
• Values are shared. A parameter on a layout keeps its value as the reader moves between pages on that layout. A data source on a layout is loaded once and reused. See Page and Portal State.
• Read-only from the page. In a page's parameter and data source lists, inherited entries carry a From layout marker. The page can give them a value and use them. To edit them, click Open in design, which jumps to the layout that owns them.
• Windows start fresh. A window inherits nothing from any layout. Its own parameters are its whole input.

A widget placed in a layout binds the same way a page widget does. Its $params and $data contain the layout's own entries and, when drawn on a page, that page's as well.

The navigation rail¶

The portal's navigation is made of ordinary widgets inside a layout, typically a Sidebar Layout with a Nav List in its sidebar. The nav list builds its links from the portal's pages. So the layout decides how navigation looks, and the portal decides what is in it, through each page's Show in navigation, Module, Icon and order. See Portals and Pages.

Changing a layout that pages use¶

Layouts are versioned together with their design. A published portal is pinned to one published design version. Editing a layout in the design's draft changes nothing for viewers until the design is published and the portal is moved to the new version.

Keep placeholder names stable across versions. A page's fills are matched to placeholders by name, so a renamed placeholder leaves that page content unrendered until the page is adjusted.

A layout that a page is based on can't be deleted. Delete the pages or move them to another layout first.