Fluent Configuration Documentation - skroonenburg/Rejuicer GitHub Wiki

#Fluent Configuration Documentation You can configure Rejuicer using a simple fluent interface.

##Where to place the code For best results, configure Rejuicer minifications in global.asax.cs on ApplicationStart. This will ensure that all minifications are configured before any requests are accepted by the web server. (Note: If you install Rejuicer via Nuget then a file will be added to your project inside App_Start. The code in this class uses WebActivator and will run on application start to configure your minification rules)

For example:

protected void Application_Start()
{
    OnRequest.ForJs("~/Combined.js")
             .Compact
             .FilesIn("~/Scripts/")
                 .Matching("*.js")
             .Cache
             .Configure();

    OnRequest.ForCss("~/Combined.css")
             .Compact
             .FilesIn("~/Styles/")
                 .Matching("*.css")
             .Cache
             .Configure();
    ...
}

##Minified Files Using Rejuicer's fluent interface, you define request URLs that will delivered combined/minified files to the client's browser.

For example:

OnRequest.ForCss("~/Combined.css")
         .Compact
         .FilesIn("~/Styles/")
         .Matching("*.css")

When a browser requests "Combined.css", Rejuicer will find all files in the "Styles" folder, combine them, minify them and return them in the response. If caching is enabled, the response will be cached, so that minification is only performed on the first request.

##Content Type

• ForCss - configure a minification rule for CSS files.
• ForJs - configure a minification rule for JavaScript files.

##Compact/Combine

• Compact - tells Rejuicer to compact/minify the content in all matching files. Yahoo's YUI compressor is used to perform the minification.
• Combine - tells Rejuicer to combine the contents of all matching files, but not minify them.

##Select Files You can configure Rejuicer to include as many files are you would like in the minification. The fluent interface allows you to chain file includes, adding single files, or a set of files matching a wildcard rule.

###Single File You can add a single file to the minification, like so:

OnRequest.ForCss("~/Combined.css")
       .Compact
       .File("~/Style.css")

###Wildcard Matching You can add all files in a folder matching a wildcard rule, like so:

OnRequest.ForJs("~/Combined.js")
       .Compact
       .FilesIn("~/Scripts/")
         .Matching("*.js")

This will include all files with the .js extension in the Scripts folder under the application root.

###Chain Multiple Includes You can chain multiple file includes together, like so:

OnRequest.ForJs("~/Combined.js")
       .Compact
       .File("~/Style.css")
       .FilesIn("~/Scripts/")
         .Matching("*.js")
       .FilesIn("~/Scripts/jquery/")
         .Matching("jquery*.js")

##Server Side Caching By default, Rejuicer will perform combination/minification once when the configuration is performed (this is best done on application start). After that, all requests for this URL will be served with the cached value. The cached value will be stored with a cache dependency for each of the original source files, meaning that if one of the included source files is modified, the cache will be invalidated, and the minification will be performed again on the next request.

When running in IIS integrated mode, all rejuiced content will be returned to the browser with a last modified date. This date will be transmitted to the server on subsequent requests. If the rejuiced content has not changed since it was first generated, the server will return 304 Not Modified, and not transmit the entire content of the file.

##Client Side (Browser) Caching

For best performance, it's a great idea to use browser caching. Rejuicer can tell the requesting browser that a file at a particular URL is valid for a long period of time (years) so that it will not be requested again.

But, how do you tell the browser to get the minified content again, in the event that it changes?

With Rejuicer, you can include a placeholder in your minified file name. If you use Rejuicer to render your <script> & <link> tags, then it will replace the placeholder with a timestamp. This is a unique timestamp representing the current version of the minified content. It will remain constant until the minified content changes. When it changes, Rejuicer will render your <script> & <link> tags with a URL containing a new timestamp. From the browser's perspective, this is a different URL and it will therefore request this new URL, since it is not cached.

If you include a placeholder for a timestamp in the minified file name, then Rejuicer will can render your <script> and <link> tags with a unique code in the filename.

Example

In your ASP.NET view:

<head>
    <%= Rejuiced.JsFor("~/Combined-{0}.js") %>
</head>

In your Rejuicer configuration on Application_Start:

Use a {0} placeholder in the filename, to represent the place where the unique code should be inserted:

OnRequest.ForJs("~/Combined-{0}.js")
         .Compact
         .FilesIn("~/Scripts/")
           .Matching("*.js")
         .Configure();

or, alternatively you can pass a delegate to insert the unique code:

OnRequest.ForJs(code => "~/Combined-" + code + ".js")
         .Compact
         .FilesIn("~/Scripts/")
           .Matching("*.js")
         .Configure();

Rejuicer will automatically read all CSS source files and scan them for ASP.NET virtual path URLs (ie. in the form ~/Folder/File.ext). Rejuicer will resolve these virtual paths into real URLs and return them inside your CSS. This prevents you from having to use relative paths inside your CSS that may break when you combine your CSS files into one combined file, which may appear to the browser to reside in a different folder on the server.

So, instead of using: background-image: url(../../images/myimage.png)

You can now use: background-image: url(~/images/myimage.png)

and Rejuicer automatically will transform this virtual path into a real URL, inside your CSS.

Rejuicer powerfully combines the browser caching with CSS transformations, allowing you to automatically browser-cache images that are referenced in your CSS files. If you include an image in your CSS using a virtual path and {0} placeholder (see browser caching above), then Rejuicer will automatically configure this file for minification (you need not have created a minification rule previously for this image file), and include replace the URL in your CSS with a URL including the current timestamp for this file.

From this point on, the browser will no longer request the server for this image, because it is cached client side. However, if the image is modified on the server then Rejuicer will automatically invalidate the CSS file referencing it. This means that next time the site is loaded, the CSS will be downloaded, and it will reference the image with an updated timestamp in the URL, causing the newly updated image to be downloaded & cached in the browser.

Therefore, your images will always be up to date in the users browser, but with all of the benefits of browser caching (no request to the server will be made to download images that have not been modified since being cached).