JavaScript dependency management
Quick links
ASP.NET Calipso has a built-in JavaScript source files management.
It can manage three kinds of JavaScript source files:
- File. A JavaScript source file located in the physical file system of Web application.
- Resource. An embedded into an assembly JavaScript source file.
- ExternalUrl. An URI/URL to a JavaScript source file.
JavaScript dependency management is performed by
Comkarl.Web.UI.JavaScriptManager class, which is also a regular ASP.NET Web Forms server control.
Includes and references
A key feature on Calipso is that JavaScript files are included in pages using references instead of a regular URL or relative file paths. That's an advantage because dependencies are used across lots of pages and their sources can be easly relocated in a single place.
In summary...
- Includes are pointers to files of file, resource or external url kind. These have an unique identifier.
- References are pointers to includes. An include is referenced by its unique identifier.
In addition, there two types of includes:
- Static. Static includes are ones added by configuration and they are loaded by JavaScriptManager during its initialization.
- Dynamic. Dynamic includes are ones added during run-time, also loaded by JavaScriptManager.
First step when some JavaScript file is required by some page within ASP.NET Calipso is configure it as an include for later reference it. Learn how!
Includes
How to configure static includes
Static includes are configured into XML
Calipso.config configuration file located in the root of ASP.NET Web application.
Locate
<includes>...</includes> XML child element of
<javascriptManager>...</javascriptManager> configuration element.
Append an
<add /> element like next samples depending on where is stored the original JavaScript file.
File-kind include sample
This is a sample of how to include a script file called
MyFile.js located in a
Scripts directory in the root of ASP.NET Web application:
<add id="MyFile" source="/Scripts/MyFile.js" kind="File"/>
Resource-kind include sample
This is a sample of how to include a script file called
MyFile.js embedded into an assembly
MyAssembly.
An embedded JavaScript file path will be the full namespace to the embedded file. In this sample, it is
MySampleProject.Files.MyFile.js:
<add id="MyFile" source="MySampleProject.Files.MyFile.js, MyAssembly" kind="Resource"/>
ExternalUrl-kind include sample
This is a sample of how to include a script file called
MyFile.js hosted in some remote site:
<add id="MyFile" source="http://www.mysite.com/scripts/myfile.js" kind="ExternalUrl"/>
How to configure dynamic includes
Dynamic includes are configured during run-time from a
ScriptControl in server-side code.
In order to add dynamic includes, bind an event handler to any event of
ScriptControl life-cycle. That is, one of these:
How to configure a File-kind dynamic include
An include of File kind is a one pointing to a physical file in the ASP.NET Web Application's file system.
From within a
ScriptControl, a JavaScript file called "MyFile.js" located in
/Scripts would be added this way:
using Comkarl.Web.Resources;
.........
protected override void OnLoad(System.EventArgs e)
{
JavaScriptManager.RegisterInclude("MyFile", "/Scripts/MyFile.js", ResourceKind.File);
}
..................
How to configure a Resource-kind dynamic include
An include of File kind is a one pointing to an embedded resource file into some assembly.
From within a
ScriptControl, a JavaScript file called "MyFile.js" embedded into assembly
MyAssembly would be added this way:
using Comkarl.Web.Resources;
.........
protected override void OnLoad(System.EventArgs e)
{
JavaScriptManager.RegisterInclude("MyFile", "Namespace.NamespaceB.MyFile.js", ResourceKind.Resource);
}
..................
How to configure a ExternalUrl-kind dynamic include
An include of ExternalUrl kind is a one pointing to a remote host and is specified using an URI/URL.
From within a
ScriptControl, a JavaScript file called "MyFile.js" would be configured this way:
using Comkarl.Web.Resources;
.........
protected override void OnLoad(System.EventArgs e)
{
JavaScriptManager.RegisterInclude("MyFile", "http://www.myweb.com/scripts/myfile.js", ResourceKind.ExternalUrl);
}
..................
References
A reference is a pointer to an include. Once an include is configured, either if it is static or dynamic, references are added using
JavaScriptManager as server control in some
Master Page or
regular pages.
First of all, add a
JavaScriptManager control to some
Master Page or
regular page if there is no other already in there.
JavaScriptManager server control supports a child control element called
References. In order to add a reference to some include, first add a
<References>...</References> element as child of
<calipso:JavaScriptManager ........>.......</JavaScriptManager>.
Finally, add a
<calipso:ResourceReference RefId="[identifier of some include]" />.
For example, this would be a full code for adding a reference to an include with
id "MyFile":
<calipso:JavaScriptManager ID="myJsManager" runat="server">
<References>
<calipso:ResourceReference RefId="MyFile" />
</References>
<calipso:JavaScriptManager>
Received HTML markup in some Web browser will have the appropiate
<script src="......." type="text/javascript"><script> including the whole JavaScript file.
References can also be added during run-time in a
ScriptControl:
protected override void OnLoad(System.EventArgs e)
{
JavaScriptManager.RegisterReference("MyFile");
}
Standalone references
Regular references will be added as separate
script tags in the rendered HTML markup if Web application is working in
debug mode, but once it is configured to work in
release mode, JavaScriptManager will combine and minify JavaScript files.
Sometimes a particular JavaScript file should be not combined and minified. Either if the original include was statically or dinamically added to the JavaScriptManager, includes can be referenced marking the reference as standalone. That is, it will not be combined and minified.
References added in the JavaScriptManager control tag should be marked as
standalone this way:
<calipso:ResourceReference RefId="MyFile" Standalone="true" />
Ones added during run-time within a
ScriptControl:
JavaScriptManager.RegisterReference("MyFile", true);