Page templates

Every page has two templates: a layout — what surrounds the content — and a content template — what is on this page. Both are XML files that place components in containers. A page can also keep its own XML instead of a file.

Where they live

  • Modules ship templates in core/modules/<module>/templates/layout/*.layout.xml and …/templates/content/*.content.xml; the site's own go into site/modules/main/templates/layout/ and …/content/.
  • Setup links them into htdocs/templates/layout/ and htdocs/templates/content/: the core's directly, the site's into a folder main/. After adding a template, run php index.php setup linker from htdocs/.
  • A page keeps the file's path relative to these folders: textblock.content.xml for a core template, main/users.content.xml for a site one.

Layout and content together

The layout's root is <page>, the content template's <content>. If the layout has an empty <content/>, the content template takes its place; otherwise the content follows the layout. The error pages' layout has the placeholder:

<page>
    <component name="langSwitcher" class="Energine\share\components\LangSwitcher"/>
    <content/>
    <component name="footerTextBlock" class="Energine\share\components\TextBlock">
        <params>
            <param name="num">footerTextBlock</param>
        </params>
    </component>
</page>

Inside the root:

  • <component name class> with <params> — see Components.
  • <container name …> groups blocks; all its attributes are copied into the page's XML. The site's stylesheets read html_class (CSS classes), block="alfa" or block="beta" (a block's frame; alfa is the main block and shows the page title, except on the home page), column and widget (columns and blocks of the block editor) and contains (show another container or component here).
  • <translations><translation const="…"/></translations> lists interface strings the view needs, <javascript><behavior name="…"/></javascript> scripts.

A content template's root can also carry segment (fixes the page's address segment), layout (selects the layout), unique (one such page per site) and disabled (not offered). robots.txt is such a page — the seo module's robots_txt.content.xml:

<content segment="robots.txt" layout="empty.layout.xml" unique="">
    <component name="robots" class="Energine\seo\components\Robots"/>
</content>

Choosing the templates of a page

The page form of «Управление структурой» (Structure management, /admin/structure/) has two lists, «Макет страницы» (Page layout) and «Содержимое страницы» (Page content). They show every *.layout.xml or *.content.xml in htdocs/templates/…/ and in its main/ folder — or, if the site has site/modules/main/templates/content.include (or layout.include), only the files its lines match. A template's name in the list is the translation of LAYOUT_<NAME> or CONTENT_<NAME>, such as CONTENT_TEXTBLOCK; a template without one shows the constant itself. A site file with a core file's name replaces it in the list.

A page's own XML

«Управление блоками» (Manage blocks) on the page toolbar moves the page's blocks and saves the result:

  • «Сохранить только для этой страницы» (Save for this page only) keeps the XML in the page itself;
  • «Сохранить в текущем шаблоне» (Save into the current template) copies a core template to site/modules/main/templates/content/ and switches every page that used it to the copy;
  • «Вернуться к шаблону ядра» (Return to the core template) and «Вернуть к начальному виду» (Reset to the initial view) undo these.

Choosing another template in the page form drops the page's own XML for it.

Templates that ship

File In the list On the page
default.layout.xml «Базовый» (Basic) the language switcher, banners, branding, the footer text and the admin toolbar
empty.layout.xml «Пустой» (Empty) nothing around the content
main.content.xml «Главная страница» (Home page) three columns: the main menu, a side text, the sign-in form, a text and the top news
textblock.content.xml «Текстовая страница» (Text page) a text
media_textblock.content.xml «Текстовая страница с медиа-файлами» (Text page with media files) texts and the page's media files
childs.content.xml «Список подразделов» (List of subsections) the page's subpages
map.content.xml «Карта сайта» (Site map) the page tree
login, register, restore_password, user_profile «Авторизация» (Sign-in), «Регистрация» (Registration), «Восстановление пароля» (Password recovery), «Профиль пользователя» (User profile) the user's pages
news.content.xml «Список новостей» (News list) news
feedback_form.content.xml «Форма обратной связи» (Feedback form) a feedback form

The modules' pages — the shop, blogs, forms, mailings — come with templates of their own; the module pages of this documentation name them.