The CSS Manager

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

CssManager is responsible of:
  • CSS source file dependency management.
  • Server and client-side framework depencency management.
  • Local CSS file compression (using AjaxMin by default).
  • Provide infrastructure to client-server Web controls.

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:
  • Actual CSS source files of these kinds:
    • File. It's a physical CSS file located in some place of file system.
    • Embedded resource. It's a CSS file that's embedded to some assembly.
    • External URL. It's a file located in some external server.
  • CSS code that's declared "as is" in your server code and it's executed in the client-side.

Includes and References.

CssManager has two different concepts that work together in order to define a CSS dependency:
  • Include. An include is pointer to a CSS file. Either physical, embedded or from an external URL. This isn't adding a CSS file to a Web page, but it's just telling CssManager that some file is available to be included in some Web page. An include has two arguments:
    • id: An arbitrary identifier. For example: "MyCSSFile".
    • source: The file path, full qualified file path for an embedded resource or an URL.
    • kind: File, Resource or ExternalUrl, depending on how you gave the source.
  • Reference. A reference is identified by an include id. It tells CssManager that the referenced include must be added to the page.

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:
  • id: MyFile.
  • source: /Scripts/MyFile.css.
  • kind: File.

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.
  • Page-level. Any page that hosts Calipso-based controls must inherit Comkarl.Web.UI.Page. Then, you can get current CssManager instance thanks to Page.CssManager property. Add your include this way (IMPORTANT THIS MUST BE DURING PAGE.LOAD EVENT!!!!):
    • CssManager.RegisterInclude(id: "MyFile", source: "/Scripts/MyFile.css", kind: CSSIncludeKind.File);
  • Control-level. Any Calipso control inherits Comkarl.Web.UI.Controls.ScriptControl. The code to do the run-time include is exactly the same as the example in page-level (previous point). Read how to create your very first control following this link.

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:
  • Page-level. Page-level approach supports doing so in code or in the ,aspx/.master.
    • In code requires that you register the references in the Page.Load event:
      • CssManager.RegisterReference("MyFile"); .
    • In your .aspx or .master. Your top-most master page must have added a CssManager to the <head />_ (X)HTML section. But nested master pages or content pages may require a CssManager if the concrete page adds ScriptControl-derived classes, or if you want to add references. For example, your CssManager control would look like this:
<Calipso:CssManager CombinedFileName="Some.css" runat="server">
   <References>
         <Calipso:CSSRef RefId="MyFile" />
    </References>
</Calipso:CssManager>
  • (Please refer to Step 9 in this wiki page in order to learn how to register CssManager in your Master Page or Content Page).
  • Control-level. This can only be made in code the same way as it's done in the page-level above.

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:
  • id: Same as any other include, for example "MyFile".
  • source: The full resource path. For example: "YourProject.NamespaceA.NamespaceB.MyFile.css, AssemblyName".
  • kind: Resource. This is very important, because CssManager must know what kind of source has your include.

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:
  • id: Same as any other include, for example "MyFile".
  • source: The URL of your file. For example http://somedomain.com/scripts/MyFile.css.
  • kind: ExternalUrl. This is very important, because CssManager must know what kind of source has your include.

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...
  • ...debug mode (<compilation debug="true"...)...
    • CSS includes/references to local file system aren't cached, because those already exist!
    • CSS includes/references to embedded files are cached for each request. Pay attention to this feature, because it's important to point that a Calipso-based solution in debug mode shouldn't be used in a production environment, because more than a request may write the same file. This behavior is very important because this way your ASP.NET application will be executing the up-to-date version of your embedded CSS file!.
    • CSS includes/references to external URLs aren't cached, because as they're external, you shouldn't need to cache them (the responsible of delivering fast CSS files is the server where these are stored!).
  • ...release mode (<compilation debug="false"...),,,
    • CSS includes/references to local file system and embedded files are combined and compressed.

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 */ 

Last edited Oct 18, 2012 at 9:59 AM by MFidemraizer, version 12

Comments

No comments yet.