Asset Class

The asset class is a set of methods to help with the collection, grouping and displaying of assets (js, css, img).

Usage

Using assets can be done in 2 ways: through static usage of the Asset class and through asset objects returned by the Asset::forge() or Asset::instance(). This section covers static usage which will always work with the default instance using the configuration specified in the configuration.

Note: the css, js and img methods will return the current instance when adding to a group. This will happen when you supply a group or auto_render is false and no group (or null) is supplied in the call.

Using asset objects, Asset::instance() and Asset::forge() is explained in the advanced section.

add_path($path, $type = null)

The add_path method adds the given path to the front of the global assets search path array. If a $type is specified, it will add the path to the front of the search folder array for the given type.

Static Yes
Parameters
Param Default Description
$path required The path to add to the front of the assets path array (RELATIVE to the asset url and WITH trailing slash).
$type 
null
 If adding a folder, the type to add it to. The asset class has the types 'img', 'css' and 'js' predefined. If you pass an undefined type, a new paths structure will be created for this type. To add the same path to multiple types, pass them as an array of types.
Returns current instance
Example 
/*
 * These paths would need to have subfolders as defined in the config
 * file, depending on the type of content you were trying to use.
 */
Asset::add_path('resources/template_1/');
Asset::add_path('resources/template_2/');

/*
 * Add a global path for all asset types, then add individual paths
 * for images and css files.
 */
Asset::add_path('assets/global/', array('css', 'js', 'img'));
Asset::add_path('assets/icons/', 'img');
Asset::add_path('assets/images/', 'img');
Asset::add_path('assets/css/', 'css');

/*
 * Create a new asset type
 */
Asset::add_path('assets/docs/', 'pdf');

/*
 * You can chain the calls as well.
 */
Asset::add_path('resources/templates/dark/')
    ->add_path('resources/templates/light')
    ->add_path('resources/templates/brown');

css($stylesheets = array(), $attr = array(), $group = NULL, $raw = false)

The css method adds css to a named group, the default group, or returns the css tag.

Static Yes
Parameters
Param Default Description
$stylesheets required An array/string of stylesheet filename(s) to be added to the group or be returned as tags, or a string containing inline CSS.
$attr 
array()
 An array of attributes to be applied to the css file(s).
$group 
null
 A group name to categorize the css. If left null the method will return the css tag.
$raw 
false
 If set to true, the result css tags will include the string or file contents directly in the HTML, instead of via a link tag.
Returns Rendered asset string or current instance when adding to group.
Example 
// adds file to group and returns '' if group is not null
Asset::css(array('header.css', 'footer.css'), array(), 'layout', false);

/* returns
 * <link href="../assets/css/inline.css" rel="stylesheet" />
 * if auto_render in the config is set to true.
 * if not, the asset will be added to the default group for later rendering
 */
echo Asset::css('inline.css');

/* returns
 * <style>
 * .bold_class { font-weight: bold }
 * #header {height: 50px}
 * </style>
 */
echo Asset::css('inline.css', array(), null, true);

/* returns
 * <style>
 * .bold_class { font-weight: bold }
 * #header {height: 50px}
 * </style>
 */
Asset::css(".bold_class { font-weight: bold }\n#header {height: 50px}", array(), 'inline', true);
echo Asset::render('inline');

/* this will do the same */
echo Asset::css(".bold_class { font-weight: bold }\n#header {height: 50px}", array(), null, true);

find_file($file, $type, $folder = '')

The find_file locates a file of a given type in all defined asset search folders for that type.

Static Yes
Parameters
Param Default Description
$file required The name of the file you are searching for.
$type required The type of asset being searched (css, js, img).
$folder 
''
 The name of the sub-folder to append to each search folder.
Returns Either the path to the file or false if not found
Example 
// find a css file
$path = Asset::find_file('layout.css', 'css');

// find an icon image (assuming icons are in an img sub-folder called 'icons')
$path = Asset::find_file('icon.png', 'img','icons/');

img($images = array(), $attr = array(), $group = NULL)

The img method either adds the image to a named group, the default group, or returns the image tag.

Static Yes
Parameters
Param Default Description
$images required An array/string of image filename(s) to be applied to the group or returned as tags.
$attr 
array()
 An array of attributes to apply to the image tag(s).
$group 
null
 The group to apply the images to.
Returns Rendered asset string or current instance when adding to group.
Example 
/* returns
 * <img src="../assets/img/logo.png" id="logo">
 * if auto_render in the config is set to true.
 * if not, the asset will be added to the default group for later rendering
 */
echo Asset::img('logo.png', array('id' => 'logo'));

Asset::img(array('bob.jpg', 'joe.jpg', 'sally.jpg'), array('class' => 'thumbnail'), 'team_avatars');

js($scripts = array(), $attr = array(), $group = NULL, $raw = false)

The js method either adds the javascript to a named group, the default group, or returns the script tag.

Static Yes
Parameters
Param Default Description
$scripts required An array/string of javascript filename(s) to be added to the group or be returned as tags, or a string containing inline javascript.
$attr 
array()
 An array of attributes to be applied to the js file(s).
$group 
null
 A group name to categorize the js. If left null the method will return the js tag.
$raw 
false
 If set to true, the result javascript tags will include the string or file contents directly in the HTML, instead of via a script tag.
Returns Rendered asset string or current instance when adding to group.
Example 
// returns '' if $raw is set to false
Asset::js(array('jquery.js', 'jqueryui.js'), array(), 'jquery', false);

/* returns
 * <script type="text/javascript">
 * var menu = getElementById('menu');
 * menu.initialize_menu();
 * </script>
 */
echo Asset::js('menu_init.js', array(), null, true);

/* returns
 * <script type="text/javascript" src="../assets/js/jquery.js"></script>
 * if auto_render in the config is set to true.
 * if not, the asset will be added to the default group for later rendering
 */
echo Asset::js('jquery.js');

/* returns
 * <script type="text/javascript">
 * var menu = getElementById('menu');
 * menu.initialize_menu();
 * </script>
 */
Asset::js("var menu = getElementById('menu');\nmenu.initialize_menu();", array(), 'inline', true);
echo Asset::render('inline');

/* this will do the same */
echo Asset::js("var menu = getElementById('menu');\nmenu.initialize_menu();", array(), null, true);

get_file($file, $type, $folder = '')

The get_file method allows you to get the URL to an asset file.

Static Yes
Parameters
Param Default Description
$file required Name of the asset to look for.
$type required Type of asset to search for. 'img', 'css', and 'js' are supported types.
$folder 
''
 Optionally you can specify sub-folders if the asset is in a sub-folder of one of the defined asset search paths.
Returns Fully qualified asset URL (depending on the base_url defined) or false if not found.
Example 
// returns something like 'http://example.org/assets/js/jquery.js'
echo Asset::get_file('jquery.js', 'js');

remove_path($path, $type = null)

The remove_path method removes the given path from the global assets search path array. If a $type is specified, it will remove the path from the search folder array for the given type.

Static Yes
Parameters
Param Default Description
$path required The path to from the assets path array.
$type 
null
 If adding a folder, the type to add it to. Currently, 'img', 'css' and 'js' are suppored. To add the same path to multiple types, pass them as an array of types.
Returns The current instance
Example 
/*
 * Remove global search paths
 */
Asset::remove_path('resources/template_1/');
Asset::remove_path('resources/template_2/');

/*
 * Remove individual paths for different asset types
 */
Asset::remove_path('assets/global/', array('css', 'js', 'img'));
Asset::remove_path('assets/icons/', 'img');
Asset::remove_path('assets/images/', 'img');
Asset::remove_path('assets/css/', 'css');

/*
 * Or chain the calls.
 */
Asset::remove_path('resources/templates/dark/')
    ->remove_path('resources/templates/light')
    ->remove_path('resources/templates/brown');

render($group = null, $raw = false)

The render renders the group of assets and returns the tags. If no group is specified, the default group will be rendered.

Static Yes
Parameters
Param Default Description
$group 
null
 The name of the group to render or null for the default group.
$raw 
false
 If true this method will include the contents of css/js files for embedding.
Returns string
Example 
/* returns
 * <link href="../assets/css/header.css" rel="stylesheet" />
 * <link href="../assets/css/footer.css" rel="stylesheet" />
 */
echo Asset::render('layout');

// renders the default group
echo Asset::render();