Themes and siteaccesses #

Part 6, chapter 5. A theme does nothing until a siteaccess uses it. This chapter shows the three settings that decide which designs a siteaccess searches, how to build a theme on top of another one, and how to use one theme for several sites with small differences.

The three settings #

In site.ini [DesignSettings], per siteaccess:

For each design name, the folders of the design extensions are searched first, in extension order, then the kernel's own design/<name>/. The full rule, and a way to print the chain a siteaccess uses, are in The design chain.

Two switches that must both be on #

A theme is used when:

1. the extension is active for the siteaccess: in site.ini [ExtensionSettings] ActiveExtensions[] (all siteaccesses) or the siteaccess's ActiveAccessExtensions[]; and
2. the siteaccess names its design in one of the three settings above.

DesignExtensions[] in the theme's own design.ini only makes its folder searchable. Forgetting the second switch is the most common reason a new theme "does nothing"; the RAD wizard's generated README gets this wrong too (A theme with the RAD wizard).

Where to write the siteaccess settings #

./console exp:ini set site.ini/DesignSettings/SiteDesign mytheme siteaccess:mysite
./console exp:ini clear 'site.ini/DesignSettings/AdditionalSiteDesignList[]' siteaccess:mysite
./console exp:ini add 'site.ini/DesignSettings/AdditionalSiteDesignList[]' base siteaccess:mysite

A theme on top of a theme #

Because designs are searched in order, a theme can build on another theme: list the other theme's design in AdditionalSiteDesignList[] after yours.

[DesignSettings]
SiteDesign=mytheme_red
AdditionalSiteDesignList[]
AdditionalSiteDesignList[]=mytheme
AdditionalSiteDesignList[]=base

mytheme_red then needs only the templates and stylesheets that differ: a header, a stylesheet with other colors. Everything else comes from mytheme. This is the cleanest way to make variants, and the way to customize a theme you did not write without forking it (Extending without forking).

One theme, several sites #

An installation often has several public siteaccesses (languages, brands). They can share one theme:

Admin siteaccesses #

Administration siteaccesses use the admin designs (admin4, admin4l, admin). A public theme does not belong in their chain. If your theme's extension also contains templates for the administration (an edit template for a datatype it adds), put them in design/standard/ or design/admin/ of the extension, where every chain finds them, and keep the public look in the theme's own design.

Checking the result #

1. The design chain script of The design chain prints the folders in order for a siteaccess.
2. With ShowUsedTemplates=enabled and the debug output on, each page lists the templates it used and the design each came from.
3. After changing design settings, clear the INI and template caches; a new template file also needs the template-override cache cleared.

Related pages #

• Previous: A theme by hand
• Next: Theme assets, the packer and CSP
• Siteaccess settings
• Settings scopes and their order
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.