Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

The design cascade

The exact order in which Exponential searches designs and extensions for a template, stylesheet or image, with a worked example from this installation and the caches that hold the result.

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/designers/theme-design/the-design-cascade.md

On this page

The design cascade

This page is for designers who want to know exactly which file wins when the same template or stylesheet exists in several places. It answers: in what order the kernel searches, how extensions fit in, how to predict the winner, and which caches remember the result.

Contents

  1. The rule in one sentence
  2. Step 1: the list of designs
  3. Step 2: each design in each extension
  4. A worked example
  5. What the cascade is used for
  6. Overrides come before the cascade
  7. The caches of the cascade
  8. Rules of thumb

The rule in one sentence

The kernel builds an ordered list of design bases (folders) and takes a file from the first base that has it. The code is eZTemplateDesignResource::findDesignBase() in kernel/common/eztemplatedesignresource.php.

Step 1: the list of designs

The design names come from site.ini [DesignSettings] of the current siteaccess:

  1. SiteDesign,
  2. every entry of AdditionalSiteDesignList[], in order,
  3. StandardDesign (default standard).

Duplicates are removed (array_unique), so listing standard in AdditionalSiteDesignList[] as well does no harm; its first position counts.

Step 2: each design in each extension

For each design name in that list, the kernel adds:

  1. extension/<extension>/design/<design> for every extension in design.ini [ExtensionSettings] DesignExtensions[], in the order of that list, if the folder exists;
  2. then the kernel's own design/<design>, if it exists.

So the extensions are searched before the kernel within each design name, and a design name higher in the list always beats a lower one, wherever it lives.

DesignExtensions[] is filled by the extensions themselves: each theme extension has a settings/design.ini.append.php with DesignExtensions[]=<its own name>. Its position in the list follows the order in which extensions are loaded (see Extension loading order).

A worked example

The siteaccess site of this installation sets SiteDesign=media and AdditionalSiteDesignList[] ezwebin, standard, base. With the theme extensions active, the bases for a lookup look like this (only folders that exist are kept):

#BaseWhy
1extension/sevenx_themes_media/design/mediadesign media, extension copy
2extension/ezwebin/design/ezwebindesign ezwebin, extension copy
3extension/<ext>/design/standard for every extension that has one (explayouts, ezjscore, ezoe ...)design standard, extension copies
4design/standarddesign standard, kernel copy
5design/basedesign base, kernel copy

Now the template node/view/line.tpl:

  • if media has templates/node/view/line.tpl, base 1 wins;
  • if not, but ezwebin has it, base 2 wins;
  • otherwise the kernel's design/standard/templates/node/view/line.tpl is used.

The same search runs for stylesheets/index.css (through ezcss_load) and for images/logo.png (through ezimage).

What the cascade is used for

Kind of fileFolder inside a baseLooked up by
Templatestemplates/{include uri='design:...'}, view templates, the pagelayout
Override templatesoverride/templates/override.ini MatchFile=
Stylesheetsstylesheets/ezcss, ezcss_load, ezcss_require, ezcssfiles
Scriptsjavascript/ezscript, ezscript_load, ezscript_require, ezscriptfiles
Design imagesimages/ezimage
Any design filethe path you giveezdesign (for example 'stylesheets/print.css'|ezdesign)

Overrides come before the cascade

When a template is requested, the kernel first checks the override rules of override.ini for that template. If a rule matches the current page (class, node, view mode ...), its MatchFile is used, searched under override/templates/ through the same bases. Only when no rule matches is the cascade's plain copy used. See Override basics.

The caches of the cascade

CacheWhen it mattersHow to clear
In-memory list per requestalwaysnothing to do
Design base list on diskonly with site.ini [DesignSettings] DesignLocationCache=enabled (default disabled)php bin/php/ezcache.php --clear-id=design_base
Template override cacheafter adding a template in a design or a rule in override.iniphp bin/php/ezcache.php --clear-id=template-override
Compiled templatesafter editing templates, when template compilation caches are kept--clear-id=template
INI cacheafter changing site.ini or design.ini--clear-tag=ini

Tip

A new template file that seems to be ignored is almost always the template override cache. A page that renders with an empty content area right after you added templates is the same cause. Clear template-override first.

On this installation, deploys clear these caches through ./console exp:velocity deploy (template, template-override, translation and design_base caches are among its steps).

Rules of thumb

  • Put a file in your design only when it differs. Everything else falls through to the designs below.
  • Do not edit design/standard or another shipped design. Copy the template into your own design at the same path and change the copy. An upgrade then never overwrites your work.
  • Keep the fallback list short and intentional. Each extra design is one more folder searched, and one more place a surprising template can come from.
  • Name the path, not the design, in templates. Write {include uri='design:parts/menu.tpl'}, never a path with a design name in it; the cascade picks the right copy.

Become an Exponential Partner

Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x