Assets

cms_system includes an assets library for handling CSS, JavaScript, and image assets.
Additional information may be available in the section on working with assets

Configuration

The Assets library can be configured by setting several values in /application/config/application.php.

assets.directories

This setting allows configuration of the directories which contain the various assets.
- The 'base' directory is relative to the public directory.
- All other directories are relative to the base directory, except 'module'.
- 'module' defines a directory name within both 'css' and 'js'.

For example, the default configuration (below) defines the location for CSS files as /public/assets/css/.

$config['assets.directories'] = array(
    'base'   => 'assets',
    'cache'  => 'cache',
    'css'    => 'css',
    'image'  => 'images',
    'js'     => 'js',
    'module' => 'module',
);

Trailing and preceding slashes in any of the values will be removed by the library.

assets.js_opener

This setting allows configuration of the line used to prefix inline JavaScript added by the Assets library.
The default setting is configured to leverage jQuery's "document ready" state:

$config['assets.js_opener'] = "$(document).ready(function() {";

This works in conjunction with assets.js_closer.

assets.js_closer

This setting allows configuration of the line appended to the end of any inline JavaScript added by the Assets library.
The default setting is configured to leverage jQuery's "document ready" state:

$config['assets.js_closer'] = "});";

This works in conjunction with the default value of assets.js_opener.

The result of the default values of assets.js_opener and assets.js_closer will look something like this when output on the page:

<script type='text/javascript'>
$(document).ready(function() {
// Inline JavaScript will be placed here...
});
</script>

assets.css_combine

This boolean setting determines whether the Assets library will automatically combine CSS files before output.
- If true, the library will combine the CSS files to generate a single file and output a link element with the href attribute set to the combined file.
- If false, the library will output a series of links to the individual CSS files.

$config['assets.css_combine'] = false;

Currently, this setting does not change the behavior of the library when dealing with module files, which are always combined.

assets.js_combine

This boolean setting determines whether the Assets library will automatically combine JS files before output.
- If true, the library will combine the JS files to generate a single file and output a script element with the src attribute set to the combined file.
- If false, the library will output a series of script elements for the individual JS files.

$config['assets.js_combine']  = false;

Currently, this setting does not change the behavior of the library when dealing with module files, which are always combined.

assets.css_minify

This boolean setting determines whether the Assets library will automatically minify CSS files before output.
- If true, the library will minify the CSS files (or look for previously minified versions of the CSS files by checking for '.min' between the filename and the '.css' extension) and output a link element with the href attribute set to the minified file.
- If false, the library will output the CSS file without performing minification.

$config['assets.css_minify'] = true;

assets.js_minify

This boolean setting determines whether the Assets library will automatically minify JS files before output.
- If true, the library will minify the JS files (or look for previously minified versions of the JS files by checking for '.min' between the filename and the '.js' extension) and output a script element with the src attribute set to the minified file.
- If false, the library will output the JS file without performing minification.

$config['assets.js_minify']  = true;

assets.encrypt_name

This boolean setting determines whether the Assets library will use PHP's md5() function to encrypt the name of any files generated by the library (when combining asset files).
Since the naming scheme used when generating the combined files may reveal some of the app's underlying structure, some people may prefer to obscure this information by encrypting the filenames.
- If true, the library will encrypt the filename.
- If false, the files will be named in the format theme_module_controller.

$config['assets.encrypt_name'] = false;

assets.encode

Specify whether assets should be encoded based on the HTTP_ACCEPT_ENCODING value.

This setting appears to be ignored.

$config['assets.encode'] = false;

Deprecated Assets Configuration Entries

The following items are deprecated and should no longer be used.
They are included here primarily as a reference for users upgrading their configuration files from previous versions of cms_system.

assets.base_folder Deprecated

Use the 'base' key in assets.directories.

assets.asset_folders Deprecated

Use the same keys in assets.directories.

CSS Methods

add_css($style[, $media = 'screen'[, $prepend = false]])

Add a file (or files) to the internal list of stylesheets to be output by the css() method.

  • $style: The name of a file or an array of filenames to be added.
  • $media: The value of the media attribute to be used in linking the file(s).
  • $prepend: If true, the file(s) will be added to the beginning of the list. Defaults to false.

add_module_css($module[, $path = null[, $media = 'screen']])

Add CSS file(s) from a module to the internal list of stylesheets to be output by the css() method.

  • $module: The name of the module.
  • $path: The name of a file or an array of filenames to be added.
  • $media: The value of the media attribute to be used in linking the file(s).

css([$style = null[, $media = 'screen'[, $bypassInheritance = false[, $bypassModule = false]]]])

Renders link(s) to stylesheets.

  • $style:

    • If $style is a string containing a filename, a link element is created and returned for that file.
    • If $style is an array containing one or more filenames, they are added to the internal list of styles, which is then processed and returned as a series of link elements.
    • If $style is empty, the internal list of styles is processed and returned as a series of link elements. Additionally, if $globals is true, it will look for a file with the same name as the current value of $media, and, if found, add that to the list.

  • $media:
    The value to assign to the media attribute in the generated link element(s).

  • $bypassInheritance:

    • If false (default), the library will check both the parent theme and the current theme for files with the requested name. If the file is found in multiple themes, they will all be loaded (files in the non-themed assets directories will only be loaded if not found in any of the themes).
    • If true, the library will only check the current theme (and the non-themed assets directories if the file can't be found in the theme).

  • $bypassModule:

    • If false (default), a CSS file named after the controller and any styles added via add_module_css() will be included in the list of styles to be processed.
    • If true, the controller and module files will not be returned.

If the .css extension is not included on any of the filenames processed by this method, it will be added.

If assets.css_combine is true, the CSS files will be combined and a single link will be returned for all of the styles (except module styles, which will be combined into a second link).
Module styles are currently combined regardless of the value of assets.css_combine, though they will not be included if $bypassModule is true.

combine_css($files[, $media = 'screen'[, $type = '']])

While primarily used internally by the css() method, the combine_css() method may also be called directly to combine multiple CSS files into a single file and return a link element for the generated file.

  • $files: an array of file arrays. Each file array contains the file path, media type, and server path for the represented file.
  • $media: The value of the media attribute placed on the generated link element.
  • $type: If set to 'module', the generated filename is changed to indicate this is a combination of module styles. Other values are ignored.

If combine_css() detects that there are no files to combine, it returns nothing.

The generated filename for the combined file will be in the format: {theme}{module}{class}_combined
- If it is a module file, 'combined' will be replaced with 'mod'.
- If assets.encrypt_name is true, the filename will be passed through PHP's md5() function.
- If assets.css_minify is true, '.min' will be added to the filename.
- Finally, the '.css' suffix will be appended to the filename and the file will be placed in the directory indicated by assets.base_folder/assets.directories['cache'].

If the file is successfully generated, combine_css() will return a string containing a link element pointing to the generated file.
If an error occurred while generating the file, an empty string will be returned.

JavaScript Methods

add_js($script[, $type = 'external'[, $prepend = false]])

Add script(s) to the internal list of scripts to be output by the js() method.

  • $script: The name of a file, an array of filenames, or the body of a script element to be added to the list.
  • $type: The type of script element to be added to the list:

    • 'external': The script is contained in a file (or files) with the name(s) given in $script.
    • 'inline': The body of the script is given by $script.
  • $prepend: Add the script to the beginning (if true) or the end (if false, which is the default) of the list.

'inline' scripts will have the text from 'assets.js_opener' prepended to them and the text from 'assets.js_closer' appended.

add_module_js($module, $file)

Add script(s) from a module to the internal list of scripts to be output by the js() method.

  • $module: The name of the module.
  • $file: The name of a file or an array of filenames of the script(s) to be added to the list.

js([$script[, $type = 'external']])

Returns the script tag(s) for the internal list of scripts or a single script.

  • $script:

    • If $script is empty, the script elements are generated for the internal list of scripts and returned.
    • If $script is an array, the scripts are added to the internal list of scripts before generating and returning the script elements.
    • If $script is a non-empty string:

      • If $type is 'external', a single script tag is generated for $script and returned.
      • Otherwise, $script is added to the list as an 'inline' script, then all of the script elements are generated and returned.
  • $type: Ignored unless $script is a string. See above for behavior when $script is a non-empty string.

external_js([$extJs = null[, $list = false[, $addExtension = true[, $bypassGlobals = false]]]])

While primarily used internally by the js() method, the external_js() method may be used to generate the script elements for JavaScript files.

  • $extJs:

    • If $extJs is empty, script elements will be generated and returned for the JS files in the internal list of scripts.
    • If $extJs is a filename or an array of filenames, links will be created only for the requested files, and the internal list will be ignored (for this call only).
  • $list:

    • If true, the output will be a comma-separated list of filenames, with each filename in double-quotes (this is primarily intended for passing the list of files to a third-party script loader).
    • If false (default), the output of this method will be a string containing script elements referencing the external js files.
  • $addExtension:

    • If true (default), the '.js' extension will be added to any filename which does not already contain it.
    • If false, the '.js' extension will not be added (for example: echo Assets::external_js('//www.google.com/jsapi', false, false, true); will output a single script tag with the value of the src attribute set to '//www.google.com/jsapi', while most other methods of adding this script in the Assets library will result in the src attribute being set to '//www.google.com/jsapi.js').
  • $bypassGlobals:

    • If true, global scripts (specifically, a script named global.js) will not be added to the list before output, regardless of the library's current $globals setting.
    • If false (default), a script named global.js will be added to the list if the library's $globals setting is true and the file exists.

module_js([$list = false])

While primarily used internally by the js() method, the module_js() method may be used to generate the script elements for JavaScript files added via add_module_js().

  • $list:

    • If true, the output will be a comma-separated list of filenames, with each filename in double-quotes (this is primarily intended for passing the list of files to a third-party script loader).
    • If false (default), the output of this method will be a string containing script elements referencing the module's js file(s).

Currently, module scripts are always combined, regardless of the configured value of assets.combine_js.

inline_js()

While primarily used internally by the js() method, the inline_js() method may be used to generate the script elements for inline JavaScript code previously added via add_js().

When this method is called, a script element is generated which contains:
1. the configured value of assets.js_opener
2. followed by a newline character
3. all of the code which has been added as 'inline' scripts
4. another newline character
5. the configured value of assets.js_closer

combine_js($files[, $scriptType = ''])

While primarily used internally by the external_js() and module_js() methods, the combine_js() method may be used directly to combine multiple JS files into a single file and return the path to the generated file.

  • $files: An array of filenames for the scripts to be combined.
  • $scriptType: If set to 'module', the generated filename will be changed to reflect that the file contains module scripts. Otherwise, the value is ignored.

If combine_js() detects that there are no files to combine, it returns nothing.

The generated filename for the combined file will be in the format: {theme}{module}{class}_combined
- If it is a module file, 'combined' will be replaced with 'mod'.
- If assets.encrypt_name is true, the filename will be passed through PHP's md5() function.
- If assets.js_minify is true, '.min' will be appended to the filename.
- Finally, the '.js' suffix will be appended to the filename and the file will be placed in the directory indicated by assets.base_folder/assets.directories['cache'].

If the file is successfully generated, combine_js() will return the path to the generated file.
If an error occurred while generating the file, an empty string will be returned.

Image Methods

image($image[, $extraAttrs = array()[, $suppressEol = false]])

A helper method to build img elements.

  • $image: The URL of the image (if empty, an empty string is returned instead of an image element with an empty src attribute).
  • $extraAttrs: An array of key/value pairs which will be applied to the img element as attributes.
  • $suppressEol:

    • If false (default) a newline is appended to the returned img element.
    • If true, the img element is returned without the newline appended.

General Methods

assets_url([$type = null[, $modulePath = false]])

Returns the full URL to one of the assets directories.

  • $type:

    • If 'cache', 'css', 'image', 'js', or 'module', returns the URL for the associated assets directory.
    • Else returns the URL for the base assets directory.
  • $modulePath: If true and $type is 'css' or 'js', returns the URL for the module path (within the CSS or JS assets path).

clear_cache()

Delete all files from the assets cache directory (configured by the values of assets.directories['base'] and assets.directories['cache']).
The index.html file in the assets cache directory will be regenerated.

setDebug([$debug = true])

Configure the library to output debug messages to the page.
Call setDebug(false) to disable debug messages.

setGlobals([$include = true])

Configure the library to include global CSS and JS files (e.g. screen.css and global.js) automatically in the output of css() and js() calls.

set_globals([$include = true]) Deprecated

Use setGlobals() instead.

init()

Called internally by the constructor to initialize the library when loaded by CodeIgniter.
Not intended to be called by external code, despite being a public method.

Helper Functions

Helper functions are not methods of the Assets library (so they are called without using the Assets:: prefix).
They are included automatically when loading the Assets library.

assets_path()

Returns the full site URL to the base assets directory.
A shortcut to Assets::assets_url().

css_path()

Returns the full site URL to the CSS assets directory.
A shortcut to Assets::assets_url('css').

img_path()

Returns the full site URL to the image assets directory.
A shortcut to Assets::assets_url('image').

js_path()

Returns the full site URL to the JavaScript assets directory.
A shortcut to Assets::assets_url('js').

module_css_path()

Returns the full site URL to the module CSS assets directory.
A shortcut to Assets::assets_url('css', true).

module_js_path()

Returns the full site URL to the module JavaScript assets directory.
A shortcut to Assets::assets_url('js', true)