Assets

Bonfire 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 Bonfire.

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.

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.

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

Renders link(s) to stylesheets.

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.

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.

'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.

js([$script[, $type = ‘external’]])

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

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.

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().

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.

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.

General Methods

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

Returns the full URL to one of the assets directories.

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)