Documentation

Assets

Download (pdf)

Overview

Although less common than components or modules, sometimes a module to plugin has need for 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 the document a quick and easy process.

Directory Structure & Files

Assets are stored in the same directory as the plugin 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
.. /plugins
.. .. /{PluginType}
.. .. .. /{PluginName}
.. .. .. .. /assets
.. .. .. .. .. /css
.. .. .. .. .. /img
.. .. .. .. .. /js

Helpers

The Hubzero\Plugin\Plugin class brings with it some useful methods for pushing StyleSheets and JavaScript assets to the document as well as building paths for images. These methods can be called from within the extended helper class or a plugin view.

Cascading Stylesheets

The css() method provides a quick and convenient way to attach stylesheets. 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 plugin will be used. For instance, if called within a view of the members plugin profile, the system will look for a stylesheet named profile.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 plugin'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
.. /plugins
.. .. /{PluginType}
.. .. .. /{PluginName}
.. .. .. .. /assets
.. .. .. .. .. /img
.. .. .. .. .. .. picture.png

From a view within the plugin:

<!-- Generate the path to the image -->
<img src="<?php echo $this->img('picture.png'); ?>" alt="My picture" />

Last modified: