The CSS Manager

Calipso implements a set of CSS-related features that are managed by Comkarl.Web.UI.CssManager class.

CssManager is responsible of:
After all, CssManager is a server control. In order to use it in any Master Page or Page, you'll need to register it on top of the .master or .aspx file:
<%@ Register Assembly="Comkarl.Web" Namespace="Comkarl.Web.UI" TagPrefix="Calipso" %>

1. Understanding CssManager and its concepts

CssManager can manage two types of script files:

Includes and References.

CssManager has two different concepts that work together in order to define a CSS dependency:
Why includes and references? Calipso avoids spreading literal CSS file references across your pages, meaning that if you need to update a CSS file, you do in a single point and it affects the entire project.

Imagine that you've a CSS file called "\Scripts\MyFile.css". An include to this file would be:
Note that physical CSS files must be in your ASP.NET application root or in any subfolder.

And this CSS include would be referenced as "MyFile" in your pages. Question is: how to add includes and references?

How to add includes

Includes can be added by configuration or during run-time.

Any Calipso-enabled project must have a Calipso.config file.

In order to add it by configuration, go to the whole configuration file and add an include as child of <includes> elements inside <CssManager> element.


A file kind include looks like this
<add id="MyFile" source="/Scripts/MyFile.css" kind="File" />


A resource kind include looks like this
<add id="MyFile" source="SomePath.Other.Blah.css, AssemblyName" kind="Resource" />


An external resource kind include looks like this
<add id="MyFile" source="http://mypage.com/myfile.css" kind="ExternalUrl" />


To add it during run-time, you can do in various levels.

How to add references

Once you've some includes configured, for example an include having "MyFile" as identifier, if you want your script file in some concrete page, there're two ways of telling CssManager to do so:
<Calipso:CssManager CombinedFileName="Some.css" runat="server">
   <References>
         <Calipso:CSSRef RefId="MyFile" />
    </References>
</Calipso:CssManager>

Includes of embedded CSS files and external files

In addition to include CSS files that points to a local file system location, CssManager supports embedded files and external URLs to files.

Embedded CSSFiles

In order to make an include to an embedded CSS, either adding the include in code or in your CssManager configuration file, you must give include arguments like this:

External URLs

Sometimes you may need to add external CSS files, for example ones from CDN or external APIs. For example, http://somedomain.com/scripts/MyFile.css.

In this case you would be giving this arguments in code or in your CssManager.config:

2. CssManager file caching, combination and minification

Every reference that's included in an actual page, even if this happened in code or in the CssManager server control, gets cached as a temporal file in the specified folder by the cachePath in the Calipso.config file located in your application root, as an attribute of <CssManager> element (f.e. <CssManager cachePath="~\css">...).

CssManager works in two modes: debug and release. This is defined in the standard Web.config:
  <system.web>
    <compilation debug="true" targetFramework="4.0" />
  </system.web>


When CSS manager is in...
CssManager doesn't combine ALL CSS code in a single file. It combines all referenced files by a CssManager instance.

For example, if your Master Page has its CssManager, it'll combine and compress all referenced CSS files for this concrete instance. Later, some Content Page may have it's own CssManager, so this will combine and compress its own references, and so on.

REMEMBER that no CssManager will work properly if you didn't give the combined file name:
<Calipso:CssManager ID="blah" CombinedFileName="Master.css" runat="server" />

Other important point is that application pool's identity must have read-write access to the temporal directory where Calipso places cached CSS files!.

When CSS files get cached?

CSS file caching occurs in run-time. First time an user request a page, CssManager will generate the necessary file cache, and after that, subsequent requests will be using the already created one.

3. Standalone references: non-combined CSS sources.

Sometimes a project may require that a particular CSS file don't get combined with the rest of ones because it should be cached alone at the browser-level (or other reasons).

Calipso introduces standalone references. In other words, a standalone reference will render a script tag in the browser and the CSS file behind the scenes will not be combined with others.

Standalone references configured in design time

That is configuring a standalone reference in the server CSS control in some master page or content page:
<Calipso:CssManager CombinedFileName="Some.css" runat="server">
   <References>
         <Calipso:CssRef RefId="MyFile" Standalone="true" /> /* NOTE THE SECOND ATTRIBUTE!! */
    </References>
</Calipso:CssManager>

Standalone references configuring during run-time

That is configuring a standalone reference in server code:

CssManager.RegisterReference("MyFile", true); /* SECOND PARAMETER IS "STANDALONE" TRUE OR FALSE */