Finally, we reach the part which is at the heart of the JavascriptHelper, the jslibraries.xml file. It’s a bit complex, but the default I’ve set up is probably good enough, with perhaps only a few minor tweaks, and once fully configured to your taste, you could easily standardize on that for your whole enterprise. It is, however, simple enough that a NuGet package could update it when being added to a project. And the good news is that I’ve also create a XSD schema file for it, so you can have IntelliSense to help you along.

The root element is <libraries> and it has four optional attributes:

localjspath=” which gives the relative location of the folder where you put your JS files. The default is “~/Scripts” which is the ASP.NET MVC default.

selfJsPath=” which gives the relative location of the folder under which you put your view-specific JS files. They follow the same structure as view files, so if you request the JS file for /Home/Index, the view file would be /Views/Home/Index.cshtml, and the JS file used would be /Scripts/Views/Home/Index.js. Defaults to “~/Script/Views”

useDebugScripts=” when set to “true” forces use of debug versions of JS files when available. Default is false. Debug scripts are always used when a debugger is attached.

transform=” which controls bundling and compression and takes one of three options: “None”, “BundleOnly”, and “Compress”. They should be self-explanatory. The default is “None”, so you must add the option to see any effect.

<library name="jquery" version="1.6.2" useGoogle="false" pathname="jquery-1.6.1.min.js"
 debugPath="jquery-1.6.1.js" transform="compress" /> 

Within the <libraries> element, there is a collection of <library> elements – one for each standard javascript file you’ll be using-- which have two required and several optional attributes:
name=” which gives a unique name for a particular javascript file. It is required and is used by the helper and throughout the xml file to refer to that file.

There is one special library name, “base” which I’ll explain below.

pathname=” which gives the path, relative to the localjspath described above, and filename of this file. This can also be a fully-qualified URL if it’s a remote file. It is required. (unless useGoogle is true, or name=”base”)

debugPath=” which, like the pathname attribute, gives the relative path to a javascript file to be used when debugging. This is optional and defaults to the value given for the pathname. The idea here is the you set the debugPath to the full, commented version, and the pathname to the mini-fied version, and the helper figures out which to use.

dependsOn” which is a list of comma separated names of files, which must be loaded before this one. This is the most powerful feature, but also the most confusing, so we’ll expand upon it in a moment. It is optional and defaults to no dependencies

alias=” which is a list of comma separated alternate names this file could be identified as. I added this because I could never remember if it’s “accordion” or “accordian”. This is optional and defaults to no aliases.

css=” which gives the name of the css element (see below) associated with this file.

useGoogle=” which, when set to true, will generate a request to the googleapi.com CDN to load the file. Optional, defaults to false. If true, “version” attribute is required.

version=” is used only when “useGoogle” is true. Gives the version of the file to load from Google.

Also within the <libraries> element (at the same level as the <library> elements), there is the <css> group.

The <css> element has only one attribute “localcsspaath” which gives the relative location of the folder where you put your CSS files. The default is “~/Content” which is the ASP.NET MVC default.
Within the <css> element, there are multiple <sheet> elements, one for each css file associated with a js file. They have two required attributes:

name=” Unique name used to identified the particular css file. Matches name given in the “css” attribute in the <library> element above. Can be the same as the name used for the js file in the <library> element.

pathname=” which gives the path, relative to the localcsspath described above, and filename of this file.

I realized that sometimes you’ll want a JavaScript file loaded on every page (before you say “jQuery!” remember, that’s handled by the dependencies). OK, what you really want to a particular CSS file loaded on every page. JavascriptHelper now offer a way to handle that and include them in bundling. Define a <library> entry with the name of “base”. You don’t need to specify a path name for it, but include a dependsOn attribute which specifies the JS files you always want loaded. Then add a <sheet> element named “base” which has a pathname of your standard CSS file (“site.css” if you
follow the MVC4 defaults).

Example:

<library name="jquery" version="1.6.1" useGoogle="false" pathname="jquery-1.6.1.min.js"
 debugPath="jquery-1.6.1.js" />
<library name="uicore" dependsOn="jquery" pathname="ui/jquery.ui.core.js"/>
<library name="uiwidget" dependsOn="uicore" pathname="ui/jquery.ui.widget.js"/>
<library name="mouse" dependsOn="uiwidget" pathname="ui/jquery.ui.mouse.js"/>
<library name="datepicker" dependsOn="uiwidget" 
 pathname="ui/jquery.ui.datepicker.js" css="ui" />
<library name="slider" dependsOn="uiwidget,mouse"
 pathname="ui/jquery.ui.slider.js" css="ui" /> 

 

Starting with the first element, we specified a JavaScript file, which we’ll be calling “jquery”. When we ask for “jquery”, we’ll normally get “jquery-1.6.1.min.js” , unless we’re debugging, in which case, it will load “jquery-1.6.1.js”. It will load these from the website, but, if, as I put it into production, I flip the useGoogle file to true, then it will load it from http://ajax.googleapis.com/ajax/libs/jquery/1.6.1/jquery.js

(Note that the “name” value is used to the googleapis URL here. Normally, the name can just be any unique string. But, this is the only place where the actual name used is significant. This is wrong, and will be fixed in some future release).

Next we want to define the complete componentized version of jQuery UI, so that we can load just the parts we want. First, we declare the UI core as depending on jQuery. Then we declare widget component as depending on the core. And the mouse component as depending on the widgets.

Then we can add the individual components themselves. “datepicker” as depending on the widgets; “slider” as depending on the widget & the mouse components. Since the mouse already depends on widget, it wasn't really necessary to specify both here, but there’s no harm. So, if you request to use “slider” on your page, then the helper makes sure that jQuery, the UI core, UI Widgets, mouse & slider components are all included, in the proper order. (Note, there is no checking for circular dependencies, so be careful how you specify the dependsOn attribute)
Both are also associated with the “ui” css file, which brings us to that section:

<css localcsspath="~/content/css/Views">
 <sheet name="ui" pathname="ui/themes/Redmond/jquery-ui-1.8.13.custom.css" />
 <sheet name="cluetip" pathname="jquery.cluetip.css" />
</css> 

Both of the jQuery UI components above give “ui” as their CSS file (the theme roller doesn’t create individual CSS files) so if either (or both) is used, that file is included. CSS files don’t have a separate dependency tree, but all associated CSS files for every dependent js file up the tree are included, so if you wanted to use the separate jQuery UI CSS files, you’d associate “ui.core.css” with uicode”, “ui.base.css” with “uiwidget” and each component with its own CSS file, and all the needed files will be included.

Last edited Jun 21, 2012 at 5:34 AM by JamesCurran, version 1

Comments

No comments yet.