Get started using Smart Include

Jump to: Install via NuGet | Install manually | Configuration | Usage

Install Smart Include

The easiest way to install Smart Include is by using NuGet, but if you rather want to add it to your project manually instructions for that will follow below the NuGet instructions.

Install using NuGet

If you're new to NuGet you might want to start by learning a bit more about how to install NuGet packages.

Install by opening the Package Manager Console within Visual Studio (you'll find it under Tools / NuGet Package Manager) and run the following command:

PM> Install-Package SmartInclude

You will get a new reference in your project to the Kaliko.SmartInclude.dll, a new folder called Includes with the Get.aspx file inside as well as a few added lines in your web.config. To learn more about this, jump down to the section on how to configure Smart Include.

Install manually

Download the latest version from the download page.
Add a reference in your project to Kaliko.SmartInclude.dll, and add the folder Includes (the Get.aspx file included) into your project.
Open the web.config from the downloaded archive and copy the AppSettings into your project's web.config as well as <add tagPrefix="smart" namespace="Kaliko.SmartInclude" assembly="Kaliko.SmartInclude"/>

Configuration

The configuration is done in the web.config's appSettings section. The added tag prefix will make smart:IncludeCss and smart.IncludeScript available on any page without local registration.

<?xml version="1.0"?>
<configuration>
  <appSettings>
    <!-- Set SmartIncludeDebugMode to true if you don't want the files combined and compressed when debugging -->
    <add key="SmartIncludeDebugMode" value="false"/>
    <!-- If SmartIncludeXhtmlMode is set to true, tags are always ended (i.e. <tag /> -->
    <add key="SmartIncludeXhtmlMode" value="false"/>
    <!-- SmartIncludePath is where the combined files will be stored. Get.aspx must exist in the same path. -->
    <add key="SmartIncludePath" value="/includes/"/>
  </appSettings>
  <system.web>
    <pages>
      <controls>
        <add tagPrefix="smart" namespace="Kaliko.SmartInclude" assembly="Kaliko.SmartInclude"/>
      </controls>
    </pages>
  </system.web>
</configuration>

Application settings

Setting	Description
SmartIncludeDebugMode	Set this to `true` in order to turn off compression and bundling. Great for debugging scripts in a readable manner. Will load the scipt and stylesheet files as if they where included using separate `<script />` and `<link />`. Should be set to false unless you actually are debugging the code as this will override any speed ups!
SmartIncludeXhtmlMode	Set to `true` if you are using XHTML and all rendered single elements will be correctly closed.
SmartIncludePath	This is the path to the Get.aspx that serves the compressed files as well as the path where these files will be stored. Make sure that the server process is able to write to this folder. Default path is `Includes` but can be anything you want, just make sure that you move Get.aspx to whatever path you wish to use.

Usage

Once installed, usage is really simple. Let's look at a sample ASPX page. We have a couple of CSS-files, one JavaScript in the head and a couple more at the bottom.

<!DOCTYPE html>
<html>
<head>
  <title>Sample ASPX page</title>
  <link href="/css/bootstrap.css" rel="stylesheet" />
  <link href="/css/mycustomstyles.css" rel="stylesheet" />
  <link href="/css/font-awesome.css" rel="stylesheet">
  <script src="/js/modernizr.js"></script>
</head>
<body>
  <p>Some content</p>
  <script src="/js/jquery.js"></script>
  <script src="/js/mycustomscripts.js"></script>
</body>

The change to the CSS is pretty straight on, we'll just switch it to smart:IncludeCSS. For the JavaScript we need to use the Group attribute in order to create two different bundles, one for the head and one for the footer.

<!DOCTYPE html>
<html>
<head>
  <title>Sample ASPX page</title>
  <smart:IncludeCss Url="/css/bootstrap.css" runat="server" />
  <smart:IncludeCss Url="/css/mycustomstyles.css" runat="server" />
  <smart:IncludeCss Url="/css/font-awesome.css" runat="server" />
  <smart:IncludeScript Url="/js/modernizr.js" Group="Head" runat="server" />
</head>
<body>
  <p>Some content</p>
  <smart:IncludeScript Url="/js/jquery.js" Group="Foot" runat="server" />
  <smart:IncludeScript Url="/js/mycustomscripts.js" Group="Foot" runat="server" />
</body>

The sample above will compress and merge the files into three different bundles; one CSS bundle and two JavaScript bundles (one with modernizr.js and one with jquery.js and mycustomscripts.js. All will be minified and compressed with GZip.

You can continue to develop in these file keeping them human readable and when you access them on you page they will be rebundled (if changed).

The reference to the bundles are rendered at the first appearance of the instance of the same type (CSS or JavaScript) and group (if used). That means that the Head group above will be rendered at line 8 and the Foot group at line 12.

If you're using different targets for your stylesheets (for instance different for screen, print etc) you can use Group together with the Media attribute (set to same values as the original link element have).