Lesson 3.1: The design chain
A template is not looked up in one folder but in a chain of designs: the site design first, then the additional
designs, then standard. Knowing the chain explains why a template you change has no effect, and where your own
templates must go. In this lesson learners read the chain of their siteaccess and add their extension's design
folder to it.
At a glance
| Course | Developers |
| Module | Module 3: Designs, overrides and debugging |
| Duration | 45 minutes (15 presenting, 30 exercise) |
| Level | Intermediate |
| Audience | Developers and template builders |
| Prerequisites | Module 2 |
Learning objectives
After this lesson, learners can:
- name the order in which a template is searched: overrides, site design, additional designs,
standard; - find the site design and additional designs of a siteaccess with
exp:ini whereandexp:ini get; - explain what a design folder holds (
templates/,override/templates/,stylesheets/,images/,javascript/); - add an extension's design folder to the chain with
DesignExtensions[]and switch the extension on.
Trainer's notes
How to present it
Sources: Templates and design, parts 1 and 2 and Extension loading order.
- The lookup (4 minutes). For a template such as
node/view/full.tpl, the first file found wins:- override templates whose rules in
override.inimatch (lesson 3.2); templates/of the site design;- the same of the additional designs;
design/standard/templates/, the fallback, never edited.
- override templates whose rules in
- The settings (3 minutes).
site.ini [DesignSettings]:SiteDesign,AdditionalSiteDesignList[]andStandardDesign=standard. Each siteaccess sets its own insettings/siteaccess/<sa>/site.ini.append.php. - Where designs live (3 minutes). In
design/<design>/of the installation or inextension/<name>/design/<design>/. An extension's design folders join the chain when the extension is active and itssettings/design.ini.append.phpsays[ExtensionSettings] DesignExtensions[]=<name>. - Order between extensions (3 minutes). An extension loaded earlier wins for templates and settings. Show
exp:ini get site.ini/ExtensionSettings/ActiveExtensions. - Site versus admin designs (2 minutes). The administration siteaccess has its own design (
admin4on new installations, withadmin3and others available); site templates never affect it, and the other way round.
Common questions
Why not edit design/standard/? It is the kernel's fallback design and is replaced at every update. Put your
template in your own design folder.
Can one siteaccess use the design of another? Yes: list it in AdditionalSiteDesignList[]. Many sites share a
base design that way.
What is design_base in the cache list? The cached list of design folders; clear it with
php bin/php/ezcache.php --clear-id=design_base after adding a design folder.
Pitfalls
- Wrong design name. A folder
extension/mysite_hello/design/mysite/does nothing unlessmysiteis the site design or an additional design of the siteaccess. Use the nameexp:ini whereprinted. - Extension not active.
DesignExtensions[]is read only from active extensions. - Stale caches. New template paths need the
template-override,design_baseand template caches cleared.
Hands-on exercise
On the development installation. Use the name of your public siteaccess (for an exp:install default, site)
where the steps say <sa>.
Find the site design:
php bin/php/console exp:ini where site.ini/DesignSettings/SiteDesign <sa>.List the additional designs:
php bin/php/console exp:ini get site.ini/DesignSettings/AdditionalSiteDesignList <sa>.Write the chain on paper: site design, additional designs,
standard.Find where the site design's folder is:
ls -d design/<design> extension/*/design/<design> 2>/dev/null.Create the design folder of your extension, using the site design's name:
mkdir -p extension/mysite_hello/design/<design>/templates mkdir -p extension/mysite_hello/design/<design>/override/templates mkdir -p extension/mysite_hello/settingsRegister the design and switch the extension on (module 7 explains both in depth):
php bin/php/console exp:ini add design.ini/ExtensionSettings/DesignExtensions mysite_hello extension:mysite_hello php bin/php/console exp:ini add site.ini/ExtensionSettings/ActiveExtensions mysite_hello global php bin/php/ezcache.php --clear-tag=ini php bin/php/ezcache.php --clear-id=design_baseCheck that the extension is listed:
php bin/php/console exp:ini get site.ini/ExtensionSettings/ActiveExtensions.Copy the kernel's line view into your design:
mkdir -p extension/mysite_hello/design/<design>/templates/node/viewandcp design/standard/templates/node/view/line.tpl extension/mysite_hello/design/<design>/templates/node/view/.Add a visible line
<p>mysite_hello line view</p>at the top of the copy, clear the template caches (php bin/php/ezcache.php --clear-tag=templateand--clear-id=template-override), and open a page that lists items in the line view. If the site design or an override already providesline.tpl, your copy is not used: note which file answers instead (lesson 3.4 shows how).Commit the new files in the extension's repository.
Expected result
- Step 1 lists
settings/site.iniand the siteaccess file, ending withIn effect:and the design name. - Step 6 created
extension/mysite_hello/settings/design.ini.append.phpand added a line tosettings/override/site.ini.append.php. - Step 9: either the line appears in lists, or the learner can name the file that answered first and why.
- The trainer checks each learner's written chain from step 3.
Quiz
- In which order are designs searched for a template?
- Which setting names the extensions whose design folders join the chain?
A.
ActiveExtensions[]B.DesignExtensions[]C.AdditionalSiteDesignList[]D.StandardDesign - What does
StandardDesign=standardmean? - Your copy of
line.tplhas no effect. Name two possible reasons. - True or false: the admin siteaccess uses the same design chain as the public site.
Answers
- Matching overrides, the site design, the additional designs in their order, then
standard. - B.
[ExtensionSettings] DesignExtensions[]in the extension'sdesign.ini.append.php; the extension must also be active. standardis the fallback design, searched last.- The design folder name is not in the siteaccess's chain; the extension is not active; an override or an earlier design provides the template; caches were not cleared.
- False. Each siteaccess has its own
[DesignSettings].
Further reading
- Templates and design: finding the design, overrides, debugging.
- Extension loading order: which extension wins.
- Registering the design: the same steps for a theme.
- Additional extension directories: extensions
outside
extension/.
Related pages
- Module 3: Designs, overrides and debugging
- Developers: course overview
- Trainers: start here
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
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.