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.

Parameters

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.

Parameters

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.

Parameters

rigImageAsset(tAsset, tAttributes, tModule, tCacheBuster)

Generates image asset location html code.

Parameters

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, pNonce)

Generates JavaScript asset location html code.

Parameters

Here is an example for your view file:

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

or

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

rigJsAsset(tGoogleApisAsset, tModule, tLocalFallbackAsset, tAttribute, pNonce)

Parameters

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.

Parameters

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.

Parameters

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">