FUEL CMS User Guide : Version 1.5.2


Asset Class

This class allows you to output css, js links and/or files as well as allows you to compress and cache them. It also has convenience methods for paths to different assets like images, pdfs, javascript css etc.

Additionally, you can use the asset helper which provides a shortcut for many of the methods of the Asset class.

This class is auto-loaded.

Properties Reference

Property Default Value Description
public
assets_path assets/ relative to web_root
assets_folders 
array('images' => 'images/', 'css' => 'css/', 'js' => 'js/', 'pdf' => 'pdf/', 'swf' => 'swf/', 'media' => 'media/', 'captchas' => 'captchas/', )
 relative to web_root/assets_path
assets_absolute_path 1 makes paths to assets absolute
assets_last_updated 00/00/0000 00:00:00 used for caching
asset_append_cache_timestamp 
array('js', 'css')
 appends timestamp of last updated after file name
assets_output none Optimize and/or cache assets. Options are: <ul> <li><strong>FALSE</strong> - no optimization</li> <li><strong>TRUE</strong> - will combine files, strip whitespace, and gzip</li> <li><strong>inline</strong> - will render the files inline</li> <li><strong>gzip</strong> - will combine files (if multiple) and gzip without stripping whitespace</li> <li><strong>whitespace</strong> - will combine files (if multiple) and strip out whitespace without gzipping</li> <li><strong>combine</strong> - will combine files (if multiple) but will not strip out whitespace or gzip</li> </ul>
force_assets_recompile none force assets to recompile on each load
assets_cache_folder cache/ cache folder relative to the application folder... must be writable directory (default is the application/assets/cache folder)
assets_gzip_cache_expiration 3600 time limit on gzip cache file in seconds
assets_module_path fuel/modules/{module}/assets/ module assets path
assets_module none module context for assets
ignore_if_loaded none will ignore loading css and js files if loaded already
protected
_used N/A an array of all the css/js files used so we can check as to whether we need to call them again.
_module_config_loaded N/A cache of module configs loaded
_asset_config_loaded N/A has assets configuration been loaded?
_cacheable_files N/A the collection of files to cache

Function Reference [+]

$this->asset->initialize([$config=array()])

Initialize the user preferences. Accepts an associative array as input, containing display preferences.

Returns

void

Parameters

(array) $config config preferences

$this->asset->img_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns an image asset path.

File extension must be included.

Returns

string

Parameters

(string) $file image file name including extension
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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)

$this->asset->css_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a css asset path.

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

Returns

string

Parameters

(string) $file css file name (extension not required)
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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
	</pre>

$this->asset->js_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a js asset path.

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

Returns

string

Parameters

(string) $file javascript file name (extension not required)
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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

$this->asset->swf_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a swf asset path.

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

Returns

string

Parameters

(string) $file swf file name (extension not required)
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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

$this->asset->pdf_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a pdf asset path.

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

Returns

string

Parameters

(string) $file pdf file name (extension not required)
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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

$this->asset->media_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a media asset path (e.g. quicktime .mov).

File extensions must be included.

Returns

string

Parameters

(string) $file pdf file name including extension
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


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

	echo $this->asset->media_path('mymovie.mov', 'my_module');
	// /fuel/modules/my_module/assets/media/nmymovie.mov (assuming /fuel/modules is where the module folder is located)

	echo $this->asset->media_path('mymovie.mov', NULL, TRUE);
	// http://www.mysite.com/assets/media/mymovie.mov

$this->asset->docs_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a document asset path (e.g. doc, docx).

File extensions must be included.

Returns

string

Parameters

(string) $file doc file name including extension
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	echo $this->asset->docs_path('mydoc.doc');
	// /assets/docs/mydoc.doc

	echo $this->asset->docs_path('mydoc.doc', 'my_module');
	// /fuel/modules/my_module/assets/docs/mydoc.doc (assuming /fuel/modules is where the module folder is located)

	echo $this->asset->media_path('mydoc.doc', NULL, TRUE);
	// http://www.mysite.com/assets/docs/mydoc.doc

$this->asset->cache_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a cache asset path.

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

Returns

string

Parameters

(string) $file cached file name including extension
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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

$this->asset->captcha_path(['$file'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns a captcha image path.

Returns

string

Parameters

(string) $file captcha file name including extension
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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

$this->asset->assets_path(['$file'=NULL], ['$path'=NULL], ['$module'=NULL], ['$absolute'=NULL])

Returns an asset path and is what the others above use.

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

Returns

string

Parameters

(string) $file asset file name including extension
(string) $path subfolder to asset file (e.g. images, js, css... etc)
(string) $module module folder if any
(boolean) $absolute whether to include http://... at beginning

Example


	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

$this->asset->assets_server_path(['$file'=NULL], ['$path'=NULL], ['$module'=NULL])

Get the server path.

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

Returns

string

Parameters

(string) $file asset file name including extension
(string) $path subfolder to asset file (e.g. images, js, css... etc)
(string) $module module folder if any

Example


	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)

$this->asset->assets_server_to_web_path('$file', ['$truncate_to_asset_folder'=FALSE])

Convert a server path to a web path.

Returns

string

Parameters

(string) $file server path to asset file
(bool) $truncate_to_asset_folder determines whether to truncate to the asset folder or not

Example


	$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->asset_exists(['$file'=NULL], ['$path'=NULL], ['$module'=NULL])

Returns a boolean value of whether a file exists.

Returns

boolean

Parameters

(string) $file asset file name including extension
(string) $path subfolder to asset file (e.g. images, js, css... etc)
(string) $module module folder if any

Example


	if ($this->asset->asset_exists('banner.jpg'))
	{
		echo 'file exists!';
	}

$this->asset->asset_filesize(['$file'=NULL], ['$path'=NULL], ['$module'=NULL], ['$format'=TRUE])

Returns the file size of an asset.

Returns

string

Parameters

(string) $file asset file name including extension
(string) $path subfolder to asset file (e.g. images, js, css... etc)
(string) $module module folder if any
(boolean) $format format

Example


	echo $this->asset->asset_filesize('banner.jpg');
	// 20500

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

$this->asset->jquery(['$version'='1.7.1'], ['$default'='jquery'])

Creates javascript code that first tries to pull in jquery from the Google CDN, and if it doesn't exist, goes to the local backup version.

Returns

string

Parameters

(string) $version jQuery version number for Google CDN
(string) $default local asset path to default version

$this->asset->js('$path', ['$module'=''], [$options=array()])

Inserts [removed][removed] tags based on configuration settings for js file path.

The third parameter is an array of additional attributes to pass. Those attributes can be the following

  • attrs - additional attributes to pass to the [removed] 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 [removed] 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:

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.

Returns

string

Parameters

(string) $path file name of the swf file including extension
(string) $module module module folder if any
(array) $options additional parameter to include (attrs, ie_conditional, and output... Can be any of the assets_output)

Example


	echo $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]-->

$this->asset->css('$path', ['$module'=''], [$options=array()])

Inserts <link ... /> tags based on configuration settings for css file path.

The third parameter is an array of additional attributes to pass. Those attributes can be the following

  • attrs - additional attributes to pass to the [removed] 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 [removed] 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:

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

Returns

string

Parameters

(string) $path file name of the swf file including extension
(string) $module module module folder if any
(array) $options additional parameter to include (attrs, ie_conditional, and output)

Example


	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->css(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]-->

$this->asset->swf('$flash', '$id', '$width', '$height', [$options=array()])

Embeds a flash file using swfobject.

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

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

Returns

string

Parameters

(string) $flash file name of the swf file including extension
(string) $id html id that the flash will replace with swfobject
(int) $width width of the flash file
(int) $height height of the flash file
(array) $options additional parameter to include (vars, version, and color, params)

Example


	echo $this->asset->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>

$this->asset->is_used('$type', '$file')

Check to see whether a css/js file has been used yet.

Returns

boolean

Parameters

(string) $type type of file (e.g. images, js, css... etc)
(string) $file file name

$this->asset->optimize('$files', [$params=array()])

Optimizes CSS and JS files by combining files together with options to remove whitespace and optimize code.

  • type - valid options are "js", "css" and auto. The default is "auto" and will look for the first file extension in the list of files passed
  • destination - the path and file name of the file to save the output to. Default is FALSE which means no file will be written
  • whitespace - whether to perform basic removal of whitespace.
  • js_minify - will use Google's Closure Compiler for javascript minification.
  • compilation_level - WHITESPACE_ONLY, SIMPLE_OPTIMIZATIONS and ADVANCED_OPTIMIZATION. More can be found here here. The default is WHITESPACE_ONLY.
  • gzip - determines whether to add PHP code to gzip the file. Must be saved as a php file.

Returns

string

Parameters

(mixed) $files file(s) to optimize. Can be an array or string
(array) $params an array of parameters including "destination", "whitespace", "js_minify", "compilation_level" and "type"

Example


	$output = $this->asset->optimize(array('file1, 'file2.js', array('type' => 'js', 'destination' => 'my.min.js', 'whitespace' => TRUE, 'js_minify' => TRUE, 'gzip' => TRUE));