Tools for theme designers
This page is for theme designers who want to know which tools exist, inside Exponential and around it, and which settings a developer switches on for them. Most of these are development settings: they belong on a development or preview siteaccess, never on the live site. Each row links to the page that explains it in depth.
Contents
- Seeing which template drew what
- The debug output
- Packed or unpacked stylesheets
- Trying a design next to the live one
- Tools in the administration
- Browser tools
- Tools for checking quality
- Which setting goes where
Seeing which template drew what
Setting (site.ini, [TemplateSettings]) | What you see | Page |
|---|---|---|
ShowTemplatePathComments=enabled | every rendered template wrapped in <!-- START ... --> and <!-- STOP ... --> comments with its path; works with the template compiler on | Template path comments |
Debug=enabled with ShowXHTMLCode=enabled | the older template debug markers in the page | Template debugging |
ShowUsedTemplates=enabled (needs the debug output) | a table of all templates used for the page | Debugging a design |
The settings file itself warns that these add markup to every output, including mails, JSON and feeds. Use them on a development siteaccess only.
The debug output
[DebugSettings] DebugOutput=enabled adds a report below the page with errors, warnings, timings and, with the setting
above, the templates used. It can be limited to certain addresses (DebugByIP with DebugIPList[]). Warnings about
missing templates or unknown operators are often the answer to "why does my change not show"
(Debugging a design).
Packed or unpacked stylesheets
In normal operation, ezjscore packs the stylesheets and scripts of a page into cached files. While working on a design,
unpacked files are easier to read in the browser's style inspector. The packer follows
[TemplateSettings] DevelopmentMode by default, and can be set explicitly with [eZJSCore] Packer in ezjscore.ini
(the settings comment says it accepts enabled, disabled or a level from 0 to 3). After a stylesheet change on a
site with packing on, the packed file must be renewed; a developer does that with the deploy steps
(The packer cache and deploys). Packed file names already carry
the modification time, so never add ?v= to a link.
Trying a design next to the live one
A preview siteaccess serves the same content with your design, at its own address, while visitors keep the live design. It is the right place for reviews (Previewing a design on a siteaccess).
Tools in the administration
| Tool | Where | Use |
|---|---|---|
| Template editor | Design tab, Template Editor | see a siteaccess's templates and their overrides in order; quick edits on a test site (The template editor) |
| Design extension wizard | Setup > RAD, /setup/designextension | generate a complete theme extension to start from (The design extension wizard) |
| Layouts editor | Layouts | build test layouts with every block view type (The layouts editor) |
| Class definitions | Setup > Classes | read fields for the mapping sheet |
Changes made in the template editor live only on that installation; a theme belongs in files under version control.
Browser tools
The browser's developer tools do most of the visual work:
- the element inspector, with template path comments visible in the DOM;
- device emulation at 375 px, and real zoom at 200% (Testing at zoom levels);
- color scheme emulation (light and dark) and reduced motion emulation;
- color-vision deficiency emulation;
- the network panel for requests to other hosts and the performance audit for LCP and CLS (Designing for performance budgets);
- the console, to see Content Security Policy violations (Checklist: CSP).
Tools for checking quality
| Check | Tool | Page |
|---|---|---|
| Contrast | any contrast checker; the ratios written into the palette sheet | Color contrast |
| Accessibility | the browser's accessibility tree and an automated checker, plus keyboard and screen reader by hand | Checklist: accessibility |
| Visual changes between releases | screenshots in light, dark and at zoom, compared | Visual regression checks |
| Template syntax | the template check command a developer runs | Template debugging |
| Admin styling rules | the design test in the test suite | The admin styling rules test |
Which setting goes where
Development settings go in the development siteaccess's site.ini.append.php or in a settings override of the
development installation, set by the developer or administrator. They never go into your theme extension, because a
theme that switches on debug output would switch it on for every site that installs it
(The design settings a theme ships).
Related pages
- Debugging a design
- Lesson 1.3: Which template wrote this markup?
- Caching for designers
- 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.