clientdependency Wiki & Documentation Rss Feed

Updated Wiki: Home

Shandem — Wed, 17 Apr 2013 02:57:17 GMT

Project has been moved to GitHub:

https://github.com/Shandem/ClientDependency

Updated Wiki: Home

Shandem — Wed, 17 Apr 2013 02:56:08 GMT

Project has been moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: Documentation

Shandem — Wed, 17 Apr 2013 02:16:31 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: ForcedProviders

Shandem — Wed, 17 Apr 2013 02:16:06 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: MVCFileRegistration

Shandem — Wed, 17 Apr 2013 00:43:44 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: FileRegistration

Shandem — Wed, 17 Apr 2013 00:38:36 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: CompositeFiles

Shandem — Wed, 17 Apr 2013 00:17:04 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: CompositeUrlTypes

Shandem — Wed, 17 Apr 2013 00:16:49 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: Configuration

Shandem — Wed, 17 Apr 2013 00:16:24 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

Updated Wiki: Configuration

Shandem — Wed, 17 Apr 2013 00:16:13 GMT

Documentation moved to GitHub:

https://github.com/Shandem/ClientDependency/wiki

New Comment on "Documentation"

michielvoo — Wed, 06 Jun 2012 08:21:04 GMT

Why doesn't the cache clear when the source files change?

New Comment on "FileRegistration"

michielvoo — Tue, 05 Jun 2012 16:05:28 GMT

+1 @driftnetnz That should be part of the documentation, preferably at the top of this document.

New Comment on "FileRegistration"

michielvoo — Tue, 05 Jun 2012 16:04:50 GMT

+driftnetnz

Updated Wiki: Home

Shandem — Mon, 04 Jun 2012 22:40:41 GMT

Overview

ClientDependency is a framework for simplifying colaborative development of ASP.NET web components, allowing components each component to state what CSS and JavaScript files they require, and ensuring that each file only is only added once to the response. ClientDependency will not only manage the inter-dependencies of scripts and styles between all your views, controls and pages but has the added benefit of managing all of the file compression, combination & minification for you. It will even detect and process script/styles that aren't registered with the framework and other requests such as json that can be minified/compressed. All of this is fully configurable if you need to modify any of the default behavior.

This project includes support for:

ASP.Net MVC & WebForms
Make your controls/views/pages dependent on client files by:
- Using HtmlHelpers
- Attributing your controls
- Using the JSInclude or CSSInclude web controls
- Dynamically registering them in code
Combining, compressing & minifying JavaScript and CSS files
- Also, compressing & minifying JavaScript and CSS files that are found directly in the markup without being registered with ClientDependency framework (these files are termed 'Rogue' files in this framework)
Adding dependencies on external/CDN files
OutputCaching of the combined/compressed composite files
Persisting the combined/compressed composite files for increased performance when applications restart or when the Cache expires
Versioning the files ... great for ensuring your clients' browser cache is cleared!
Tagging client files with priorities
Tagging client files with path names so you don't have to worry about moving files around in your project, worrying about absolute vs relative paths, or running your application in a virtual folder... great for theming!
Detecting 'Rogue' script and styles in your pages to have them magically compressed and output
Provider Model so you can choose how you would like your JS and CSS files rendered
Provider Model so you can choose how you would like your JS and CSS files combined, compressed & minified

Some simple examples

Registration in markup (MVC):

@Html
  .RequiresCss("ColorScheme.css", "Styles")
  .RequiresJs("/Js/jquery-1.3.2.min.js");

Registration in markup (Web Forms):

<CD:CssInclude ID="CssInclude1" runat="server" FilePath="~/CSS/Content.css" />

Registration via attributes (Web Forms):

[ClientDependency(ClientDependencyType.Css, "~/Css/CustomControl.css")]

Documentation

See Documentation tab

Updated Wiki: MVCFileRegistration

Shandem — Mon, 04 Jun 2012 22:35:38 GMT

Registering files in MVC

Registering scripts or styles in MVC is very easy and straight forward. Everything is based on extension methods on the html helper class.
Register a style sheet (multiple overloads)

<%--Register stylesheet with full path --%>
<% Html.RequiresCss("~/Site.css"); %>

<%--Register stylesheet with path alias --%>
<% Html.RequiresCss("Site.css", "Styles"); %>

<%--Register stylesheet with priority (a lower number ensures it will render higher in the queue) --%>
<% Html.RequiresCss("~/Site.css", 1); %>

<%--Register stylesheet with path alias and priority --%>
<% Html.RequiresCss("Site.css", "Styles", 1); %>

Register a script (multiple overloads)

<%--Register script with full path --%>
<% Html.RequiresJs("~/Js/AnotherTest.js"); %>

<%--Register script with path alias --%>
<% Html.RequiresCss("AnotherTest.js", "Scripts"); %>

<%--Register script with priority (a lower number ensures it will render higher in the queue) --%>
<% Html.RequiresCss("~/Js/AnotherTest.js", 1); %>

<%--Register script with path alias and priority --%>
<% Html.RequiresCss("AnotherTest.js", "Scripts", 1); %>

You can also chain all of these calls together!! Html.RequiresCss(...).RequiresJs(...).RequiresJs(...) etc...

Rendering files in MVC

In order to get the script/style (link) markup in your html, you'll need to render the css/js somewhere. Generally you would do this on your master page and these statements should only be called once for each request (though, nothing prohibits you from rendering the markup in multiple places)

Note that in Razor, you need to wrap both the RenderJsHere and RenderCssHere in @Html.Raw(...) calls because Razor automatically Html encodes the output. Example: @Html.Raw(Html.RenderJsHere())

Render JS block (multiple overloads):

<%--Render the JS block without specifying any path aliases--%>
<%= Html.RenderJsHere() %>

<%--Render the JS block and specifying one path alias --%>
<%= Html.RenderJsHere(new BasicPath("Scripts", "/Js")) %>

<%--Render the JS block and specifying multiple path aliases --%>
<%= Html.RenderJsHere(new List<IClientDependencyPath>() { 
    new BasicPath("Scripts", "/Js"),
    new BasicPath("OtherScripts", "/OtherJs")
}) %>

<%--Render the JS block using a forced renderer and specifying multiple path aliases --%>
<%= Html.RenderJsHere("LazyLoadRenderer", new List<IClientDependencyPath>() { 
    new BasicPath("Scripts", "/Js"),
    new BasicPath("OtherScripts", "/OtherJs")
}) %>

Render Style block (multiple overloads):

<%--Render the CSS block without specifying any path aliases--%>
<%= Html.RenderCssHere()%>

<%--Render the CSS block and specifying one path alias --%>
<%= Html.RenderCssHere(new BasicPath("Css", "/Css"))%>

<%--Render the CSS block and specifying multiple path aliases --%>
<%= Html.RenderCssHere(new List<IClientDependencyPath>() { 
    new BasicPath("Css", "/Css"),
    new BasicPath("OtherCss", "/OtherCss")
}) %>

<%--Render the CSS block using a forced renderer and specifying multiple path aliases --%>
<%= Html.RenderCssHere("LazyLoadRenderer", new List<IClientDependencyPath>() { 
    new BasicPath("Css", "/Css"),
    new BasicPath("OtherCss", "/OtherCss")
}) %>

Updated Wiki: Configuration

Shandem — Mon, 04 Jun 2012 22:21:23 GMT

Configuration

At a minimum, you need to specify the following in your web.config:
The handler

<!-- ** Section for using IIS 6 -->
<httpHandlers>
  <add verb="*" path="DependencyHandler.axd" type="ClientDependency.Core.CompositeFiles.CompositeDependencyHandler, ClientDependency.Core "/>
</httpHandlers>

<!-- ** Section for using IIS 7 -->
<system.webServer>
  <validation validateIntegratedModeConfiguration="false"/>    
  <handlers>
    <remove name="DependencyHandler"/>
    <add name="DependencyHandler" preCondition="integratedMode" verb="*" path="DependencyHandler.axd" type="ClientDependency.Core.CompositeFiles.CompositeDependencyHandler, ClientDependency.Core "/>
  </handlers>
</system.webServer>

The module

<!-- ** Section for using IIS 6 -->
<httpModules>
  <add name="ClientDependencyModule" type="ClientDependency.Core.Module.ClientDependencyModule, ClientDependency.Core"/>
</httpModules>

<!-- ** Section for using IIS 7 -->
<system.webServer>
  <validation validateIntegratedModeConfiguration="false"/>
  <modules runAllManagedModulesForAllRequests="true">      
    <remove name="ClientDependencyModule"/>
    <add name="ClientDependencyModule" type="ClientDependency.Core.Module.ClientDependencyModule, ClientDependency.Core"/>
  </modules>   
</system.webServer>

You don't actually have to specify any ClientDependency configuration as it will just run with pre-defined defaults which should work for most website implementations. However, you can change the defaults by adjusting the configuration as necessary.

This is the configuration section block. This specifies the default providers to use for registering providers as well as the default provider used to combine/compress/minify your JavaScript & CSS files. The core library ships with all providers specified in this configuration block. See below for details about each one.

<!--
Customize the configuration section as required, it is optional,
when it is not specified the defaults will be loaded. YOU DONT NEED
TO SPECIFY ALL OF THIS CONFIG, THE MINIMUM IS JUST THIS:
<clientDependency version="1" />

Each section is optional, so if you're not using Mvc, you don't need
that section and if you're not using Web Forms, you don't need the 
fileRegistration section.
Composite files are used for both types of projects.

** IMPORTANT: If you're web.config setting: compilation debug="true" is set to 'true', then composite files will NOT be enabled no matter what
-->
<clientDependency version="76" fileDependencyExtensions=".js,.css">
  <!-- 
    This section is used for Web Forms only, the enableCompositeFiles="true" is optional and by default is set to true.
    The PlaceHolderProvider is set to default, the javascriptPlaceHolderId, cssPlaceHolderId attributes are optional and default to what is listed below. If using
    this provider, then you must specify both PlaceHolder controls on your page in order to render the JS/CSS.
  -->
  <fileRegistration defaultProvider="PlaceHolderProvider">
    <providers>
      <add name="PageHeaderProvider" type="ClientDependency.Core.FileRegistration.Providers.PageHeaderProvider, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="LazyLoadProvider" type="ClientDependency.Core.FileRegistration.Providers.LazyLoadProvider, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="LoaderControlProvider" type="ClientDependency.Core.FileRegistration.Providers.LoaderControlProvider, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="PlaceHolderProvider" type="ClientDependency.Core.FileRegistration.Providers.PlaceHolderProvider, ClientDependency.Core" enableCompositeFiles="true" javascriptPlaceHolderId="JavaScriptPlaceHolder" cssPlaceHolderId="CssPlaceHolder"/>
    </providers>
  </fileRegistration>
  <!-- This section is used for MVC only -->
  <mvc defaultRenderer="StandardRenderer">
    <renderers>
      <add name="StandardRenderer" type="ClientDependency.Core.FileRegistration.Providers.StandardRenderer, ClientDependency.Core" enableCompositeFiles="true"/>
      <add name="LazyLoadRenderer" type="ClientDependency.Core.FileRegistration.Providers.LazyLoadRenderer, ClientDependency.Core" enableCompositeFiles="true"/>
    </renderers>  
  </mvc>
  <!-- 
The composite file section configures the compression/combination/minification of files.
You can enable/disable minification of either JS/CSS files and you can enable/disable the 
persistence of composite files. By default, minification and persistence is enabled. Persisting files
means that the system is going to save the output of the compressed/combined/minified files
to disk so that on any subsequent request (when output cache expires) that these files don't have
to be recreated again and will be based on the persisted file on disk. This saves on processing time.
-->
  <compositeFiles defaultFileProcessingProvider="CompositeFileProcessor" compositeFileHandlerPath="~/DependencyHandler.axd">
    <!--
    File processing providers perform the file combination, compression and storage.
    Generally there would be no reason to replace.
    NOTE: The pathUrlFormat is much nicer as {dependencyId}.{version}.{type} which is the default,
    however, it is specified below with '/' as the delimiter to demonstrate using it with Cassini
    since Cassini does not support '.' chars in the path.
    --> 
    <fileProcessingProviders>
      <add name="CompositeFileProcessor"
            type="ClientDependency.Core.CompositeFiles.Providers.CompositeFileProcessingProvider, ClientDependency.Core" 
            enableCssMinify="false" 
            enableJsMinify="false" 
            persistFiles="true"     
            compositeFilePath="~/App_Data/ClientDependency" 
            bundleDomains="localhost:54153" 
            urlType="MappedId"
            pathUrlFormat="{dependencyId}/{version}/{type}"/>
    </fileProcessingProviders>
    <!-- 
    A file map provider stores references to dependency files by an id to be used in the handler URL when using the MappedId Url type
    -->
    <fileMapProviders>
      <add name="XmlFileMap" 
            type="ClientDependency.Core.CompositeFiles.Providers.XmlFileMapper, ClientDependency.Core" 
            mapPath="~/App_Data/ClientDependency"/>
    </fileMapProviders>
    <!-- 
  Defines the mime types to compress when requested by the client.
  Path is a regex selector, or a * can be used as in place of 'any'.
  Generally mime types are only set by client browsers in the request for things
  such as JSON or XML ajax requests.
  -->
    <mimeTypeCompression>
      <add type="application/json" path="^.*?/Services/.*"/>
    </mimeTypeCompression>
    <!-- 
  Defines the paths to match on to enable rogue file compression.
  Path is a regex selector, or a * can be used as in place of 'any'.
  jsExt and cssExt are comma seperated list of extensions to match to have the dependencies
  replaced with the composite file handler. You can even include ASP.Net web service JS proxies.
  -->
    <rogueFileCompression>
      <add path="*" compressJs="true" compressCss="true" jsExt=".js,asmx/js" cssExt=".css">
        <!--<exclusions>
          <add path="^.*test.aspx.*"/>
        </exclusions>-->
      </add>
    </rogueFileCompression>
  </compositeFiles>
</clientDependency>

Versioning

As seen in the above configuration, a version can be specified. This accomplishes the following:

Appends a version number as a query string to each JavaScript/CSS file request when in debug mode (see below). This is useful for new web application deployments as it will force all browsers to request an un-cached file. This solves the issue of having to clear your browser cache all of the time (or getting your clients to clear their cache)
When not in debug mode, forces the system to create newly versioned composite files. This refreshes the server output cache. This also solves the problem listed above with browser cache as well.

File registration providers (Web Forms)

The file registration provider controls how your script and css files get rendered into the HTML markup. The Client Dependency core ships with 3 providers: PageHeaderProvider, LoaderControlProvider and LazyLoadProvider. All file registration providers inherit from the BaseFileRegistration provider class.

PlaceHolderProvider

This provider gives you full control over where your JS and CSS references are rendered in your page. In order for this provider to work you must declare 2 Asp.Net PlaceHolder control's in your page with specific Ids assigned. By default, these Ids are: "JavaScriptPlaceHolder" and "CssPlaceHolder" but these can be changed via config if you want to specify different Ids. When the page renders, the JavaScript will be rendered where the JavaScriptPlaceHolder is found and the CSS will be rendered where the CssPlaceHolder is found.
This is most common provider used as it gives you full control over where in the page your dependencies are rendered.

PageHeaderProvider

This provider will render all script and link tags in the pages header tag

LoaderControlProvider

This provider will render all script and link tags in the same location in the page's markup that the ClientDependencyLoader control is found.

LazyLoadProvider

This is a specialized provider dynamically registers/injects JavaScript and CSS files using JavaScript
This is commonly used to improve page performance as the page will display before CSS and JavaScript files are downloaded, however, this generally means you'll need to have some sort of page loader renderred until the files are loaded.

MVC Renderers (MVC)

MVC renders the output for client dependencies using Renderer providers. The renderers included are: Standard Renderer and Lazy Load Renderer. A render simply outputs the script or style (link) markup to support all of the dependencies registered. With MVC, you need to specify in your markup where you would like to render the script or style tags in your html. Unlike webforms, MVC will render out the script/style (link) blocks wherever you put the following markup

<%= Html.RenderCssHere() %>
<%= Html.RenderJsHere() %>

So you need to make sure that you only use the syntax above in one spot throughout your views (such as on your master page).

fileDependencyExtensions

By default this property is set to "js,css" it is not mandatory to specify this property in the configuration.
This property indicates what files to process as file based dependencies as opposed to request based dependencies.
- An example of a request based dependency could be an .ashx page that dynamically generates JavaScript, or a request to an .asmx/js webservice JavaScript proxy.
- It is more overhead to process a request based dependency since the server will actually make the request on the server side to include it in the composite files generated.
- If the system detects a file request that doesn't end in the extensions specified by this property, it treats the request as a request based dependency.

Composite file processing

This library ships with one composite file processing provider which uses a .Net handler to do the processing.
The configuration options are pretty self explanatory

Mime Type Compression

If you would like to add compression to requests based on mime type, you can easily add it here.
This is mostly useful for request such as JSON based requests

Rogue File Compression

Here you can specify how the system detects 'rogue' scripts and styles and how to treat them
Though its better to register scripts and styles with ClientDependency, the system will automatically compress/minify scripts and styles that haven't explicitly been registered, but again, you can change the config.

Updated Wiki: Home

Shandem — Mon, 04 Jun 2012 22:20:34 GMT

Overview

ASP.Net MVC & WebForms
Make your controls/views/pages dependent on client files by:
- Using HtmlHelpers
- Attributing your controls
- Using the JSInclude or CSSInclude web controls
- Dynamically registering them in code
Combining, compressing & minifying JavaScript and CSS files
- Also, compressing & minifying JavaScript and CSS files that are found directly in the markup without being registered with ClientDependency framework (these files are termed 'Rogue' files in this framework)
Adding dependencies on external/CDN files
OutputCaching of the combined/compressed composite files
Persisting the combined/compressed composite files for increased performance when applications restart or when the Cache expires
Versioning the files ... great for ensuring your clients' browser cache is cleared!
Tagging client files with priorities
Tagging client files with path names so you don't have to worry about moving files around in your project, worrying about absolute vs relative paths, or running your application in a virtual folder... great for theming!
Detecting 'Rogue' script and styles in your pages to have them magically compressed and output
Provider Model so you can choose how you would like your JS and CSS files rendered
Provider Model so you can choose how you would like your JS and CSS files combined, compressed & minified

Quick Examples

Registration in markup (MVC):

@Html
  .RequiresCss("ColorScheme.css", "Styles")
  .RequiresJs("/Js/jquery-1.3.2.min.js");

Registration in markup (Web Forms):

<CD:CssInclude ID="CssInclude1" runat="server" FilePath="~/CSS/Content.css" />

Registration via attributes (Web Forms):

[ClientDependency(ClientDependencyType.Css, "~/Css/CustomControl.css")]

Documentation

See Documentation tab

Updated Wiki: Home

Shandem — Mon, 04 Jun 2012 22:19:55 GMT

Overview

ASP.Net MVC Framework
Make your controls/views/pages dependent on client files by:
- Using HtmlHelpers
- Attributing your controls
- Using the JSInclude or CSSInclude web controls
- Dynamically registering them in code
Combining, compressing & minifying JavaScript and CSS files
- Also, compressing & minifying JavaScript and CSS files that are found directly in the markup without being registered with ClientDependency framework (these files are termed 'Rogue' files in this framework)
Adding dependencies on external/CDN files
OutputCaching of the combined/compressed composite files
Persisting the combined/compressed composite files for increased performance when applications restart or when the Cache expires
Versioning the files ... great for ensuring your clients' browser cache is cleared!
Tagging client files with priorities
Tagging client files with path names so you don't have to worry about moving files around in your project, worrying about absolute vs relative paths, or running your application in a virtual folder... great for theming!
Detecting 'Rogue' script and styles in your pages to have them magically compressed and output
Provider Model so you can choose how you would like your JS and CSS files rendered
Provider Model so you can choose how you would like your JS and CSS files combined, compressed & minified

Quick Examples

Registration in markup (MVC):

@Html
  .RequiresCss("ColorScheme.css", "Styles")
  .RequiresJs("/Js/jquery-1.3.2.min.js");

Registration in markup (Web Forms):

<CD:CssInclude ID="CssInclude1" runat="server" FilePath="~/CSS/Content.css" />

Registration via attributes (Web Forms):

[ClientDependency(ClientDependencyType.Css, "~/Css/CustomControl.css")]

Documentation

See Documentation tab

Updated Wiki: Home

Shandem — Mon, 04 Jun 2012 22:19:37 GMT

Overview

ASP.Net MVC Framework
Make your controls/views/pages dependent on client files by:
- Using HtmlHelpers
- Attributing your controls
- Using the JSInclude or CSSInclude web controls
- Dynamically registering them in code
Combining, compressing & minifying JavaScript and CSS files
- Also, compressing & minifying JavaScript and CSS files that are found directly in the markup without being registered with ClientDependency framework (these files are termed 'Rogue' files in this framework)
Adding dependencies on external/CDN files
OutputCaching of the combined/compressed composite files
Persisting the combined/compressed composite files for increased performance when applications restart or when the Cache expires
Versioning the files ... great for ensuring your clients' browser cache is cleared!
Tagging client files with priorities
Tagging client files with path names so you don't have to worry about moving files around in your project, worrying about absolute vs relative paths, or running your application in a virtual folder... great for theming!
Detecting 'Rogue' script and styles in your pages to have them magically compressed and output
Provider Model so you can choose how you would like your JS and CSS files rendered
Provider Model so you can choose how you would like your JS and CSS files combined, compressed & minified

Quick Examples

Registration in markup (MVC):

@Html
     .RequiresCss("ColorScheme.css", "Styles")
     .RequiresJs("/Js/jquery-1.3.2.min.js");

Registration in markup (Web Forms):

<CD:CssInclude ID="CssInclude1" runat="server" FilePath="~/CSS/Content.css" />

Registration via attributes (Web Forms):

[ClientDependency(ClientDependencyType.Css, "~/Css/CustomControl.css")]

Documentation

See Documentation tab

Updated Wiki: Home

Shandem — Mon, 04 Jun 2012 22:19:04 GMT

Overview

ASP.Net MVC Framework
Make your controls/views/pages dependent on client files by:
- Using HtmlHelpers
- Attributing your controls
- Using the JSInclude or CSSInclude web controls
- Dynamically registering them in code
Combining, compressing & minifying JavaScript and CSS files
- Also, compressing & minifying JavaScript and CSS files that are found directly in the markup without being registered with ClientDependency framework (these files are termed 'Rogue' files in this framework)
Adding dependencies on external/CDN files
OutputCaching of the combined/compressed composite files
Persisting the combined/compressed composite files for increased performance when applications restart or when the Cache expires
Versioning the files ... great for ensuring your clients' browser cache is cleared!
Tagging client files with priorities
Tagging client files with path names so you don't have to worry about moving files around in your project, worrying about absolute vs relative paths, or running your application in a virtual folder... great for theming!
Detecting 'Rogue' script and styles in your pages to have them magically compressed and output
Provider Model so you can choose how you would like your JS and CSS files rendered
Provider Model so you can choose how you would like your JS and CSS files combined, compressed & minified

Quick Examples

Registration in markup (MVC):

@Html
         .RequiresCss("ColorScheme.css", "Styles")
         .RequiresJs("/Js/jquery-1.3.2.min.js");

Registration in markup (Web Forms):

<CD:CssInclude ID="CssInclude1" runat="server" FilePath="~/CSS/Content.css" />

Registration via attributes (Web Forms):

[ClientDependency(ClientDependencyType.Css, "~/Css/CustomControl.css")]

Documentation

See Documentation tab