Templates

Templates define project rendering and frontend presentation behavior. A template is a package that provides the visual layer for a project and can add settings, layouts, zones, frontend assets, and rendering behavior.

Use a template package when a project needs its own page structure, CSS, JavaScript, layouts, template events, or presentation settings. Use a normal module when the package only adds business logic, backend controls, console commands, events, or XML configuration that is not the project's visual layer.

Package Type

Template packages use the Composer type:

{
  "name": "vendor/template-example",
  "type": "quiqqer-template",
  "require": {
    "php": "^8.1",
    "quiqqer/core": "^2"
  }
}

Use quiqqer-template only when the package provides the visual presentation for a project. Use quiqqer-module for normal extension packages.

See First Module for the basic package setup and composer.json for package metadata.

Projects, Sites, And Templates

A project selects the template package used for frontend rendering. Sites inside that project provide the page content, the selected layout, and site-specific attributes.

During rendering, the template receives the current project and site context. The template decides how global page parts are rendered and where the current site layout is inserted:

<main class="main-contentWrapper">
    {$Template->getLayout()}
</main>

Use project or template settings for global presentation defaults. Use site-specific settings and attributes when editors should be able to adjust a single page, for example header visibility, a custom page class, a page layout, or navigation behavior.

Package Structure

A template package commonly contains:

vendor/template-example/
├─ composer.json
├─ locale.xml
├─ package.xml
├─ settings.xml
├─ site.xml
├─ events.xml
├─ bin/
│  ├─ css/
│  ├─ img/
│  └─ init.js
├─ layout/
│  ├─ noSidebar.html
│  ├─ leftSidebar.html
│  └─ rightSidebar.html
├─ template/
│  ├─ page.html
│  ├─ footer.html
│  ├─ scripts.html
│  └─ head/
└─ src/

Not every template needs every file. Start with the package metadata, translations, one layout, and the templates required by the project.

Package Metadata

Use package.xml for the package title, description, logo, previews, support links, and license information. Title and description should reference locale.xml.

Template packages can provide preview images for the administration interface:

<quiqqer>
    <package>
        <title>
            <locale group="vendor/template-example" var="package.title"/>
        </title>

        <description>
            <locale group="vendor/template-example" var="package.description"/>
        </description>

        <image src="URL_OPT_DIR/vendor/template-example/bin/img/logo.png"/>

        <preview>
            <image src="URL_OPT_DIR/vendor/template-example/bin/img/preview/home.jpg"/>
        </preview>
    </package>
</quiqqer>

Use URL_OPT_DIR for browser-accessible package assets.

See package.xml and Localization.

Layouts And Templates

The layout/ directory contains page layout files. A layout defines how the page content area is arranged, for example with no sidebar, a left sidebar, or a right sidebar.

The template/ directory contains reusable template parts such as page wrapper, header, navigation, footer, scripts, and head assets. Keep layout files focused on page structure and move shared rendering into template/ files.

Template files can use Smarty template syntax and QUIQQER template helpers. For example, a page wrapper can fetch shared partials and expose template event positions:

{template_event name="vendor::template::body::beforeMain" Template=$Template}

<div class="main-contentWrapper">
    {$Template->getLayout()}
</div>

{template_event name="vendor::template::body::afterMain" Template=$Template}

Use template events when other packages should be able to extend the output without editing the template package.

Frontend Assets

Put browser-accessible assets below bin/, for example CSS, JavaScript, fonts, images, and preview images.

Typical asset paths:

bin/css/style.css
bin/img/logo.png
bin/img/preview/home.jpg
bin/init.js

Reference assets through package URLs, not through Core paths:

<link href="{$Template->getTemplateUrl('bin/css/style.css')}" rel="stylesheet">

getTemplateUrl() resolves the asset URL for the active template package and can fall back to a template parent when the file is not present in the current template. This is the preferred pattern for template assets that may be overridden by a derived template.

Use URL_OPT_DIR for static XML metadata such as package images and previews:

<image src="URL_OPT_DIR/vendor/template-example/bin/img/logo.png"/>

Build tools are package-specific. A template can use its own CSS or JavaScript build workflow, but QUIQQER does not require a global frontend build standard for all template packages.

Project And Site Settings

Templates can define configuration for projects and sites.

Use settings.xml for package or project-wide settings such as colors, layout defaults, navigation behavior, footer behavior, or feature toggles.

Use site.xml when the template needs site attributes or site editor settings. Common examples are page header behavior, custom CSS classes, navigation overrides, or site-specific presentation options.

Site settings should use package-scoped configuration names:

<attribute>templateExample.showHeader</attribute>
<attribute>templateExample.pageCustomClass</attribute>

See settings.xml and site.xml.

Template Overrides

Keep project-specific changes in a template package instead of modifying Core or another installed template directly.

For small visual changes, prefer configurable settings and CSS variables. For structural changes, create or extend a template package and override only the files that need different behavior.

Common override points are:

• layout files below layout/
• shared template partials below template/
• CSS, JavaScript, images, and fonts below bin/
• template settings exposed through settings.xml
• site-specific presentation options exposed through site.xml

When a template builds on another template, keep filenames and paths stable so fallbacks and overrides stay predictable. If a file is copied only to change a small detail, check whether a setting, CSS variable, or template event would be cleaner.

Events

Template packages can react to lifecycle and rendering events with events.xml. Common use cases are:

• initialize template variables during Smarty setup
• react when project configuration changes
• react when site configuration changes
• prepare template-specific data during package setup

Example:

<events>
    <event on="onSmartyInit" fire="\Vendor\TemplateExample\EventHandler::onSmartyInit"/>
    <event on="onSiteSave" fire="\Vendor\TemplateExample\EventHandler::onSiteSave"/>
</events>

See events.xml and Events.

Practical Checklist

Before handing over a template package:

• Use quiqqer-template as Composer type.
• Provide locale.xml with package title, description, and visible labels.
• Reference package images and CSS through URL_OPT_DIR.
• Keep browser assets below bin/.
• Keep layouts in layout/ and shared partials in template/.
• Use settings.xml and site.xml for configurable behavior.
• Avoid changing Core files for template-specific behavior.
• Run the package's PHPCS and PHPStan tools if configured.