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"

Assets Location

To use this helper you should store your assets in a folder called "assets" at your root. You can change this path in your application/config/config.lc 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. The same folder structure applies if you store your files in an arbitrary named folder in assets/modules/ like:
/assets
   /img
   /css
   /js
   /modules
      /myAssetsFolder
         /img
         /css
         /js

 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 application/config/config.lc 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 - defaults to 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.lc (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.lc", tAttrib) into gData["myCSS"]

Assumed the raw CSS file is called myCSS.css.lc, 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 application/config/config.lc 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"] ]]</title>
  
    [[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 - defaults to 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 - defaults to 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, tAttribute)

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 - defaults to TRUE (read about cache busting above). The optional fourth parameter is an async and / or defer script attribute.

Here is an example for your view file:

<? return rigJsAsset("myScript.js") ?>

or

<? return rigJsAsset("myScript.js", , , "async") ?>

rigJsAsset(tGoogleApisAsset, tModule, tLocalFallbackAsset, tAttribute)

If you want to use the Google Apis CDN to serve an open-source JavaScript library you can do so by setting the first parameter of the rigJsAsset() function to a value like: jsGoogleapis-<name>-<version>.
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 optional third parameter is the name of a JavaScript file on your server which serves as a fallback in case a connection to the Google content distribution network is not possible. The optional fourth parameter is an async and / or defer script attribute.
Examples:

<? return rigJsAsset("jsGoogleapis-jquery-1.7.1", , "jQuery.js") ?>

or

<? return rigJsAsset("jsGoogleapis-dojo-1.6.1") ?>

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 - defaults to TRUE (read about cache busting above).

Here is an example for your view file:

<? return rigAddFavicon() ?>

rigWriteManifest tResourcesDir, tManifestName, tUseAbsoluteURI, tResourcesOnlineOnly, tFallbackResources, tDirToIgnore

Generates a manifest file used to store resources in the HTML5 application cache.

The first parameter is a root relative path to resources you want to be cached. The second parameter is the name of the manifest file to be generated. The optional third parameter is a boolean which determines whether to write absolute URIs. Defaults to FALSE. The optional fourth parameter is either an array or a comma delimited list of file names of assets which should not be cached. These names represent the NETWORK section of the manifest to be built. Use pure file names here without paths. The optional fifth parameter is an array of pairs of root relative paths used to build the FALLBACK section of the manifest. The array key describes the preferred URL for a resource to be cached, whereas the array value is a fallback URL to use if the file is inaccessible using the first URL. Use the optional sixth parameter to define a directory containing assets which you don't want to be cached.

Example:

<?lc

put "manifestexample,index" into gControllerHandlers


command manifestexample
  rigLoadHelper "asset"
end manifestexample


command index
  # SET PAGE TITLE
  put "Manifest Example" into gData["pageTitle"]

  # THE PATH TO THE FILES TO BE CACHED
  put "assets/modules/manifest" into tResourcesDir
  put "myTestManifest" into gData["manifestFile"]

  # THE NETWORK AND THE FALLBACK SECTION
  put "myOnlinePic.png" into tResourcesOnlineOnly[1]
  put "/offlineerror" into tFallbackResources["/"]

  # IGNORE ALL ASSETS IN THE myOtherFiles FOLDER
  put "assets/modules/manifest/myOtherFiles" into tDirToIgnore

  # NOW LET'S GENERATE THE MANIFEST FILE
  rigWriteManifest tResourcesDir, gData["manifestFile"], TRUE, tResourcesOnlineOnly, tFallbackResources, tDirToIgnore

  # LOAD THE VIEW FILE
  get rigLoadView("manifestexampleView")
end index



--| END OF manifestexample.lc
--| Location: ./application/controllers/manifestexample.lc
----------------------------------------------------------------------

Now declare the manifest file in the HTML of your view file using the manifest attribute:

<html manifest="[[gData["manifestFile"] ]].manifest">