Creating Asset Packages

Creating Asset Packages

Asset packages are the the core of Ignite. They contain assets that are served to the client.

Package Container

Because Ignite is tightly integrated with MVC3, the package container needs to hooking into the routes of your application. This is commonly done in the Global.asax.cs file of your solution:

public static void RegisterRoutes(RouteCollection routes)
{
    PackageContainer.Create()
        .Map(routes);

    // Other route configuration would go here.
}

The package container's route mappings should go before other route configuration (especially if you have a "catch-all" route).

Adding Packages

There are two types of supported packages: JavaScript and StyleSheet packages.

Packages are created by using the JavaScript() or StyleSheet() methods on the package container. Here are their method signatures:

IPackageContainer JavaScript(string name, string[] include, string[] exclude = null);
IPackageContainer StyleSheet(string name, string[] include, string[] exclude = null);

The first parameter is the name of the package. The name along with the type of package uniquely identifies the package. It is possible to use the same name for both a JavaScript and a StyleSheet package.

The next two parameters are the paths to the assets to include/exclude with this package. Here is an example of using just the include parameter:

PackageContainer.Create()
    .JavaScript("core", new[]
    {
        "scripts/jquery-1.7.0.js",
        "scripts/underscore-1.3.1.js",
        "scripts/backbone-0.9.1.js"
    })
    .Map(routes);

Because some files are required to be loaded by the browser before another file, it is usually a good idea to write out the full path of the asset. However, wildcard and recursive searches are also possible:

.JavaScript("core", new[]
{
    "scripts/jquery-*.js",
    "scripts/underscore-*.js",
    "scripts/backbone-*.js",
    "scripts/app/**/*.js"
});

The last line would recursively search scripts/app for files that end with .js.

Finally, sometimes it's nice to be able to exclude files that were perhaps resolved by recursive search. In this example, everything from the admin folder would be excluded from the core JavaScript pacakge.

.JavaScript("core", 
    include: new[] { "scripts/app/**/*.js" }, 
    exclude: new[] { "scripts/app/admin/*.js" });

The difference between JavaScript and StyleSheet packages is that JavaScript packages support loading JavaScript templates. To read more about this, check out the JavaScript Templates page.

Rendering Package Tags

Rendering the tags for a package is done by calling either the JavaScriptTag() or StyleSheetTag() methods on the PackageContainer class. The first parameter is the name of the package that was given in the previous section. Both methods expose an optional htmlAttributes parameter that can be used to add additional HTML attributes to the rendered tag.

@Ignite.PackageContainer.JavaScriptTag("core")
@Ignite.PackageContainer.StyleSheetTag("core")
@Ignite.PackageContainer.StyleSheetTag("print", new { media = "prnt" })

When your application is in debug mode, individual assets are rendered in <script> and <link> tags to allow you to easily debug any issues.

<script type="text/javascript" src="/assets/core.js?debug=scripts/jquery-1.7.0.js"></script>
<script type="text/javascript" src="/assets/core.js?debug=scripts/underscore-1.3.1"></script>
<script type="text/javascript" src="/assets/core.js?debug=scripts/backbone-0.9.1.js"></script>
<link rel="stylesheet" type="text/css" href="/assets/core.css?debug=style/reset.less" />
<link rel="stylesheet" type="text/css" href="/assets/core.css?debug=style/lib.less" />
<link rel="stylesheet" type="text/css" href="/assets/core.css?debug=style/layout.less" />
<link rel="stylesheet" type="text/css" href="/assets/print.css?debug=style/print.less" media="print" />

However, when you're not debugging, assets are combined into a single tag with a version parameter attached. This dramatically decreases the requests made to the server to improve application performance:

<script type="text/javascript" src="/assets/core.js?v=f8h5j21k7"></script>
<link rel="stylesheet" type="text/css" href="/assets/core.css?v=f8h5j21k7" />
<link rel="stylesheet" type="text/css" href="/assets/print.css?v=f8h5j21k7" media="print" />

Route Prefix

The one thing you'll notice is that the URLs that are generated have an assets prefix. This can be customized:

PackageContainer.Create()
    .RoutePrefix("static")
    .JavaScript("core", new[] { "path/to/script.js" })
    .Map(routes);

Which would cause the <script> tag to be rendered as:

<script type="text/javascript" src="/static/core.js?debug=path/to/script.js"></script>