Documentation

Assets

Download (pdf)

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:

  1. 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 named mod_tags.css.
  2. 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" />

Last modified: