This tutorial page has moved to: http://discourse.farcrycore.org/t/loading-javascript-css-libraries/96

Overview

In dynamic CMS frameworks you often find yourself needing to load many different JavaScript or CSS libraries into a page. This becomes particularly complex when plugins enter the mix, needing to load libraries.

In FarCry this problem is solved using skin:registerJS / skin:loadJS and skin:registerCSS / skin:loadCSS.

The "load" tags tell FarCry to add libraries to a stack to be inserted into the head at the end of the request. The register tags make it easy to define a library in one place, then load them many places without redundant data. Added benefits of loadJS and loadCSS:

automatically minification
de-duping - libraries with the same id are only loaded once overriding libraries - you can override a library defined in a plugin by re-registering it in your project
inline code - code between the open and closing tags is added to the end of the library, even if no actual files are specified
including multiple files in a single library

Here are some examples of how different libraries would be updated:

Example 1; CSS stylesheets

<!-- normal HTML library reference -->
<link media="screen" rel="stylesheet" type="text/css" href="/css/960.css">

<!-- /yourproject/config/_serverSpecificVarsAfterInit.cfm -->
<skin:registerCSS id="960" baseHREF="/css" lFiles="960.css" />


<!-- headerwebskin.cfm --> 
<skin:loadCSS id="960" />

Example 2; Conditional Javascript libraries

<!-- normal HTML library reference -->
<!--[if lt IE 7]>
<script type="text/javascript" src="/js/DD_belatedPNG_0.0.8a-min.js"></script>
<![endif]-->

<!-- /yourproject/config/_serverSpecificVarsAfterInit.cfm -->
<skin:registerJS id="png" condition="lt IE 7" baseHREF="/js" lFiles="DD_belatedPNG_0.0.8a-min.js" />

<!-- headerwebskin.cfm -->
<skin:loadJS id="png" />

Example 3; External library references

<!-- normal HTML library reference -->
<script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>

<!-- /plusoneplugin/config/_serverSpecificVarsAfterInit.cfm -->
<skin:registerJS id="plusone" lFiles="https://apis.google.com/js/plusone.js" />

<!-- plusonewebskin.cfm -->
<skin:loadJS id="plusone" />

Once you have updated your library references with loadJS/loadCSS see HTML like the following in the HEAD section of your web pages:

<!-- 
ID: 960
FILES: /css/960.css
-->
<link rel="stylesheet" type="text/css" href="/cache/960--1309753095000-C3608969AFF7EA8450DDC43B11362F20-D41D8CD98F00B204E9800998ECF8427E-D41D8CD98F00B204E9800998ECF8427E.css" media="screen" >

Combining libraries into a single file

Most web experts recommend that a website serve as few CSS and JS files as possible. FarCry's library loading functionality can take care of this too. After converting all your libraries to use loadJS and loadCSS, review your source and make a note of the groups of files that can be combined.

A typical example might be to combine jQuery with your site specific JavaScript.

<!-- Register these combined libraries in /yourproject/config/_serverSpecificVarsAfterInit.cfm -->
<skin:registerJS id="combined-project" lCombineIDs="jquery,projectjs" />

<!-- Load this new library in your pages -->
<skin:loadJS id="combined-project" />

If FarCry sees this combined library in the stack, it will automatically remove instances of it's child libraries.

Frequently Asked Questions

Q: Will the sequence of skin:loadJS calls be preserved by FarCry?
A: Yes, though loading a combined library overrides the position of any libraries it contains. Looking back at the example, if combined-project is loaded then any other attempts to load projectjs will be ignored.

Q: Are combined libraries minified too?
A: Yes. All CSS and JS libraries are minified.

Q: Can external libraries be combined with internal ones?
A: No, external libraries and internal libraries can't be mixed at this point.

Q: Are the media and condition attributes preserved in combined libraries?
A: No, a combined library needs to redefine all of the relevant attributes, including media and condition.