Assets
Overview
It is not uncommon for a module to have its own styles and scripts to further enhance the user experience. There are a number of helpers to make adding CSS and Javascript to a module a quick and easy process.
Directory Structure & Files
Assets are stored in the same directory as the module file itself and, while there are no hard rules on the placement and organization of the files, it is highly recommended to follow the structure detailed below as it helps keep both small and large projects clean, organized, and allows for several helper methods (detailed in the "Helpers" section).
All assets are stored within an assets
folder, which is further sub-divided by asset type. The most common types being js
(javascript), css
(cascading stylesheets), and img
(images) but may also contain any other asset such as fonts
, less
, and so on.
/app .. /modules .. .. /{ModuleName} .. .. .. /assets .. .. .. .. /css .. .. .. .. /img .. .. .. .. /js
Helpers
The Hubzero\Module\Module
class brings with it some useful methods for pushing StyleSheets and JavaScript assets to the document. These methods can be called from within the extended helper class or the view itself.
Cascading Stylesheets
The css()
method provides a quick and convenient way to attach stylesheets. For modules, it accepts two arguments:
- The name of the stylesheet to be pushed to the document (file extension is optional). If no name is provided, the name of the module will be used. For instance, if called within a view of the module
mod_tags
, the system will look for a stylesheet namedmod_tags.css
. - The name of the extension to look for the stylesheet. This accepts either module, component or plugin name and will follow the same naming conventions used for extension directories (e.g. "com_tags", "mod_login", etc). Passing an extension name of "system" will retrieve assets from the core system assets (
/core/assets
).
For the defined stylesheet to be found, the assets must be organized as described in the "Directory Structure & Files" section.
Method chaining is also allowed.
<?php // Push a stylesheet to the document $this->css() ->css('another'); ?> ... view HTML ...
Javascript
Similarly, a js()
method is available for pushing javascript assets to the document. The arguments accepted are the same as the css()
method described above.
<?php // Push some javascript to the document $this->js() ->js('another'); ?> ... view HTML ...
Images
Finally, a img()
method is available for building paths to images within the module's assets
directory. Unlike the css()
and js()
methods, this helper does not add anything to the global document object and, instead, simply returns an absolute file path.
Given the following directory structure:
/app .. /modules .. .. /{ModuleName} .. .. .. /assets .. .. .. .. /img .. .. .. .. .. picture.png
From a component view:
<!-- Generate the path to the image --> <img src="<?php echo $this->img('picture.png'); ?>" alt="My picture" />