Design extensions #

This page is for designers who want their design to live in an extension (the normal way) instead of in the kernel's design/ folder. It answers: what makes an extension a design extension, how it is switched on, and what the theme extensions of this installation ship besides their templates.

Contents #

1. Why a design belongs in an extension
2. The one setting: DesignExtensions
3. Activating the extension
4. What a theme extension usually ships
5. The theme extensions of this installation
6. One extension, several designs
7. Checks after activating

Why a design belongs in an extension #

• Upgrades never touch it. The kernel's design/ folder belongs to the product; an upgrade replaces it.
• It travels as one unit. Templates, stylesheets, settings and translations go together in one folder, one Git repository, one Composer package.
• It can be switched on and off. Activating or deactivating the extension adds or removes the design without moving files.

The one setting: DesignExtensions #

An extension's designs are found only when the extension is listed in design.ini [ExtensionSettings] DesignExtensions[]. The extension adds itself, in its own settings/design.ini.append.php. The starter theme's file, extension/cjw_themes_jumper/settings/design.ini.append.php, is the whole example:

<?php /* #?ini charset="utf-8"?
[ExtensionSettings]
# The design "starter" (design/starter/) of this extension
DesignExtensions[]=cjw_themes_jumper
*/ ?>

With that line, every folder extension/cjw_themes_jumper/design/<name>/ becomes a design base for the design <name>. The kernel builds the list in eZTemplateDesignResource::designExtensions() (kernel/common/eztemplatedesignresource.php).

Activating the extension #

An extension is read only when it is active. Two lists in site.ini [ExtensionSettings] decide that:

A theme that only one site uses belongs in ActiveAccessExtensions[] of that siteaccess, so the other sites never search its folders. Activation lines go into the installation's settings/override/site.ini.append.php or a siteaccess's site.ini.append.php, which an administrator edits.

After activating a new extension, regenerate the autoload array if the extension has PHP classes, and clear caches:

php bin/php/ezpgenerateautoloads.php -e
php bin/php/ezcache.php --clear-all

On this installation, ./console exp:velocity deploy runs these steps and reloads PHP.

What a theme extension usually ships #

The metadata files, packaging and release steps are covered in the theme extension pages of this help (Theme extensions: start here).

The theme extensions of this installation #

Each is described on its own page: The media theme, The simple theme, The starter theme, The super theme, The ezwebin design as a base.

One extension, several designs #

A design extension can carry any number of designs: cjw_themes_jumper has design/starter for its own look and design/standard for templates that should be found by every siteaccess whose cascade reaches standard. Use a standard folder in an extension with care: it is searched by every siteaccess that has the extension active and falls back to standard, the administration included.

Checks after activating #

• To do: The extension is active: the administration lists it under Setup > Extensions (or ask your administrator).
• To do: A template of the design shows up: enable ShowTemplatePathComments on a test siteaccess and look at the page source (Debugging a design).
• To do: A stylesheet of the design is in the packed CSS: the browser's network panel shows one packed file from var/<site>/cache/public/stylesheets/ that contains your rules.
• To do: No other siteaccess changed look: open the administration and the other public sites once.

Related pages #

• The design cascade
• The design directory layout
• Tutorial: create a theme extension
• Extension loading order
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.