Loading stylesheets #

This page is for designers who add a stylesheet to a design, or wonder why one is not on the page. It answers: which operator prints stylesheets, where the file lists live, in which order files arrive, and how a single content template can ask for an extra stylesheet.

Contents #

1. The short answer
2. ezcss_load in the pagelayout
3. File lists in design.ini
4. A stylesheet for one kind of page only
5. Order and specificity
6. Media and print
7. What not to do

The short answer #

1. Put the file in design/<yourdesign>/stylesheets/ of your design extension.
2. Name it in the ezcss_load( array( ... ) ) call of your pagelayout's head, or in a design.ini list your pagelayout reads.
3. Clear caches and hard-reload. The file reaches the browser packed with the others (The packer).

ezcss_load in the pagelayout #

The ezjscore extension provides the operators (extension/ezjscore/autoloads/ezjscpackertemplatefunctions.php):

Default media is all and default pack_level 3. Paths are relative to stylesheets/ and found through the design cascade, so 'mytheme.css' finds design/<any design in the chain>/stylesheets/mytheme.css, and 'explayouts_standard/grid.css' finds a file in a subfolder.

The media design's head (pagelayout/head/style.tpl):

{ezcss_load( array( 'inter.css',
                    'explayouts_standard/grid.css',
                    'index.css',
                    'shop.css',
                    'exp-mobile-layout.css' ) )}

(shortened). Use ezcss_load, not ezcss, in the pagelayout: only _load prints what other templates required.

File lists in design.ini #

settings/design.ini [StylesheetSettings] defines lists a pagelayout can read with ezini():

A list only matters if the design's head template reads it. The kernel's design/standard/templates/pagelayout.tpl and the simple design read CSSFileList and FrontendCSSFileList; admin4's page_head_style.tpl reads AdminComponentCSSFileList and BackendCSSFileList; the media design names its files itself. If you want other extensions to be able to add stylesheets to your design, read the lists:

{ezcss_load( array( 'mytheme.css',
                    ezini( 'StylesheetSettings', 'FrontendCSSFileList', 'design.ini' ) ) )}

and an extension then adds one line in its own settings/design.ini.append.php:

[StylesheetSettings]
FrontendCSSFileList[]=myextension.css

A stylesheet for one kind of page only #

A full view template that needs extra CSS asks for it; the pagelayout's ezcss_load prints it:

{* override/templates/full/event.tpl *}
{ezcss_require( array( 'event-calendar.css' ) )}
<article class="event">...</article>

This works because the view runs before the pagelayout. The list travels in the persistent variable, so it also survives the view cache. The visitor downloads the file only on pages that need it; on all other pages it costs nothing.

Order and specificity #

• Files come out in the order of the array; files queued with ezcss_require come after the array.
• Later files win at equal specificity. Put base styles first, then components, then page-specific files, then fixes.
• Duplicates are dropped: a file required twice is printed once.

Media and print #

The second parameter is the media attribute:

{ezcss_load( array( 'mytheme.css' ) )}
{ezcss( array( 'print.css' ), 'print' )}

A print stylesheet is often simpler inside the main file, with @media print { ... } (Print stylesheets).

What not to do #

• No <style> blocks or style="" in templates (No inline CSS).
• No hand-written <link> to /extension/.../stylesheets/x.css: it bypasses the cascade and the packer.
• No ?v= query strings to force reloads (No version queries on asset links).
• No CDN stylesheets without a reason: third-party hosts slow the first paint and must be allowed by the site's Content Security Policy (External resources and CDNs).

Related pages #

• Loading JavaScript
• The ezcss and ezscript operators
• The packer
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.