Page templates replace global regions

Page templates replace global regions. A page template is a reusable, full-page component tree containing exactly one Page content marker. Canvas inserts the main page content at that marker.

Page templates can contain headers, footers, navigation, and other components. They are independent of Drupal theme regions unless they use the optional theme page template component.

Manage page templates in the Canvas editor under Templates > Page templates. Use a template's actions menu and select Set as default to make it the site default. Pages without an explicit selection use the site default.

To use a different template for a Canvas page, choose one under Page data > Page template. For a full content template, choose one from its Page template context submenu. Choose Site default to use the site default.

Backward compatibility

The optional Drupal Canvas Page Template Component module (canvas_page_template_component) exposes an installed theme's page template as a Canvas component, with the theme's regions available as slots. A page template that uses this component preserves the theme's existing page and region markup. Sites can keep using the theme-based component or rebuild the page template with regular Canvas components to remove its theme dependency.

The administer page template permission has not changed. The permission previously controlled global regions and now controls creating and managing page templates and choosing the site default. Existing permission assignments are preserved. Users who can edit pages can select a page template for a page without having permission to manage page templates.

Automatic migration from global regions

Canvas runs the migration when database updates run during a Canvas update and when a site template is installed. If the site does not already have a default page template, Canvas converts the enabled global regions from the default front-end theme into one page template and enables the Drupal Canvas Page Template Component module.

The generated template:

• Becomes the site default.
• Preserves the theme's page and region markup.
• Moves existing region component trees into the corresponding template slots.

Regions belonging to other themes and disabled regions are not migrated.

Global regions fallback

If Canvas cannot resolve a page template and the active theme has enabled global regions, Canvas continues to render those regions. If no enabled global regions exist, Drupal renders the theme's block layout.

Module developers

Code using the Canvas page_region config entity or its HTTP API must migrate to page_variant. The site default page template is stored in canvas.settings:default_page_variant. Canvas pages select a template through the page_variant field, full content templates use the pageVariant property.

Themers

When Canvas renders a page template, its component tree replaces the theme's page.html.twig output and region layout. The theme's html.html.twig still wraps the page. The optional canvas_page_template_component sub-module preserves the theme's existing page and region templates when its component is used in a page template.

Site templates, recipes and distribution developers

Before

Site templates, recipes, and distributions could provide separate canvas.page_region.<theme>.<region> configurations for each theme region.

After

Separate region configs should be replaced with a canvas.page_variant.<id> config entity containing the full-page component tree. Each page template must contain exactly one marker.page_content component. Set canvas.settings:default_page_variant when supplying a site default.

For backward compatibility, installing a site template that still provides global region configuration runs the automatic migration described above. New and updated site templates should provide page variants directly.