FUEL CMS User Guide : Version 0.9.3

Asset Class

The Asset class gives you a way to manage paths to asset files in your web project. It also provides several convenient methods for embedding css, javascript and flash assets.

This class must exist in the application libraries folder for the FUEL CMS admin to work

Initializing the Class

Like most other classes in CodeIgniter, the Asset class is initialized in your controller using the $this->load->library function:

$this->load->library('asset');

Alternatively, you can pass initialization parameters as the second parameter:

$this->load->library('asset', array('assets_path' => 'external_files', 'assets_last_updated' => '01/01/2010 00:00:00'));

Once loaded, the Asset object will be available using: $this->asset. Additionally, you can use the asset helper which provides a shortcut for many of the methods of the asset class.

Configuring Asset Information

The Asset class automatically loads the config/asset.php file to initialize. That file contains the following configurable parameters:

array(
'images' => 'images/',
'css' => 'css/',
'js' => 'js/',
'pdf' => 'pdf/',
'swf' => 'swf/',
'media' => 'media/',
'captchas' => 'captchas/'
);
				

Optimizing Assets

You can increase server performance by optimizing your assets. The assets_output configuration parameter explained above gives you several ways to output and optimize your css and js files. Values of TRUE, gzip, whitespace and combine will put files in the assets cache folder.

Important - The cache folder must have writable permissions.

Manage Assets in the FUEL Admin

FUEL CMS can help users manage asset files for their site. More information about managing assets can be found in the asset modules documentation

Important - To allow the FUEL Admin to manage your sites assets, you must give the folder(s) writable permissions.

Function Reference

The following functions return paths to asset files. The first parameter is the name of the asset file. The second parameter is used when you want to reference an asset folder in a module. The third parameter provides an http absolute path. If no parameters are passed then just the web path to the respective asset folder will be returned. Each path function below has a corresponding helper function from the asset_helper for convenience.

If the asset type is listed in the asset_append_cache_timestamp configuration parameter, a query string parameter similar to this ?c=943948800 will be appended to the end of the file name.

$this->asset->img_path(['file'], ['module'], [is_absolute])

Returns the web path to an image asset. This and the helper function equivalent are commonly used in <img> tags. The first parameter is the name of the image file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->img_path('banner.jpg');
// /assets/images/banner.jpg

echo $this->asset->img_path('banner.jpg', 'my_module');
// /fuel/modules/my_module/assets/images/banner.jpg (assuming /fuel/modules is where the module folder is located)

echo $this->asset->img_path('banner.jpg', NULL, TRUE);
// http://www.mysite.com/assets/images/banner.jpg (if the "assets_module" Asset class property is empty)
// http://www.mysite.com/fuel/modules/my_module/assets/images/banner.jpg (if the "assets_module" Asset class property is my_module)

echo $this->asset->img_path('banner.jpg', '', TRUE);
// http://www.mysite.com/assets/images/banner.jpg (and empty string for the module parameter will properly ignore anything in the assets_module Asset class property)

File extension must be included.

$this->asset->css_path(['file'], ['module'], [is_absolute])

Returns the web path to a css stylesheet asset. This and the helper function equivalent are commonly used in css <link> tags. The first parameter is the name of the css file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->css_path('main');
// /assets/css/main.css

echo $this->asset->css_path('main', 'my_module');
// /fuel/modules/my_module/assets/css/main.css (assuming /fuel/modules is where the module folder is located)

echo $this->asset->css_path('main', NULL, TRUE);
// http://www.mysite.com/assets/css/main.css

The .css file extension will automatically be added if it is not found in the file name (first parameter).

$this->asset->js_path(['file'], ['module'], [is_absolute])

Returns the web path to a javascript asset. This and the helper function equivalent are commonly used in javascript <script> tags. The first parameter is the name of the javascript file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->js_path('main');
// /assets/js/main.js

echo $this->asset->js_path('main', 'my_module');
// /fuel/modules/my_module/assets/js/main.js (assuming /fuel/modules is where the module folder is located)

echo $this->asset->js_path('main', NULL, TRUE);
// http://www.mysite.com/assets/js/main.js

The .js file extension will automatically be added if it is not found in the file name (first parameter).

$this->asset->swf_path(['file'], ['module'], [is_absolute])

Returns the web path to a flash swf asset. This and the helper function equivalent are commonly used in <object> and <embed> tags. The first parameter is the name of the swf file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->swf_path('main');
// /assets/swf/home.swf

echo $this->asset->swf_path('main', 'my_module');
// /fuel/modules/my_module/assets/swf/home.swf (assuming /fuel/modules is where the module folder is located)

echo $this->asset->swf_path('main', NULL, TRUE);
// http://www.mysite.com/assets/swf/home.swf

The .swf file extension will automatically be added if it is not found in the file name (first parameter).

$this->asset->pdf_path(['file'], ['module'], [is_absolute])

Returns the web path to a pdf asset. This and the helper function equivalent are commonly used in anchor (<a>) tags linking to pdf files. The first parameter is the name of the pdf file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->pdf_path('newsletter');
// /assets/swf/newsletter.pdf

echo $this->asset->pdf_path('main', 'my_module');
// /fuel/modules/my_module/assets/pdf/newsletter.pdf (assuming /fuel/modules is where the module folder is located)

echo $this->asset->pdf_path('main', NULL, TRUE);	
// http://www.mysite.com/assets/pdf/newsletter.pdf

The .pdf file extension will automatically be added if it is not found in the file name (first parameter).

$this->asset->media_path(['file'], ['module'], [is_absolute])

Returns the web path to a media asset (e.g. a quicktime movie). This and the helper function equivalent are commonly used in anchor (<a>) tags linking to media files. The first parameter is the name of the media file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->media_path('mymovie.mov');
// /assets/swf/newsletter.pdf

echo $this->asset->media_path('main', 'my_module');
// /fuel/modules/my_module/assets/swf/newsletter.pdf (assuming /fuel/modules is where the module folder is located)

echo $this->asset->media_path('main', NULL, TRUE);
// http://www.mysite.com/assets/swf/newsletter.pdf

File extensions must be included.

$this->asset->cache_path(['file'], ['module'], [is_absolute])

Returns the web path to the cache folder for optimized javascript and css assets. The configuration parameter assets_output must be set to either TRUE, gzip, whitespace and combine for files to appear in this folder. The first parameter is the name of the media file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->cache_path('3c38643da81c3cee289feac34465c353_943948800.php');
// /assets/cache/3c38643da81c3cee289feac34465c353_943948800.php

echo $this->asset->cache_path('3c38643da81c3cee289feac34465c353_943948800.php', 'my_module');
// /fuel/modules/my_module/assets/cache/3c38643da81c3cee289feac34465c353_943948800.php (assuming /fuel/modules is where the module folder is located)

echo $this->asset->cache_path('3c38643da81c3cee289feac34465c353_943948800.php', NULL, TRUE);
// http://www.mysite.com/assets/cache/3c38643da81c3cee289feac34465c353_943948800.php

File extensions must be included. Modules should include a writable asset cache folder (e.g. assets/cache) if asset optimizing is used

$this->asset->captcha_path(['file'], ['module'], [is_absolute])

Returns the web path to where captcha images are stored. The captcha plugin (or another captcha library), should use this folder to store captcha images. The first parameter is the name of the capthca file. The second parameter module folder name. The third parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->captcha_path('123456_captcha.jpg');
// /assets/captcha/123456_captcha.jpg

echo $this->asset->captcha_path('123456_captcha.jpg', 'my_module');
// /fuel/modules/my_module/assets/captcha/123456_captcha.jpg (assuming /fuel/modules is where the module folder is located)

echo $this->asset->captcha_path('123456_captcha.jpg', NULL, TRUE);
// http://www.mysite.com/assets/captcha/123456_captcha.jpg

File extensions must be included. This folder must be writable.

$this->asset->assets_path('file', 'type', 'module', is_absolute)

Returns the web path to an asset file. The first parameter is the name of the asset file. The second parameter is the subfolder name (e.g. images). The third parameter is the module folder name. The fourth parameter is a boolean value to return either a relative or an http absolute path. Examples:

echo $this->asset->assets_path();
// /assets/

echo $this->asset->assets_path('banner.jpg', 'images');
// /assets/images/banner.jpg

echo $this->asset->assets_path('banner.jpg', 'images', 'my_module');
// /fuel/modules/my_module/assets/images/banner.jpg (assuming /fuel/modules is where the module folder is located)

echo $this->asset->assets_path('banner.jpg', 'images', NULL, TRUE);
// http://www.mysite.com/assets/images/banner.jpg

File extensions must be included. This folder must be writable.

$this->asset->assets_server_path('file', 'type', 'module')

Returns the server path to an asset file. The first parameter is the name of the asset file. The second parameter is the asset type subfolder name (e.g. images). The third parameter is the module folder name. Examples:

echo $this->asset->assets_server_path();
// /Library/WebServer/Documents/assets/

echo $this->asset->assets_path('banner.jpg', 'images');
// /Library/WebServer/Documents/assets/images/banner.jpg

echo $this->asset->assets_path('banner.jpg', 'images', 'my_module');
// /Library/WebServer/Documents/fuel/modules/my_module/assets/images/banner.jpg (assuming /fuel/modules is where the module folder is located)

File extensions must be included. This folder must be writable.

$this->asset->assets_server_to_web_path('file', truncate_to_asset_folder)

Converts a server path to a web path. Typically used when you scan a directory of files and you need to convert from the server path to the web path. The truncate_to_asset_folder will truncate the path all the way to the particular asset folder.

$file_server_path = '/Library/WebServer/Documents/assets/images/my_img.jpg';
echo $this->asset->assets_server_to_web_path($file_server_path);
// /assets/images/my_img.jpg

$this->asset->js('file', ['module'], [params])

Can return either be a <script> tag with a src value pointing to a file or can print the contents of that file inlne. The first parameter is the path to the file(s). Use a comma seperated string or an array to specify multiple files. The second parameter is the module name. The third parameter is an array of additional attributes to pass. Those attributes can be the following

• attrs - additional attributes to pass to the <script> tag. Can be a string or an array
• output - the output method to be applied to the contents of the file. Can be any of the assets_output
• ie_conditional - applies an IE specific conditional comment around the <script> tag

Additionally, if the asset configuration of asset_append_cache_timestamp includes js, then the caching timestamp will be appended as a query string parameter at the end just like if you were to use $this->asset->js_path(). Examples:

$this->asset->js('main');
// <script src="/assets/js/main.js" type="text/javascript" charset="utf-8"></script>

echo $this->asset->js('jquery, main');
// <script src="/assets/js/jquery.js" type="text/javascript" charset="utf-8"></script>
// <script src="/assets/js/main.js" type="text/javascript" charset="utf-8"></script>

echo $this->asset->js(array('jquery', 'main'));
// <script src="/assets/js/jquery.js" type="text/javascript" charset="utf-8"></script>
// <script src="/assets/js/main.js" type="text/javascript" charset="utf-8"></script>

echo $this->asset->js('main', 'my_module');
// <script src="/fuel/modules/my_module/assets/js/jquery.js" type="text/javascript" charset="utf-8"></script>

echo $this->asset->js('main', NULL, array('output' => TRUE, 'attrs' => 'onload=myOnloadFunc()', 'ie_conditional' => 'lte IE 6'));
// <!--[if lte IE 6]>
// <script src="/assets/cache/3c38643da81c3cee289feac34465c353_943948800.php" type="text/javascript" charset="utf-8" onload="myOnloadFunc"></script>
// <![endif]-->

Important - All path references in the javascript file (e.g. paths to image files), should be changed to absolute if the script is printed inline.

$this->asset->css('file', ['module'], [params])

Can return either be a <link> tag with a href value pointing to a file or can print the contents of that file inlne in a style tag. The first parameter is the path to the file(s). Use a comma seperated string or an array to specify multiple files. The second parameter is the module name. The third parameter is an array of additional attributes to pass. Those attributes can be the following

• attrs - additional attributes to pass to the <link> tag. Can be a string or an array
• output - the output method to be applied to the contents of the file. Can be any of the assets_output
• ie_conditional - applies an IE specific conditional comment around the <link> tag

Additionally, if the asset configuration of asset_append_cache_timestamp includes css, then the caching timestamp will be appended as a query string parameter at the end just like if you were to use $this->asset->css_path(). Examples:

echo $this->asset->css('main');
// <link href="/assets/css/main.css" media="all" rel="stylesheet"/>

echo $this->asset->css('main, home');
// <link href="/assets/css/main.css" media="all" rel="stylesheet"/>
// <link href="/assets/css/home.css" media="all" rel="stylesheet"/>

echo $this->asset->js(array('main', 'home'));
// <link href="/assets/css/main.css" media="all" rel="stylesheet"/>
// <link href="/assets/css/home.css" media="all" rel="stylesheet"/>

echo $this->asset->css('main', 'my_module');
// <link href="fuel/modules/my_module/assets/css/main.css" media="all" rel="stylesheet"/>

echo $this->asset->css('main', NULL, array('output' => TRUE, 'attrs' => 'media="print"', 'ie_conditional' => 'lte IE 6'));
// <!--[if lte IE 6]>
// <link href="/assets/css/main.css" media="print" rel="stylesheet"/>
// <![endif]-->

Important - All path references in the css file (e.g. paths to background image files), should be changed to absolute if the script is printed inline

$this->asset->swf('file', 'id', 'width', 'height', [other_options])

Will return code to embed a Flash swf file. The first value is the name or the flash file. The second parameter is html id value that swfobject should replace. The third and fourth parameter is the width and height of the flash file respectively. The fourth parameter is a catch all for additional parameter that can be passed which include:

• vars - FlashVar variables to pass to the swf file
• version - the Flash Player version to detect for. Default is Flash Player 9
• color - the background color to be used. May be seen briefly before the swf file runs.
• params - additional parameters to be passed to the swf file. For information on the additional parameters, visit the swfobject documentation

echo swf('home', 'home_flash', 800, 300, array('color' => '#000000', 'version' => 9));

// <script src="/assets/js/swfobject.js" type="text/javascript" charset="utf-8"></script>
// <script type="text/javascript">
// //<![CDATA[
//     var so = new SWFObject("/assets/swf/home.swf", "flash_swf", "800", "300", "9", "#000000");
//     so.write("flash");
// // ]]>
// </script>

Important - Requires the swfobject.js to be located in the javascript assets folder. The swfoject being used is an older version (1.5)

 · Top of Page  · User Guide Home  ·

FUEL CMS  ·  © Copyright 2012  ·  Daylight Studio