Asset Library
The Asset library takes over some of the role of the old Page class prior to version 0.6. It allows asset files to be loaded and optimised in a controller to ease development while at the same time providing quick loading files for the live web server.
Important: This class is initialized automatically by the system so there is no need to do it manually.
Features:
- Asset Dependencies
- Asset Groups
- Browser Specific Assets (a.k.a Conditional Assets)
- Asset Caching and Optimisation
- CSS Compression
- JS Compression
How to use the Asset Library?
The asset library is loaded by default by the BackendPro Class. The class file can be found at modules/site/libraries/bep_assets.php
To access a method in the Asset library please using the following syntax:
$this->bep_assets->{method_name};
The Basics
What is an Asset? And why do we need a Loader?
An asset is a file which contains either CSS or JS, which is used to style an HTML page or provide functionality to a page.
On small websites you may have a single CSS file to style your pages and a few JS files to do some drop down menus with. As your site expands you will start to get more CSS and more JS, so to keep it all maintainable you seperate it into smaller files keeping related things together. Before you know it you need to load 10 CSS files and 5 JS files for one page, and 3 more CSS files for a different page.
An asset loading system will help you manage what files need to be loaded and when. This means you are only ever loading the CSS and JS you need for a page, it also means you can optimise and cache the files to speed up loading even more. No more having to update header views to load a single extra CSS files (which will now be loaded on every page even though it is only used on one), just a few lines of code and the loader takes care of how to best load the files you want, when you want.
Configuration & Setup
All configuration settings for the Asset library can be found in modules/site/config/bep_assets.php.
Asset Array
To be able to load an asset in your code, you have to first tell the system about the file. Where it is, what do you want to call it, how do you want it outputed and also does it need another asset to work.
Lets take a look at some example asset definitions of all the options which are possible:
A Simple Asset:
$config['asset'][] = array('file'=>'reset.css');As you can see above we have defined an asset called reset.css, it is a CSS file and therefore should be located in the assets/css/ directory. This will be outputed in the <header> of the page.
Throughout your code you can reference this asset used the name reset.
Changing the Asset Name:
$config['asset'][] = array('file'=>'my.style.file.css', 'name'=>'style');There will be times for what ever reason when you don't want to use the asset file name to reference the asset. In this case you can specify a name attribute. This overrides the default name meaning you reference this asset using style rather than my.style.file.
Dynamic Assets:
$config['asset'][] = array('file'=>'generate_js.php', 'name'=>'dynamic', 'type'=>'js');The asset loader can also handle dynamicly generated CSS/JS files. The only difference is you must specify the type of the output, either 'css' or 'js' are valid values.
When using dynamic assets you must include several lines of code in the actual PHP file. The code below sets what type of file the browser will see it as. The if statement is so it is not used when caching the file, since it is not needed in this case.
<?php
if( ! isset($cache_output))
{
header('content-type:text/css'); // Include if a css file
header('content-type:text/js'); // Include if a js file
}
?>Asset Dependencies:
$config['asset'][] = array('file'=>'jquery.plugin.js', 'needs'=>'plugin_css|jquery');There will be times (mainly with JS files) when for it to work it depends on another asset file. In the example above our jquery.plugin,js asset requires two assets, one a CSS file and the other a jquery JS file.
An asset can depend on as many other assets as you want, seperate each asset reference name using a | character .
Important: Do not create circular dependencies, it will cause the site to hang and is not caught by the loader.
Output JS Assets in Header:
$config['asset'][] = array('file'=>'jquery.plugin.js', 'position'=>'header');By default the asset loaded will load all JS files at the end of the document. This is becasue while a browser is downloading a JS file it can't do anything else. So by putting it at the end, your user should be able to see and use parts of the site without waiting. If you need to use a document.write statement you will need to output the JS file to the header of the document. This can be done like in the example code above.
If you set an asset to be in the 'header' position then all the assets it depends on will also be moved to the header. Note: CSS assets are always outputed in the header.
Asset Group Array
There may be a case when you need to load groups of assets all at once. For example, a collection of assets for a theme. This is possible by creating an entry in the asset group array.
$config['asset_group']['SITE'] = 'reset|typography';
In the code above you can see we have defined a group called SITE and in the group is a reset & typography asset. Group names should always be in CAPITALS.
There are 3 main default groups which are loaded in the BackendPro system:
- SITE: This group is loaded by the Site_Controller class, this means it is loaded for both front end and backend controllers.
- PUBLIC: This group is loaded by the Public_Controller class, this means it is loaded only for a front end controller.
- ADMIN: This group is loaded by the Admin_Controller class, this means it is loaded only for a backend controller.
Methods
$this->bep_assets->load_asset()
Load an Asset file:
$this->bep_assets->load_asset('asset')
Specifies an asset file to load when the page is outputed. asset should be an asset reference. This will depend on how you have setup the asset in the config file. Please read about the Asset array for more details.
$this->bep_assets->load_asset_group()
Load an Asset Group:
$this->bep_assets->load_asset_group('group')
Specifies an asset group to load when the page is outputed.
$this->bep_assets->get_header_assets()
Get all the header assets for the current page. This would be used in your view and should be put somewhere in the <header> tag.
$this->bep_assets->get_footer_assets()
Get all the footer assets for the current page. This would be used in your view and should be last statement before the <body> closing tag.
$this->bep_assets->icon()
Output an Icon file:
$this->bep_assets->icon('name','title');
- The first parameter is the name of the icon file you want to output. It must be the filename of the icon file located in assets/icons/ without the extension. Only PNG can currently be outputed.
- The second optional paramter sets an image title which will appear on mouseover of the icon.