Loading Javascript & CSS Libraries

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 id are 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


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>

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.


Hi. I am very new to FarCry. I cant find the file mentioned in Example 1 above called headerwebskin.cfm. So I thought maybe I need to create one. I tried that but it didn’t seem to take any notice, probably in the wrong place? Where would that file go? Do I need to Update the app via admin once I change something like that?

I am using the Chelsea skeleton for my project and was testing how to create my own CSS “overrides” by including my css file after the bootstrap.css and main.css. Am I on the right track here?


Taking Chelsea as an example, the standard webskin structure for a HTML page is;

  • displayPageStandard
    • displayHeaderStandard
    • displayBody
    • displayFooterStandard

The files in the projects webskin/types folder contain the generic webskins that might apply to any content type on a generic level.

If you look in webskin/tyoes/displayHeaderStandard.cfm you’ll see that the CSS is included by normal HTML <style> elements on lines 21 and 22:

So you could place your custom CSS overrides after this :slight_smile:

For changes to existing webskins you generally don’t need to do an Update App, restarting the application is only necessary when you have made changed to components, or added new components or new webskins.

The Jump Start course is a great place to start, in particular the sections on webskins (aka views):

OK! Sorry, missed that! :slight_smile: Thanks!

Thanks again for your detailed reply Justin. As you see Geoff pointed me at the Jump Start course which I had missed which also helps explain things.

Much appreciated,