Themes are extensions
Part 6, chapter 1. Exponential has no separate "theme" mechanism. A theme is an extension whose main content is a
design folder: extension/<name>/design/<design name>/ with templates, stylesheets, scripts and images. This
chapter explains why that is a good thing, and introduces the three words this part uses all the time.
Three words
| Word | Meaning |
|---|---|
| design | a named set of templates and files, for example simple, standard, admin4. A design name is a folder name under some design/ folder |
| design extension | an extension that contributes design folders, registered in design.ini [ExtensionSettings] DesignExtensions[] |
| siteaccess | one entry point of the installation (a public site, the admin, an editor site), which chooses the designs it uses in site.ini [DesignSettings] |
A theme, then, is a design extension that provides a design for one or more siteaccesses.
Why not edit the kernel's design folders?
The kernel has its own design/standard/, design/admin/ and others. You could put your templates there. Do not:
- Updates overwrite them. The kernel's folders belong to the kernel's releases.
- You cannot tell your files from the kernel's. A year later nobody knows which template you changed.
- You cannot reuse the theme. It is mixed into one installation.
In an extension, the theme has its own folder, its own Git repository, its own version and license, and can be installed into any number of sites with Composer.
A real one
se7enxweb/sevenx_themes_simple is a public theme, and a good one to read. At the top level it has exactly what this book's Part 3 describes for any extension:
sevenx_themes_simple/
composer.json extension.xml ezinfo.php LICENSE
design/simple/ the design "simple"
settings/ design.ini and site.ini additions, and per-siteaccess settings
packages/ content class packages the theme's templates expect
translations/ the theme's interface textsIts settings/design.ini.append.php starts with the line that makes it a design extension:
[ExtensionSettings]
DesignExtensions[]=sevenx_themes_simpleThe next chapter goes through the rest: The anatomy of a design extension.
What a theme can and cannot do
| A theme can | A theme should not |
|---|---|
| replace any template, from the pagelayout to one attribute's view | contain PHP business logic (put that in a separate extension) |
| add view modes and override rules | change kernel settings unrelated to looks |
| bring stylesheets, scripts, fonts and images | ship content; ship content classes as packages instead (sevenx_themes_simple does) |
add template operators it needs (in its own autoloads/) | depend on one particular installation's node IDs |
The last point matters when a theme is shared: a template that fetches node 254 works on your site and nowhere else. Use settings for such values, with a sensible default.
Related pages
- Previous: Part 6: Theme developers
- Next: The anatomy of a design extension
- The design chain
- A design inside an extension
- 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.