One thing that I’ve come to appreciate in
control development in ASP.NET that use JavaScript is
the ability to have more
control over script and script include placement than ASP.NET provides natively. Specifically in ASP.NET you can use either
the ClientScriptManager or ScriptManager to embed scripts and script references into pages via code. This works reasonably well, but
the script references that get generated are generated into
the HTML body and there’s very little operational
control for placement of scripts. If you have multiple controls or several of
the same
control that need to place
the same scripts onto
the page it’s not difficult to end up with scripts that render in
the wrong order and stop working correctly. This is especially critical if you load script libraries with dependencies either via resources or even if you are rendering referenced to CDN resources. Natively ASP.NET provides a host of methods that help embedding scripts into
the page via either Page.ClientScript or
the ASP.NET ScriptManager
control (both with slightly different syntax): RegisterClientScriptBlock Renders a script block at
the top of
the HTML body and should be used for embedding callable functions/classes. RegisterStartupScript Renders a script block just prior to
the </form> tag and should be used to for embedding code that should execute when
the page is first loaded. Not recommended – use jQuery.ready() or equivalent load time routines. RegisterClientScriptInclude Embeds a reference to a script from a url into
the page. RegisterClientScriptResource Embeds a reference to a Script from a resource file generating a long resource file string All 4 of these methods render their <script> tags into
the HTML body.
The script blocks give you a little bit of
control by having a ‘top’ and ‘bottom’ of
the document location which gives you some flexibility over script placement and precedence. Script includes and resource url unfortunately do not even get that much
control – references are simply rendered into
the page in
the order of declaration.
The ASP.NET ScriptManager
control facilitates this task a little bit with
the abililty to specify scripts in code and
the ability to programmatically check what scripts have already been registered, but it doesn’t provide
any more
control over
the script rendering process itself. Further
the ScriptManager is a bear to deal with generically because generic code has to always check and see if it is actually present. Some time ago I posted a ClientScriptProxy class that helps with managing
the latter process of sending script references either to ClientScript or ScriptManager if it’s available. Since I last posted about this there have been a number of improvements in this API, one of which is
the ability to
control placement of scripts and script includes in
the page which I think is rather important and a missing feature in
the ASP.NET native functionality. Handling ScriptRenderModes One of
the big enhancements that I’ve come to rely on is
the ability of
the various script rendering functions described above to support rendering in multiple locations: /// <summary>
/// Determines how scripts are included into
the page
/// </summary>
public enum ScriptRenderModes
{
/// <summary>
/// Inherits
the setting from
the control or from
the ClientScript.DefaultScriptRenderMode
/// </summary>
Inherit,
/// Renders
the script include at
the location of
the control
/// </summary>
Inline,
/// <summary>
/// Renders
the script include into
the bottom of
the header of
the page
/// </summary>
Header,
/// <summary>
/// Renders
the script include into
the top of
the header of
the page
/// </summary>
HeaderTop,
/// <summary>
/// Uses ClientScript or ScriptManager to embed
the script include to
/// provide standard ASP.NET style rendering in
the HTML body.
/// </summary>
Script,
/// <summary>
/// Renders script at
the bottom of
the page before
the last Page.Controls
/// literal
control. Note this may result in unexpected behavior
/// if /body and /html are not
the last thing in
the markup page.
/// </summary>
BottomOfPage
}
This enum is then applied to
the various Register functions to allow more
control over where scripts actually show up. Why is this useful? For me I often render scripts out of
control resources and these scripts often include things like a JavaScript Library (jquery) and a few plug-ins.
The order in which these can be loaded is critical so that jQuery.js always loads before
any plug-in for example.
Typically I end up with a general script layout like this:
Core Libraries- HeaderTop
Plug-ins: Header
ScriptBlocks: Header or Script depending on other dependencies
There’s also an option to render scripts and CSS at
the very bottom of
the page before
the last Page
control on
the page which can be useful for speeding up page load when lots of scripts are loaded.
The API syntax of
the ClientScriptProxy methods is closely compatible with ScriptManager’s using static methods and
control references to gain access to
the page and embedding scripts.
For example, to render some script into
the current page in
the header:
// Create script block in header
ClientScriptProxy.Current.RegisterClientScriptBlock(this, typeof(ControlResources),
"hello_function", "function helloWorld() { alert('hello'); }", true,
ScriptRenderModes.Header);
// Same again - shouldn't be rendered because it's
the same id
ClientScriptProxy.Current.RegisterClientScriptBlock(this, typeof(ControlResources),
"hello_function", "function helloWorld() { alert('hello'); }", true,
ScriptRenderModes.Header);
// Create a second script block in header
ClientScriptProxy.Current.RegisterClientScriptBlock(this, typeof(ControlResources),
"hello_function2", "function helloWorld2() { alert('hello2'); }", true,
ScriptRenderModes.Header);
// This just calls ClientScript and renders into bottom of document
ClientScriptProxy.Current.RegisterStartupScript(this,typeof(ControlResources),
"call_hello", "helloWorld();helloWorld2();", true);
which generates:
<html xmlns="http://www.w3.org/1999/xhtml" >
<head><title>
</title>
<script type="text/javascript">
function helloWorld() { alert('hello'); }
</script>
<script type="text/javascript">
function helloWorld2() { alert('hello2'); }
</script>
</head>
<body>
…
<script type="text/javascript">
//<![CDATA[
helloWorld();helloWorld2();//]]>
</script>
</form>
</body>
</html>
Note that
the scripts are generated into
the header rather than
the body except for
the last script block which is
the call to RegisterStartupScript. In general I wouldn’t recommend using RegisterStartupScript – ever. It’s a much better practice to use a script base load event to handle ‘startup’ code that should fire when
the page first loads. So instead of
the code above I’d actually recommend doing:
ClientScriptProxy.Current.RegisterClientScriptBlock(this, typeof(ControlResources),
"call_hello", "$().ready( function() { alert('hello2'); });", true,
ScriptRenderModes.Header);
assuming you’re using jQuery on
the page.
For script includes from a Url
the following demonstrates how to embed scripts into
the header. This example injects a jQuery and jQuery.UI script reference from
the Google CDN then checks each with a script block to ensure that it has loaded and if not loads it from a server local location:
// load jquery from CDN
ClientScriptProxy.Current.RegisterClientScriptInclude(this, typeof(ControlResources),
"http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js",
ScriptRenderModes.HeaderTop);
// check if jquery loaded - if it didn't we're not online
string scriptCheck =
@"if (typeof jQuery != 'object')
document.write(unescape(""%3Cscript src='{0}' type='text/javascript'%3E%3C/script%3E""));";
string jQueryUrl = ClientScriptProxy.Current.GetWebResourceUrl(this, typeof(ControlResources),
ControlResources.JQUERY_SCRIPT_RESOURCE);
ClientScriptProxy.Current.RegisterClientScriptBlock(this, typeof(ControlResources),
"jquery_register", string.Format(scriptCheck,jQueryUrl),true,
ScriptRenderModes.HeaderTop);
// Load jquery-ui from cdn
ClientScriptProxy.Current.RegisterClientScriptInclude(this, typeof(ControlResources),
"http://ajax.googleapis.com/ajax/libs/jqueryui/1.7.2/jquery-ui.min.js",
ScriptRenderModes.Header);
// check if we need to load from local
string jQueryUiUrl = ResolveUrl("~/scripts/jquery-ui-custom.min.js");
ClientScriptProxy.Current.RegisterClientScriptBlock(this, typeof(ControlResources),
"jqueryui_register", string.Format(scriptCheck, jQueryUiUrl), true,
ScriptRenderModes.Header);
// Create script block in header
ClientScriptProxy.Current.RegisterClientScriptBlock(this, typeof(ControlResources),
"hello_function", "$().ready( function() { alert('hello'); });", true,
ScriptRenderModes.Header);
which in turn generates this HTML:
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"></script>
<script type="text/javascript">
if (typeof jQuery != 'object')
document.write(unescape("%3Cscript src='/WestWindWebToolkitWeb/WebResource.axd?d=DIykvYhJ_oXCr-TA_dr35i4AayJoV1mgnQAQGPaZsoPM2LCdvoD3cIsRRitHKlKJfV5K_jQvylK7tsqO3lQIFw2&t=633979863959332352' type='text/javascript'%3E%3C/script%3E"));
</script>
<title>
</title>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.7.2/jquery-ui.min.js" type="text/javascript"></script>
<script type="text/javascript">
if (typeof jQuery != 'object')
document.write(unescape("%3Cscript src='/WestWindWebToolkitWeb/scripts/jquery-ui-custom.min.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
$().ready(function() { alert('hello'); });
</script>
</head>
<body>
…</body>
</html>
As you can see there’s a bit more
control in this process as you can inject both script includes and script blocks into
the document at
the top or bottom of
the header, plus if necessary at
the usual body locations. This is quite useful especially if you create custom server controls that interoperate with script and have certain dependencies.
The above is a good example of a useful switchable routine where you can switch where scripts load from by default –
the above pulls from Google CDN but a configuration switch may automatically switch to pull from
the local development copies if your doing development for example.
How
does it work?
As mentioned
the ClientScriptProxy object mimicks many of
the ScriptManager script related methods and so provides close API compatibility with it although it contains many additional overloads that enhance functionality. It
does however work against ScriptManager if it’s available on
the page, or Page.ClientScript if it’s not so it provides a single unified frontend to script access. There are however many overloads of
the original SM methods like
the above to provide additional functionality.
The implementation of script header rendering is pretty straight forward – as long as a server header (ie. it has to have runat=”server” set) is available. Otherwise these routines fall back to using
the default document level insertions of ScriptManager/ClientScript. Given that there is a server header it’s relatively easy to generate
the script tags and code and append them to
the header either at
the top or bottom. I suspect Microsoft didn’t provide header rendering functionality precisely because a runat=”server” header is not required by ASP.NET so behavior would be slightly unpredictable. That’s not really a problem for a custom implementation however.
Here’s
the RegisterClientScriptBlock implementation that takes a ScriptRenderModes parameter to allow header rendering:
/// <summary>
/// Renders
client script block with
the option of rendering
the script block in
///
the Html header
///
/// For this to work Header must be defined as runat="server"
/// </summary>
/// <param name="
control">any
control that instance typically page</param>
/// <param name="type">Type that identifies this rendering</param>
/// <param name="key">unique script block id</param>
/// <param name="script">The script code to render</param>
/// <param name="addScriptTags">Ignored for header rendering used for all other insertions</param>
/// <param name="renderMode">Where
the block is rendered</param>
public void RegisterClientScriptBlock(Control
control, Type type, string key, string script, bool addScriptTags, ScriptRenderModes renderMode)
{
if (renderMode == ScriptRenderModes.Inherit)
renderMode = DefaultScriptRenderMode;
if (control.Page.Header == null ||
renderMode != ScriptRenderModes.HeaderTop &&
renderMode != ScriptRenderModes.Header &&
renderMode != ScriptRenderModes.BottomOfPage)
{
RegisterClientScriptBlock(control, type, key, script, addScriptTags);
return;
}
// No dupes - ref script include only once
const string identifier = "scriptblock_";
if (HttpContext.Current.Items.Contains(identifier + key))
return;
HttpContext.Current.Items.Add(identifier + key, string.Empty);
StringBuilder sb = new StringBuilder();
// Embed in header
sb.AppendLine("\r\n<script type=\"text/javascript\">");
sb.AppendLine(script);
sb.AppendLine("</script>");
int? index = HttpContext.Current.Items["__ScriptResourceIndex"] as int?;
if (index == null)
index = 0;
if (renderMode == ScriptRenderModes.HeaderTop)
{
control.Page.Header.Controls.AddAt(index.Value, new LiteralControl(sb.ToString()));
index++;
}
else if(renderMode == ScriptRenderModes.Header)
control.Page.Header.Controls.Add(new LiteralControl(sb.ToString()));
else if (renderMode == ScriptRenderModes.BottomOfPage)
control.Page.Controls.AddAt(control.Page.Controls.Count-1,new LiteralControl(sb.ToString()));
HttpContext.Current.Items["__ScriptResourceIndex"] = index;
}
Note that
the routine has to keep track of items inserted by id so that if
the same item is added again with
the same key it won’t generate two script entries. Additionally
the code has to keep track of how many insertions have been made at
the top of
the document so that entries are added in
the proper order.
The RegisterScriptInclude method is similar but there’s some additional logic in here to deal with script file references and ClientScriptProxy’s (optional) custom resource handler that provides script compression
/// <summary>
/// Registers a
client script reference into
the page with
the option to specify
///
the script location in
the page
/// </summary>
/// <param name="
control">Any
control instance - typically page</param>
/// <param name="type">Type that acts as qualifier (uniqueness)</param>
/// <param name="url">the Url to
the script resource</param>
/// <param name="ScriptRenderModes">Determines where
the script is rendered</param>
public void RegisterClientScriptInclude(Control
control, Type type, string url, ScriptRenderModes renderMode)
{
const string STR_ScriptResourceIndex = "__ScriptResourceIndex";
if (string.IsNullOrEmpty(url))
return;
if (renderMode == ScriptRenderModes.Inherit)
renderMode = DefaultScriptRenderMode;
// Extract just
the script filename
string fileId = null;
// Check resource IDs and try to match to mapped file resources
// Used to allow scripts not to be loaded more than once whether
// embedded manually (script tag) or via resources with ClientScriptProxy
if (url.Contains(".axd?r="))
{
string res = HttpUtility.UrlDecode( StringUtils.ExtractString(url, "?r=", "&", false, true) );
foreach (ScriptResourceAlias item in ScriptResourceAliases)
{
if (item.Resource == res)
{
fileId = item.Alias + ".js";
break;
}
}
if (fileId == null)
fileId = url.ToLower();
}
else
fileId = Path.GetFileName(url).ToLower();
// No dupes - ref script include only once
const string identifier = "script_";
if (HttpContext.Current.Items.Contains( identifier + fileId ) )
return;
HttpContext.Current.Items.Add(identifier + fileId, string.Empty);
// just use script manager or ClientScriptManager
if (control.Page.Header == null || renderMode == ScriptRenderModes.Script || renderMode == ScriptRenderModes.Inline)
{
RegisterClientScriptInclude(control, type,url, url);
return;
}
// Retrieve script index in header
int? index = HttpContext.Current.Items[STR_ScriptResourceIndex] as int?;
if (index == null)
index = 0;
StringBuilder sb = new StringBuilder(256);
url = WebUtils.ResolveUrl(url);
// Embed in header
sb.AppendLine("\r\n<script src=\"" + url + "\" type=\"text/javascript\"></script>");
if (renderMode == ScriptRenderModes.HeaderTop)
{
control.Page.Header.Controls.AddAt(index.Value, new LiteralControl(sb.ToString()));
index++;
}
else if (renderMode == ScriptRenderModes.Header)
control.Page.Header.Controls.Add(new LiteralControl(sb.ToString()));
else if (renderMode == ScriptRenderModes.BottomOfPage)
control.Page.Controls.AddAt(control.Page.Controls.Count-1, new LiteralControl(sb.ToString()));
HttpContext.Current.Items[STR_ScriptResourceIndex] = index;
}
There’s a little more code here that deals with cleaning up
the passed in Url and also some custom handling of script resources that run through
the ScriptCompressionModule –
any script resources loaded in this fashion are automatically cached based on
the resource id. Raw urls extract just
the filename from
the URL and cache based on that. All of this to avoid doubling up of scripts if called multiple times by multiple instances of
the same
control for example or several controls that all load
the same resources/includes.
Finally RegisterClientScriptResource utilizes
the previous method to wrap
the WebResourceUrl as well as some custom functionality for
the resource compression module:
/// <summary>
/// Returns a WebResource or ScriptResource URL for script resources that are to be
/// embedded as script includes.
/// </summary>
/// <param name="
control">Any control</param>
/// <param name="type">A type in assembly where resources are located</param>
/// <param name="resourceName">Name of
the resource to load</param>
/// <param name="renderMode">Determines where in
the document
the link is rendered</param>
public void RegisterClientScriptResource(Control
control, Type type,
string resourceName,
ScriptRenderModes renderMode)
{
string resourceUrl = GetClientScriptResourceUrl(control, type, resourceName);
RegisterClientScriptInclude(control, type, resourceUrl, renderMode);
}
/// <summary>
/// Works like GetWebResourceUrl but can be used with javascript resources
/// to allow using of resource compression (if
the module is loaded).
/// </summary>
/// <param name="
control"></param>
/// <param name="type"></param>
/// <param name="resourceName"></param>
/// <returns></returns>
public string GetClientScriptResourceUrl(Control
control, Type type, string resourceName)
{
#if IncludeScriptCompressionModuleSupport
// If wwScriptCompression Module through Web.config is loaded use it to compress
// script resources by using wcSC.axd Url
the module intercepts
if (ScriptCompressionModule.ScriptCompressionModuleActive)
{
string url = "~/wwSC.axd?r=" + HttpUtility.UrlEncode(resourceName);
if (type.Assembly != GetType().Assembly)
url += "&t=" + HttpUtility.UrlEncode(type.FullName);
return WebUtils.ResolveUrl(url);
}
#endif
return
control.Page.ClientScript.GetWebResourceUrl(type, resourceName);
}
This code merely retrieves
the resource URL and then simply calls back to RegisterClientScriptInclude with
the URL to be embedded which means there’s nothing specific to deal with other than
the custom compression module logic which is nice and easy.
What else is there in ClientScriptProxy?
ClientscriptProxy also provides a few other useful services beyond what I’ve already covered here:
Transparent ScriptManager and ClientScript calls
ClientScriptProxy includes a host of routines that help figure out whether a script manager is available or not and all functions in this class call
the appropriate object – ScriptManager or ClientScript – that is available in
the current page to ensure that scripts get embedded into pages properly. This is especially useful for
control development where controls have no
control over
the scripting environment in place on
the page.
RegisterCssLink and RegisterCssResource
Much like
the script embedding functions these two methods allow embedding of CSS links. CSS links are appended to
the header or to a form declared with runat=”server”.
LoadControlScript
Is a high level resource loading routine that can be used to easily switch between different script linking modes. It supports loading from a WebResource, a url or not loading anything at all. This is very useful if you build controls that deal with specification of resource urls/ids in a standard way.
Check out
the full Code
You can check out
the full code to
the ClientScriptProxyClass here:
ClientScriptProxy.cs
ClientScriptProxy Documentation (class reference)
Note that
the ClientScriptProxy has a few dependencies in
the West Wind Web Toolkit of which it is part of. ControlResources holds a few standard constants and script resource links and
the ScriptCompressionModule which is referenced in a few of
the script inclusion methods.
There’s also another useful ScriptContainer companion control to
the ClientScriptProxy that allows scripts to be placed onto
the page’s markup including
the ability to specify
the script location and script minification options.
You can find all
the dependencies in
the West Wind Web Toolkit repository:
West Wind Web Toolkit Repository
West Wind Web Toolkit Home Page© Rick Strahl, West Wind Technologies, 2005-2010Posted in ASP.NET JavaScript
