Before you can reference an asset in your code, you have to register an asset, in order for Concrete CMS to know how to include it. Registering an asset can be done easily in a short block of PHP. Let's say we want to register jQuery as an asset in Concrete (note: this is unnecessary, since jQuery ships with Concrete it has already been registered. A full list of pre-registered assets and their handles is available here.
First, we get our Asset List class. This class is a singleton – a single asset list class is available in every part of Concrete, and you can add to or modify it from anywhere. We use getInstance() to get that single instance, rather than create a new one. Our register() call takes three arguments
- The handle we'd like to refer to this asset by ('jquery' in this case.)
- The path or URL to the asset
- An array of options (optional; described later, not pictured here)
- A \Concrete\Core\Package\Package object or package handle (optional; used if the asset is found in a package, not pictured here.)
Concrete includes three asset types that can be called in register()
- css for CSS style sheets.
- css-inline for style elements
- css-localized TBD
The path specified in the register() function is relative to one of the following
- The application/ directory
- The packages/package_handle/ directory (if a package handle or package object is specified as part of the register() method.)
- The concrete/ directory
These three locations are checked in this order. So, in our example, first we'll try and load jquery.js from application/js/jquery.js, then from concrete.js.
You can register an asset from anywhere – your application's custom startup file (application/bootstrap/app.php), a package's on_start() method, a block type's on_start() method, etc…
Registering an asset in a block
Registering an asset in a package.
Registering an asset in a package is very similar – add it to the package controller's on_start() method. Let's say our package handle was "audio_player" and we wanted to register MediaElement.js within it. Add this method to the package controller.php file:
The fourth argument of the register() function is an array of optional parameters. Here are the options, as well as their defaults if not specified.
- local – defaults to true. If false, the exact string will be treated as a URL to a non-local asset.
- version – defaults to false. If specified, this version will be stored against the asset as the numerical version of the asset.
- combine – either true (combine this asset with other assets if asset caching is enabled) or false (do not combine this asset with others). Defaults to -1, which uses the default for the Asset type.
- minify – either true (minify this asset before combining, if asset caching is enabled) or false (do not minify this asset). Defaults to -1, which uses the default for the Asset type.
Registering with Options
Let's take a look at what our Mediaelement.js register() method would look like with some more options relevant to the files: