Stylesheets and scripts for your site #

This page is for website creators who add their own CSS and JavaScript to a design. In Exponential they are not linked by hand in the pagelayout: they are listed in design.ini and loaded by the ezjscore packer, which combines them, minifies them and gives each version its own file name.

Contents #

1. The lists in design.ini
2. Loading them in the pagelayout
3. The packer
4. After a change
5. Scripts that work under a Content Security Policy
6. Checklist

The lists in design.ini #

In your design extension, settings/design.ini.append.php:

<?php /* #?ini charset="utf-8"?
[ExtensionSettings]
DesignExtensions[]=mysite_design

[StylesheetSettings]
CSSFileList[]=main.css
CSSFileList[]=print.css

[JavaScriptSettings]
JavaScriptList[]=ezjsc::jquery
JavaScriptList[]=main.js
*/ ?>

ezjsc::jquery is ezjscore's own jQuery, so you do not ship a copy. The shipped simple theme is a real example: extension/sevenx_themes_simple/settings/design.ini.append.php.

Loading them in the pagelayout #

{ezcss_load( array( ezini( 'StylesheetSettings', 'CSSFileList', 'design.ini' ),
                    ezini( 'StylesheetSettings', 'FrontendCSSFileList', 'design.ini' ) ) )}
...
{ezscript_load( array( ezini( 'JavaScriptSettings', 'JavaScriptList', 'design.ini' ),
                       ezini( 'JavaScriptSettings', 'FrontendJavaScriptList', 'design.ini' ) ) )}

A template that needs one more file for itself asks for it with {ezcss_require( 'gallery.css' )} or {ezscript_require( 'gallery.js' )}; the pagelayout's ezcss_load/ezscript_load then includes it. The four functions are defined in extension/ezjscore/autoloads/ezjscpackertemplatefunctions.php.

The packer #

The packer is set in extension/ezjscore/settings/ezjscore.ini:

With the packer on, the page links one combined file per list; with it off (development), each file separately, which is easier to debug.

After a change #

Because packed files and the pagelayout's cache blocks remember the old file names, a stylesheet change needs:

php bin/php/ezcache.php --clear-id=ezjscore-packer --allow-root-user
php bin/php/ezcache.php --clear-tag=template --allow-root-user
php bin/php/ezcache.php --clear-id=template-block --allow-root-user

Then reload the page with a hard reload. Do not add ?v=... to links; the modification time in the file name already does that.

Scripts that work under a Content Security Policy #

The shipped policy, when you turn it on for a site, allows script files and stylesheet files of the site itself only (script-src 'self', style-src 'self'): no inline <script> code, no on...= attributes, no style="" (Content Security Policy). Write the site that way from the start:

Checklist #

• To do: Every CSS and JS file is listed in design.ini, none is linked by hand.
• To do: No inline scripts, on... attributes or style="" in your templates.
• To do: The packer is on for production (DevelopmentMode off).
• To do: After a change: packer, template and template-block caches cleared, hard reload.
• To do: Third-party scripts and fonts are reviewed for privacy and allowed in the policy.

Related pages #

• The pagelayout: your site's frame
• ezjscore
• jQuery 4 and the removal of YUI
• Content Security Policy for your code
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.