The JavaScriptManager

Calipso implements a set of JavaScript-related features that are managed by Comkarl.Web.JavaScriptManager class.

JavaScriptManager is responsible of:
After all, JavaScriptManager is a server control. In order to use it in any Master Page or Page, you'll need to register it on top of the .master or .aspx file:
<%@ Register Assembly="Comkarl.Web" Namespace="Comkarl.Web" TagPrefix="Calipso" %>

1. Understanding JavaScriptManager and its concepts

JavaScriptManager can manage two types of script files:

Includes and References.

JavaScriptManager has two different concepts that work together in order to define a JavaScript dependency:
Why includes and references? Calipso avoids spreading literal JavaScript file references across your pages, meaning that if you need to update a JavaScript file, you do in a single point and it affects the entire project.

Imagine that you've a JavaScript file called "\Scripts\MyFile.js". An include to this file would be:
Note that physical JavaScript files must be in your ASP.NET application root or in any subfolder.

And this JavaScript include would be referenced as "MyFile" in your pages. Question is: how to add includes and references?

How to add includes

Includes can be added by configuration or during run-time.

Any Calipso-enabled project must have a Calipso.config file.

In order to add it by configuration, go to the whole configuration file and add an include as child of <includes> elements inside <javascriptManager> element.


A file kind include looks like this
<add id="MyFile" source="/Scripts/MyFile.js" kind="File" />


A resource kind include looks like this
<add id="MyFile" source="SomePath.Other.Blah.js, AssemblyName" kind="Resource" />


An external resource kind include looks like this
<add id="MyFile" source="http://mypage.com/myfile.js" kind="ExternalUrl" />


To add it during run-time, you can do in various levels.

How to add references

Once you've some includes configured, for example an include having "MyFile" as identifier, if you want your script file in some concrete page, there're two ways of telling JavaScriptManager to do so:
<Calipso:JavaScriptManager CombinedFileName="Some.js" runat="server">
   <References>
         <Calipso:JavaScriptRef RefId="MyFile" />
    </References>
</Calipso:JavaScriptManager>

Includes of embedded JavaScript files and external files

In addition to include JavaScript files that points to a local file system location, JavaScriptManager supports embedded files and external URLs to files.

Embedded JavaScriptFiles

In order to make an include to an embedded JavaScript, either adding the include in code or in your JavaScriptManager configuration file, you must give include arguments like this:

External URLs

Sometimes you may need to add external JavaScript files, for example ones from CDN or external APIs. For example, http://somedomain.com/scripts/MyFile.js.

In this case you would be giving this arguments in code or in your JavaScriptManager.config:

Arbitrary JavaScript files executed in the client-side and defined in the server-side as literals or variables

JavaScriptManager supports an approach to execute some JavaScript code in the client-side that's defined in the server-side. Note that this should be used carefully because it's a feature that's available for a limited number of cases.

This can only be made in code in the server side and it's available in page-level and control-level.

An example of doing so would be this code:
JavaScriptManager.RegisterAfterLoadScript("MyArbitraryCode", "var a = \"hello world\";");


Arbitrary code could aid some developments in doing very specific tasks like initializing some API, setting some default value to some variable, object property or things like that in the client-side from the server-side.

2. JavaScriptManager file caching, combination and minification

Every reference that's included in an actual page, even if this happened in code or in the JavaScriptManager server control, gets cached as a temporal file in the specified folder by the cachePath in the Calipso.config file located in your application root, as an attribute of <javascriptManager> element (f.e. <javascriptManager cachePath="~\js">...).

JavaScriptManager works in two modes: debug and release. This is defined in the standard Web.config:
  <system.web>
    <compilation debug="true" targetFramework="4.0" />
  </system.web>


When JavaScript manager is in...
JavaScriptManager doesn't combine ALL JavaScript code in a single file. It combines all referenced files by a JavaScriptManager instance.

For example, if your Master Page has its JavaScriptManager, it'll combine and compress all referenced JavaScript files for this concrete instance. Later, some Content Page may have it's own JavaScriptManager, so this will combine and compress its own references, and so on.

REMEMBER that no JavaScriptManager will work properly if you didn't give the combined file name:
<Calipso:JavaScriptManager ID="blah" CombinedFileName="Master.js" runat="server" />

Other important point is that application pool's identity must have read-write access to the temporal directory where Calipso places cached JavaScript files!.

When JavaScript files get cached?

JavaScript file caching occurs in run-time. First time an user request a page, JavaScriptManager will generate the necessary file cache, and after that, subsequent requests will be using the already created one.

3. Standalone references: non-combined JavaScript sources.

Sometimes a project may require that a particular JavaScript file don't get combined with the rest of ones because it should be cached alone at the browser-level (or other reasons).

Calipso introduces standalone references. In other words, a standalone reference will render a script tag in the browser and the JavaScript file behind the scenes will not be combined with others.

Standalone references configured in design time

That is configuring a standalone reference in the server JavaScript control in some master page or content page:
<Calipso:JavaScriptManager CombinedFileName="Some.js" runat="server">
   <References>
         <Calipso:JavaScriptRef RefId="MyFile" Standalone="true" /> /* NOTE THE SECOND ATTRIBUTE!! */
    </References>
</Calipso:JavaScriptManager>

Standalone references configuring during run-time

That is configuring a standalone reference in server code:

JavaScriptManager.RegisterReference("MyFile", true); /* SECOND PARAMETER IS "STANDALONE" TRUE OR FALSE */