In CMS frameworks you often find yourself needing to load many different JavaScript or CSS libraries within 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 custom tags.
The “load” tags tell FarCry to add libraries to a stack to be inserted into the <HEAD> at the end of the page request.
The “register” tags allow developers to define a library in one place, then load them many places without redundant data.
Added benefits of loadJS and loadCSS:
- automatic minification
- de-duping (libraries with the same
idare only loaded once even if they are referenced by multiple views in the one request) - 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
- aggregate multiple files in a single library
Usage
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">
Is replaced with…
<!-- /yourproject/config/_serverSpecificVarsAfterInit.cfm -->
<skin:registerCSS id="960" baseHREF="/css" lFiles="960.css" />
```
``` markup`
<!-- 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]-->
Is replaced with…
``` markup`
<skin:registerJS id=“png” condition=“lt IE 7” baseHREF="/js" lFiles=“DD_belatedPNG_0.0.8a-min.js” />
``` markup`
<!-- headerwebskin.cfm -->
<skin:loadJS id="png" />
Example 3; External library references
``` markup`
Is replaced with...
``` markup`
<!-- /plusoneplugin/config/_serverSpecificVarsAfterInit.cfm -->
<skin:registerJS id="plusone" lFiles="https://apis.google.com/js/plusone.js" />
``` markup`
<skin:loadJS id=“plusone” />
Once you have updated your library references with `loadJS`/`loadCSS` you will see HTML like the following in the HEAD section of your web pages:
``` markup
<!--
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.
``` markup`
<skin:registerJS id=“combined-project” lCombineIDs=“jquery,projectjs” />
``` markup`
<!-- 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?
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?
Yes. All CSS and JS libraries are minified.
Q: Can external libraries be combined with internal ones?
No, external libraries and internal libraries can’t be mixed at this point.
Q: Are the media and condition attributes preserved in combined libraries?
No, a combined library needs to redefine all of the relevant attributes, including media and condition.
Thanks!