A tour of the super theme #

This page is for designers who want to see the smallest complete design extension, or who have just generated one with the design extension wizard. sevenx_themes_super on the demonstration installation is such a generated skeleton (its settings/override.ini.append.php says "Generated by the design extension wizard"). It is not part of the Exponential root package.

Contents #

1. Everything it contains
2. How the parts fit
3. Three lines to correct
4. Growing it into a real theme

Everything it contains #

extension/sevenx_themes_super/
├── composer.json, extension.xml, ezinfo.php, README.md
├── settings/design.ini.append.php        DesignExtensions[]=sevenx_themes_super, CSSFileList[]=site.css, JavaScriptList[]=site.js
├── settings/override.ini.append.php      one example override (full view of class article)
└── design/sevenx_themes_super/
    ├── templates/pagelayout.tpl          the frame
    ├── templates/page_head.tpl           meta tags, title, stylesheets
    ├── templates/page_header.tpl
    ├── templates/page_footer.tpl
    ├── override/templates/full/article.tpl
    ├── stylesheets/site.css
    ├── javascript/site.js
    └── images/                            (empty)

A handful of files: enough to switch a siteaccess to the design and see a page.

How the parts fit #

• pagelayout.tpl prints <html>, includes page_head.tpl in <head>, then page_header.tpl, a <main> element with {$module_result.content}, and page_footer.tpl.

• settings/override.ini.append.php holds one rule:

  [full_article_sevenx_themes_super]
  Source=node/view/full.tpl
  MatchFile=full/article.tpl
  Subdir=templates
  Match[class_identifier]=article

  which shows how an override replaces the full view of one class (Override basics).

• The design is used by a siteaccess once its SiteDesign (or AdditionalSiteDesignList[]) names sevenx_themes_super.

Three lines to correct #

The generated head and frame need three corrections before they work as intended (reported for the wizard):

1. The stylesheets are never printed. page_head.tpl calls {ezcss_require( ezini( 'StylesheetSettings', 'CSSFileList' ) )}. ezcss_require only queues files for a later ezcss_load, and nothing calls ezcss_load. In addition, ezini() without a file name reads site.ini, not design.ini. Use:

   {ezcss_load( ezini( 'StylesheetSettings', 'CSSFileList', 'design.ini' ) )}

2. jQuery and site.js are never printed for the same reason: pagelayout.tpl ends with {ezscript_require( array( 'ezjsc::jquery' ) )}. Put an ezscript_load before </body>:

   {ezscript_load( ezini( 'JavaScriptSettings', 'JavaScriptList', 'design.ini' ) )}

3. The title uses an operator that does not exist. implode_key is not a registered template operator, so the <title> line fails. Build the title with a loop instead:

   <title>{foreach $module_result.path|reverse as $path_item}{$path_item.text|wash}{delimiter} / {/delimiter}{/foreach} - {ezini( 'SiteSettings', 'SiteName' )|wash}</title>

While you are there, write the character set plainly: <meta charset="utf-8">.

Growing it into a real theme #

1. Give it a real name and your own Composer package (see the theme extension pages: Theme extensions: start here).
2. Replace the frame with a pagelayout that has landmarks and a skip link (Landmarks and headings).
3. Add design tokens and a dark mode to site.css (Design tokens).
4. Add override rules per class and view mode (Node templates by class).
5. Add translations for its strings (Tutorial: internationalize a theme).

Related pages #

• Tutorial: create a theme extension
• The pagelayout
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.