Asset Helper
The Asset Helper file contains handlers that assist in working with assets, namely images, css files, javascript files and favicons.
Loading this Helper
This helper is loaded using the following code:
rigLoadHelper "asset"
Note: To use this helper you should put your assets into a folder called "assets" at your root. You can change this path in your system/application/config/config.irev file. This helper assumes that your image folder is called "img", that your CSS folder is called "css" and that your Javascript folder is called "js". If you don't like that, you can change the corresponding variables at the top of the helper script.
Busting Caches
If you are using far future expire headers for static files, which are likely to be modified anytime, you should set
use_cacheBusters in system/application/config/config.irev to TRUE to enable a mechanism for automatically updating user's cache. Then whenever you modify static files like images, CSS files, JavaScript files or favicons, browser cached data is refreshed without the need to change file names.
If use_cacheBusters is set to TRUE, asset file names are translated by the asset helper to <name>-cb<lastModified>.suffix,
so you need to include the following mod_rewrite RewriteRule either in a .htaccess file or in httpd.conf:
RewriteRule ^(.*)-cb\d+\.(.*)$ $1.$2 [L]
This rule causes assets with names like <name>-cb<lastModified>.suffix to be redirected to the original ones.
Note: If you use mod_rewrite rules as described in revIgniter URLs, you need to insert this rule on a seperate line before the "RewriteBase /" statement.
The asset helper functions use an optional parameter which allows to exclude assets from being affected by the global setting use_cacheBusters (if set to TRUE). That way the cache busting mechanism can be applied individually.
All code regarding cache busting is based on ideas found at: http://cjohansen.no/en/apache/using_a_far_future_expires_header
The following functions are available:
rigCssAsset(tAsset, tAttributes, tModule, tCacheBuster)
Generates a css asset location html code.
The first parameter is the name of your CSS file like myCSS.css. Assets can be nested in folders, then the value of this parameter looks like: myFirstFolder/mySecondFolder/myCSS.css. These folders would be located in assets/css. The second optional parameter is an array of attributes and the third optional parameter a folder name where you store assets for the current page if you like to organize assets for different pages in separate folders. This folder should be located in a "modules" folder, which is located in the "assets" folder". The fourth optional parameter is a boolean, which determines if asset file names should include the timestamp of last modification - default is TRUE (read about cache busting above).
Here is an example for the header section in your view file:
<? return rigCssAsset("myCSS.css") ?>
rigDynamicCssAsset(tRawCSS, tAttributes, tModule, tCacheBuster)
Simple CSS preprocessor which dynamically generates a CSS file and the corresponding CSS asset location html code.
This function is primarily intended to be used to apply cache busting to images referenced in CSS files. The first parameter is the name of your CSS file containing variables enclosed in double square brackets that correspond to array keys in the global array variable gData. The meaning of the second, third and fourth parameter is identical to those of the rigCssAsset() function above.
Here is an example on how to apply this function:
Let's say this is an abstract of your CSS file.
#mastHead {
height:480px;
width:312px;
background-image: url('[[gData["mastheadImg"] ]]');
}
Note: File name prototype for your raw CSS file to be processed is filename.css.irev (mind the suffixes).
This is an abstract of your controller.
-- define your variables, in this case store an image URL in gData
put rigImgAssetURL("masthead.jpg") into gData["mastheadImg"]
-- define attributes if needed
put "screen" into tAttrib["media"]
-- preprocess your raw CSS file and get the CSS asset location html code to be stored in gData
put rigDynamicCssAsset("myCSS.css.irev", tAttrib) into gData["myCSS"]
Assumed the raw CSS file is called myCSS.css.irev, then the name of the generated CSS file sent to the browser is myCSS.css
This is an abstract of the generated CSS file, assumed use_cacheBusters in system/application/config/config.irev is set to TRUE:
#mastHead {
height:480px;
width:312px;
background-image: url('http://yourDomain.com/assets/img/masthead-cb1263400945.jpg');
}
Note: File permissions on your assets/css folder or wherever you store your CSS files must be set such that it is writable.
This is an abstract of your view.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>[[gData["myTitle"] ]]
[[gData["myCSS"] ]]
</head>
<body>
rigImgAssetURL(tAsset, tModule, tCacheBuster)
Used mainly in conjunction with the rigDynamicCssAsset() function to generate image URLs as values for the gData array variable.
The first parameter is the name of your image file like myPic.jpg. Assets can be nested in folders, then the value of this parameter looks like: myFirstFolder/mySecondFolder/myPic.jpg. These folders would be located in assets/img. The second parameter is optional, it is the name of the folder where you store all your assets for the current page if you like to organize assets for different pages in separate folders. This folder should be located in a "modules" folder, which is located in the "assets" folder". The fourth optional parameter is a boolean, which determines if asset file names should include the timestamp of last modification - default is TRUE (read about cache busting above). See usage in the example above.
rigImageAsset(tAsset, tAttributes, tModule, tCacheBuster)
Generates image asset location html code.
The first parameter is the name of your image file like myPic.jpg. Assets can be nested in folders, then the value of this parameter looks like: myFirstFolder/mySecondFolder/myPic.jpg. These folders would be located in assets/img. The second optional parameter is an array of attributes and the third optional parameter a folder name where you store assets for the current page if you like to organize assets for different pages in separate folders. This folder should be located in a "modules" folder, which is located in the "assets" folder". The fourth optional parameter is a boolean, which determines if asset file names should include the timestamp of last modification - default is TRUE (read about cache busting above).
Example:
put "pics" into tArray["class"]
put "My Portrait" into tArray["alt"]
put rigImageAsset("myPic.jpg", tArray, "aboutMe", FALSE) into gData["myPic"]
"aboutMe" would be a folder in your "assets/modules" folder.
rigJsAsset(tAsset, tModule, tCacheBuster)
Generates JavaScript asset location html code.
The first parameter is the name of your Javascript file like myScript.js. Assets can be nested in folders, then the value of this parameter looks like: myFirstFolder/mySecondFolder/myScript.js. These folders would be located in assets/js. The second optional parameter is a folder name where you store assets for the current page if you like to organize assets for different pages in separate folders. This folder should be located in a "modules" folder, which is located in the "assets" folder". The third optional parameter is a boolean, which determines if asset file names should include the timestamp of last modification - default is TRUE (read about cache busting above).
Here is an example for your view file:
<? return rigJsAsset("myScript.js") ?>
If you want to use the Google Apis CDN to serve an open-source JavaScript library you can do so by naming the asset (the first parameter) like: jsGoogleapis-<name>-<version>. Examples:
<? return rigJsAsset("jsGoogleapis-jquery-1.4.4") ?>
or
<? return rigJsAsset("jsGoogleapis-dojo-1.5") ?>
For a list of available libraries see: Google Libraries API - Developer's Guide.
rigAddFavicon(tModule, tCacheBuster)
Generates a link tag using the base url that points to favicon.
Use this function, if your favicon is not located at your root. Put it in assets/img. The first optional parameter is a folder name where you store assets for the current page if you like to organize assets for different pages in separate folders. This folder should be located in a "modules" folder, which is located in the "assets" folder". The second optional parameter is a boolean, which determines if asset file names should include the timestamp of last modification - default is TRUE (read about cache busting above).
Here is an example for your view file:
<? return rigAddFavicon() ?>