Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

Theme assets, the packer and CSP

Load a theme's stylesheets, scripts, images and fonts the way Exponential expects - frontend lists, ezcss_load and ezscript_load, the ezjscore packer, ezimage - so they are fast and pass a CSP.

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/extension-development/part-6-theme-developers/theme-assets-the-packer-and-csp.md

On this page

Theme assets, the packer and CSP

Part 6, chapter 6. A theme's look lives in its assets: stylesheets, scripts, images and fonts. This chapter shows how to load each kind so that ezjscore's packer bundles them into few requests, browsers cache them, and a Content Security Policy with 'self' lets them through.

Stylesheets and scripts: lists and loaders

Register files in the theme's design.ini.append.php, by name relative to the design's stylesheets/ or javascript/ folder:

[StylesheetSettings]
FrontendCSSFileList[]=mytheme.css
FrontendCSSFileList[]=mytheme-print.css

[JavaScriptSettings]
FrontendJavaScriptList[]=mytheme.js

The pagelayout loads the lists with ezjscore's template functions:

{ezcss_load( ezini( 'StylesheetSettings', 'FrontendCSSFileList', 'design.ini' ) )}
...
{ezscript_load( array( 'ezjsc::jquery', ezini( 'JavaScriptSettings', 'FrontendJavaScriptList', 'design.ini' ) ) )}
FunctionDoes
ezcss_load( files )prints one <link> for the files given plus any collected with ezcss_require
ezscript_load( files )prints the <script> tags for the files given plus any collected with ezscript_require
ezcss_require( files ), ezscript_require( files )collect files from any template, printed later by the _load call
ezscript( files )prints the script tags right here (used inside page content)

ezjsc::jquery is a packer key: ezjscore resolves it to its jQuery 4 file.

Templates deeper in the page that need a script of their own call ezscript_require, as long as the _load call comes later in the page (at the end of <body>, as above). Inside page content after that point, use ezscript.

The packer

ezjscore's packer combines the listed files into one file per type, optionally minifies them, and writes the result to the site's cache folder (var/<site>/cache/public/). The bundle's name contains a hash and the newest modification time of its files, so a changed file gives a new name and browsers fetch it.

SituationWhat happens
site.ini [TemplateSettings] DevelopmentMode=enabledfiles are served one by one, unpacked: good for debugging
DevelopmentMode=disabled (the default)files are bundled and packed
ezjscore.ini [eZJSCore] Packer=overrides the above when set (disabled, enabled, or a level 0 to 3)

After changing an asset on a site with packing on, clear the caches that hold the packed links, then hard-reload the browser:

php bin/php/ezcache.php --clear-id=template,template-block

Never add ?v= or other version queries to asset links: the packer's names already change.

Images

Reference images through the design chain, so a theme on top of yours can replace them:

<img src={'logo.svg'|ezimage} alt="{ezini( 'SiteSettings', 'SiteName' )|wash}" width="160" height="40">

ezimage finds images/logo.svg in the first design that has it and prints the quoted address. In stylesheets, refer to images relative to the stylesheet (url( ../images/background.webp )); the packer rewrites the paths of bundled stylesheets.

Give every content image width and height (or an aspect ratio in CSS), so the page does not jump while loading.

Fonts

Ship font files in the theme (for example design/mytheme/fonts/) and load them from your stylesheet with @font-face and a relative URL. Loading fonts from a third-party service sends every visitor's address to that service and needs its host in the policy; local files need neither. Check the font's license first: most open fonts use the SIL Open Font License, which allows bundling (Distributing a theme).

The Content Security Policy

A policy with 'self' for scripts and styles allows exactly what the above produces: files from your own site. It refuses:

RefusedInstead
<script> blocks in templatesa file in javascript/, values in data-* attributes
onclick= and other event attributeslisteners in your file
style="" attributes and <style> blocksclasses in your stylesheet
scripts, styles and fonts from other hostslocal files, or the host added to the policy for that siteaccess

The kernel's public siteaccesses have the policy off by default; administrators may turn it on (Content Security Policy). A theme that already works under it is one less obstacle. The conversions are explained in Part 4: inline scripts, event attributes, inline CSS.

A small exception you may need: a script that must run before the page is painted (to apply a saved color scheme, see the next chapter). Make it a tiny file loaded as a normal script in <head>, not an inline script.

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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x