Generating CSS sprites with T4 tempales

.t4SpriteVar { background-image: url("SpriteVar.png")}
.t4accept {background-position:0px -418px;width: 48px;height: 48px;}
.t4accept.disabled {background-position:-48px -418px;width: 48px;height: 48px;} 

I also must mention that the basic code/algorithm that creates the sprite and the CSS is not my work. You can find the original one on Code Project: Image Sprites and CSS Classes Creator. I took the source code of V2.0, and modified it to match the logic of T4, as the original one is a console application. If you think, you can give an at least ‘Excellent’ vote for the Swiss AlexCode for his work. The best thing in his code is that it is simple, fast and short. That is why I chose it, as in a T4 file it is a little hard to write and debug long and complicated code. 

Another property of T4 files is that they cannot be parameterized from outside. We have the File Properties window, provided by VS, but we cannot get too far with that. Therefore, we must set the parameters within a file, and that is why I separated the codebase from the parameterizing T4 files. Let’s look into one of the parameterizing .tt files to see what each setting does. The settings, following AlexCode’s pattern, must be put as properties into the SCEngineOptions class:  

.SourceDirectory = T4Folder+"\\Images16"; 

This property defines the folder, where the source images are. The 'T4Folder' is the folder of the .tt file, which allows us to set relative paths for the folder of the source images.

.CssClassPrefix = "t4";  

It is recommended to add a prefix to the names of the CSS classes that define the positions of the images within the sprite, in order to prevent name collides with normal, manually created css classes (e.g. .t4label instead of .label). 

.BinPackingLevel = 1; 

The code number of the image positioning algorithm. The goal is to make the smallest possible sprite filesize. There were three algorithms in AlexCode’s code, and I took them as they were:

1 - Basic rectangle (fastest)

2 - Cygon packager (average size)

3 - ArevaloRectanglePacker (maybe minimal size). 

One might think, that the “best” is the best, but it is not. That is why you have this setting, so can choose. The best algorithm for a situation depends on the size of the pictures, the variation of the sizes and the number of pictures.  The bad thing is that the only way to find the smallest sprite for each picture-pack is to run the algorithms for ourself. Except if we have pictures of the same size. In this case, the 1. basic algorithm is the best for sure. 

.FilesName = Path.GetFileNameWithoutExtension(T4FileName);

The name of the generated .png sprite, CSS, HTML, .cs file, C# static class and CSS base class. As you can see, in this case comes from .tt file name. However, you can overwrite with any static name. 

.ImageVariants.Add(new ImageVariant() {
            GreyScale = true,            //is gray scaled image?
            Width = 0,                   //Resized image width, 0 means image won't resize
            Height = 0,
            CssClassName= "disabled",    //additional CSS class for this variant
            DisplayName = "Disabled"     //Column title in demo/test html 
});  

To go even further, I made an extension that allows us to make image variants from the source images with image-transformations. This solves the common problem, when a toolbox icon has multiple visual states: clickable (colorful), disabled (grey) and pressed (highlighted). Sometimes, we want to use an image in multiple sizes, like 48x48, 32x32 or 16x16. Because of the definition I shown above, every icon will have a greyscale version. You can also assign custom CSS classes for each variants. The great advantage of this is that the visual state, enabled or disabled, can be easily defined by the presence or absence of a CSS class. 

Enabled (left icon):  <span class="image24 t4icon t4SpriteVar t4clock"></span> 

Disabled (right icon): <span class="image24 t4icon t4SpriteVar t4clock disabled"></span> 

You can cram multiple CSS classes in the CssClassName, if you want more than one transformation. This is how I made the normal 128x128 / disabled 128x128 / normal 24x24 / disabled 24x24 icons on the bottom-right four 'clock': 

.ImageVariants.Add(new ImageVariant() {
            GreyScale = true,
            Width = 24,
            Height = 24,
            CssClassName= "image24 disabled",
            DisplayName = "24x24 dis."
            });  

This will make them gray, resize them to 24x24 and create two classes to distinguish from the original 128x128 and from the normal 24x24 image.   

You can put multiple variant definitions into the ImageVariants collection. For more examples, see the settings in "SpriteVar.tt", where multiple sizes and grey versions are defined to be created.

The rest of the parameterizing T4 files contain the parts that generate the CSS, the .cs and the overview HTML file.   

We put the T4SpriteMaker.ttinlude file, wherever we want. Then we have to make sure that we set the linking in the parameterizing T4 files to reach the .ttinclude file in a relative path.

<#@ include file="..\path\T4SpriteMaker.ttinclude"#>

<o:p>

If it is in the same folder as the .tt files, then we don’t have to do anything. The include statements will be fine with the default value. 

After that, we create the folder for the images and put there anything we need. We give a meaningful name for the .tt files, because that will be the default name for the generated files (e.g. Sprite32.tt, because of the value of the .FilesName, that we use in this demo). 

After parameterizing and saving the .tt files, the other files will be generated.  

namespace MvcApp.Content.Images 
{
	public static class Sprite32
	{
		public const string t4accept = "t4accept";
		public const string t4add = "t4add";
		public const string t4block = "t4block";
		public const string t4chart_pie = "t4chart_pie";
		public const string t4users = "t4users";
		//…
	}
}    

In the .css, you will find the position codes (compressed a litle): 

.t4Sprite32{background-image: url("Sprite32.png")}
.t4accept{background-position:0px -162px;width:32px;height:32px;}
.t4accept.disabled{background-position:-32px -162px;width:32px;height:32px;}
.t4add{background-position:-64px -162px;width:32px;height:32px;}
.t4add.disabled{background-position:-96px -162px;width:32px;height:32px;} 

The .html file will contain the overview page and an example of usage in the markup. The header of the table will contain the value of the .DisplayName parameter. For example, in the picture on the right, the .DisplayName = "Disabled" setting resulted the header “Disabled” for the column of the greyscale icons. <o:p>  

(You will also find a few extra .tt files in the demo application that can be used for testing purposes. These are made for situations like bad image file, empty image folder or the lack of image folder (SpriteInvalidImages, SpriteEmptyDir, SpriteWrongPath)).  

The demo application also contains a possible usage in the ASP.NET MVC 4 framework with custom Html and Ajax link helpers. Some method calling variations: 

@Html.SPActionLink(SpriteVar.t4block, "Block button", "Index")
@Html.SPActionLink(SpriteVar.t4block, "Block button", "Index", ButtonMode.Disabled)
@Html.SPActionLink(SpriteVar.t4block, "Block button", "Index", "Home")
@Html.SPActionLink(SpriteVar.t4block, "Block button", "Index", "Home", ButtonMode.Disabled)
@Html.SPActionLink(SpriteVar.t4block, "Block button", "Index", "Home", null, null)
@Html.SPActionLink(SpriteVar.t4block, "Block button", "Index", "Home", null, null, 
                   ButtonMode.Disabled)

@Html.SPActionLink(SpriteVar.t4help, "Help button", "Index", "Home", null, null, 
                   ButtonMode.Default | ButtonMode.IconOnly)
@Html.SPActionLink(SpriteVar.t4help, "Help button", "Index", "Home", null, null, 
                   ButtonMode.Disabled | ButtonMode.IconOnly)  

 Points of Interest