Home

Shannon Deminick edited this page Nov 17, 2016 · 43 revisions

ClientDependency Framework

Table of contents

Overview
Quick Start
    Debugging
    MVC
    Webforms
    Pre-defined bundles
Path aliases 
Configuration 
Prioritizing 
Versioning 
Composite files, debugging, urls & grouping  
Html tag attributes 
Forced providers 
More on MVC - setup & runtime registration 
More on Webforms & runtime registration 
Rogue Files - script/link tag detection 

Overview

The main page has a brief overview of what CDF is, its feature set and links to releases

Quick start

To get started quickly, install CDF via Nuget. If you are using MVC be sure to install the MVC package as well.

PM> Install-Package ClientDependency

PM> Install-Package ClientDependency-Mvc5

or if you are using an old version of MVC:

PM> Install-Package ClientDependency-Mvc

Debugging

When you're creating a website, you don't want CDF to be combining, caching & compressing all of your files because you need to be able to debug your JavaScript and CSS in the browser so it is important to note that setting <compilation debug="true"> will disable all combining, caching, compressing, rogue script detection, etc... !!

When you deploy your website or want to test the composite files created with CDF you need to change this to <compilation debug="false">

MVC

Make your view dependent on any CSS/JavaScript file
@{Html.RequiresCss("~/Css/ColorScheme.css");}
@{Html.RequiresJs("~/Js/jquery.js");}
Make your view dependent on an entire CSS/JavaScript folder
@{Html.RequiresCssFolder("~/Css/Widgets/");}
@{Html.RequiresJsFolder("~/Js/Controls/");}
Support for chaining calls to any CDF HtmlHelper method
@{
Html.RequiresJs("~/Js/jquery.js")
	 .RequiresJs("~/Js/jquery.validation.js")
	 .RequiresJs("~/Js/myCoffeeLib.coffee");
}
Rendering CSS/JavaScript in your page
@Html.RenderJsHere()
@Html.RenderCssHere()
Referencing a bundle in MVC
@{Html.RequiresCssBundle("MyControl");}
@{Html.RequiresJsBundle("JQuery");}

Webforms

In webforms, you'll need to register a control prefix on your webforms page:

<%@ Register TagPrefix="CD" Namespace="ClientDependency.Core.Controls" Assembly="ClientDependency.Core" %>
Make your page/control dependent by using normal html markup

One of th easiest ways to get up and running with CDF with Webforms is to just wrap your normal css/javascript html declarations in the HtmlInclude control:

<CD:HtmlInclude runat="server">
	
	<link type='text/css' href='/css/site.less'/>
	<link type='text/css' href='/css/controls.css'/>

	<script type='text/javascript' src='/js/jquery.js'></script>
	<script type='text/javascript' src='/js/jquery.ui.js'></script>
	<script type='text/javascript' src='/js/myTypeScript.ts'></script>

</CD:HtmlInclude>
Make your page/control dependent on any CSS/JavaScript file
<CD:CssInclude runat="server" FilePath="~/CSS/ColorScheme.css" /> 
<CD:JsInclude runat="server" FilePath="~/Js/jquery.js" />
Make your page/control dependent on an entire CSS/JavaScript folder
<CD:CssFolderInclude runat="server" FolderVirtualPath="~/Css/Widgets/" /> 
<CD:JsFolderInclude runat="server" FolderVirtualPath="~/Js/Controls/" />
Make your composite controls dependent on any CSS/JavaScript file:
[ClientDependency(ClientDependencyType.Css, "~/Css/CustomControl.css")] 
public class MyControl : Control { ... }
[ClientDependency(ClientDependencyType.JavaScript, "~/Js/MyControl.js")] 
public class MyControl : Control { ... }
Rendering CSS/JavaScript in your page

You need to have a loader on your page:

<CD:ClientDependencyLoader runat="server" id="Loader" />

NOTE: The loader control should normally be defined in your markup before any other CDF controls are declared.

Then you'll need to define a place holder for where you want the JavaScript and CSS rendered

<%--This will ensure the CSS is rendered at the location of this placeholder--%>
<asp:PlaceHolder runat="server" ID="CssPlaceHolder"></asp:PlaceHolder>
<%--This will ensure the JS is rendered at the location of this placeholder--%>
<asp:PlaceHolder runat="server" ID="JavaScriptPlaceHolder"></asp:PlaceHolder>

NOTE: the Ids of the controls must be how they are defined above, otherwise you can change the expected ids in the CDF configuration. Also in Webforms there are various providers that allow you to change the behavior of the ClientDependencyLoader but the PlaceHolderProvider is the default and is recommended.

Pre-defined bundles

Creating a pre-defined bundle on application startup. This example creates a bundle in the global.asax:

public class MyApplication : HttpApplication
{
    protected void Application_Start()
    {        
        CreateBundles();
    }

	public static void CreateBundles()
    {
        BundleManager.CreateCssBundle("MyControl", 
            new CssFile("~/Css/Controls/MyControl/css1.css"),
            new CssFile("~/Css/Controls/MyControl/css2.css"),
            new CssFile("~/Css/Controls/MyControl/css3.css"));

		BundleManager.CreateJsBundle("JQuery", 
            new JavascriptFile("~/Js/jquery.js"),
            new JavascriptFile("~/Js/jquery.validation.js"));
    }
}