Static resources

Static resources#

We often want to ship a website with a static resource, such as an image, icon, CSS, or JavaScript file. For CSS and JavaScript files, we can use the resource registry to register, then deliver, them to the client browser.

The resource registry provides a programmatic way, either in code or through the web, to extend and configure the dependencies between static resources. It also automatically manages caching of static resources. If you were to hard-code these resources in templates with <link> or <script> tags, you would not have these advantages.

See also

For some additional implementation information, see Theme.

Registering JavaScript and CSS#

To register a static resource in Plone 6, we need to use the plone.base.interfaces.resources.IBundleRegistry interface.

The following example registers a JavaScript resource in browser/profiles/default/registry of your Plone 6 project. The JavaScript files have to be in the browser/static folder of your Plone 6 project.

<registry>
  <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/jscript">
    <value key="enabled">True</value>
    <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
    <value key="load_async">False</value>
    <value key="load_defer">False</value>
    <value key="depends">plone</value>
  </records>
</registry>

You can register a CSS resource in the same way.

    <registry>
    <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
      <value key="enabled">True</value>
      <value key="csscompilation">++plone++myproject.site/style.min.css</value>
      <value key="depends">plone</value>
    </records>
  </registry>

You can also register both a JavaScript file and a CSS file in the same bundle.

<registry>
  <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
    <value key="enabled">True</value>
    <value key="csscompilation">++plone++myproject.site/style.min.css</value>
    <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
    <value key="load_async">False</value>
    <value key="load_defer">False</value>
    <value key="depends">plone</value>
  </records>
</registry>

Available attributes#

The following attributes are available for registering a static resource.

enabled

Boolean. Whether the bundle is enabled or not. If it is disabled, the bundle will not be loaded.

jscompilation

String. The path to the compiled JavaScript file.

csscompilation

String. The path to the compiled CSS file.

depends

String. A comma-separated list of bundles that this bundle depends on. For a single dependency, do not insert commas.

When a bundle depends on another one, its <script> or <link> tag is rendered after the bundle it depends on.

If the bundle's dependencies do not exist, then the bundle will not render.

The depends attribute may be assigned the value of all, making this bundle render last, after all other bundles. The all value lets you load CSS files after the automatically added theme resources and override CSS declarations from your own custom CSS files.

If you set multiple bundles to all, then these bundles will render in alphabetical order by its name.

Note

You can also add custom CSS through-the-web via the Theming control panel, under Site Setup ‣ Theming ‣ Advanced settings ‣ Custom Styles. Setting depends to all does not affect custom CSS that you define in the Theming control panel, which always renders as the last style resource. It only affects bundles, not control panel settings.

Added in version Plone: 6.0.14

depends value of all.

load_async

Boolean. Whether the bundle should be loaded asynchronously or not. Only JavaScript

load_defer

Boolean. Whether the bundle should be loaded deferred or not. If you use load_async, this attribute has no effect. Only JavaScript

Contents