Skinning Krang

Krang's appearance can be modified by creating a skin. The simplest skins just change Krang's color palette, but more advanced skins can totally revise Krang's user interface. This document will teach you how to build a Krang skin.

A Simple Skin

The simplest possible skin consists of a single file, called skin.conf placed in a directory underneath the skins/ directory. For example, to create a skin called 'Red' a directory called skins/Red must be created:

  mkdir skins/Red

The skins/Red/skin.conf file will contain the basic configuration information for the skin. For example, here's one that changes Krang's colors to shades of red:

    # based on the Default skin
    Base Default
    Include ../Default/skin.conf

    <CSS>
        # change palette to reds
        DarkColor       #660002
        LightColor      #eba4a5
        BrightColor     #ff0004

        # text colors
        TextColor       #414041
        LightTextColor  #e6e2e6
        LinkColor       #52797b
        ButtonColor     #414041
    </CSS>

    <Images>
        BioChromeBlack  #ffffff
        BioChromeRed    #eba4a5
        BioChromeGreen  #ff0004
        BioChromeBlue   #660002
        <File logo.gif>
            # logo colors
            BioChromeRed    #660002
            BioChromeGreen  #eba4a5
            BioChromeBlue   #ff0004
        </File>
        <File arrow.gif></File>
        <File arrow-asc.gif></File>
        <File arrow-desc.gif></File>
        <File left-bg.gif></File>
    </Images>

Let's look at some of the directives and blocks we're using:

• Base
  
This directive tells Krang that you you want to use the CSS files and image files from another skin as your base. This is really useful if you want to just tweak the style of an existing skin or just change a few of the images.

In this case we're using 'Default' as our base and we share it's images and CSS template files.

• Include
  
This directive brings in another config file (in this case Default/skin.conf) and uses it as if it appeared exactly in our configuration file.

This is useful if you wish to base your skin off of another skin's configuration or what to have your skin configuration in multiple files.

• CSS
  
This block can contain an arbitrary list of colors that will be used as parameters to the CSS templates (files that would match templates/*.css.tmpl).
• Images
  
This block refers to images that will be run through Image::BioChrome. This will allow you to use the same images as your base skin, but filtering them for different colors. You will probably need to experiment a lot with the values you use for BioChromeBlack, BioChromeRed, BioChromeGreen and BioChromeBlue.

To use this skin, first change the configured skin in your conf/krang.conf file:

  Skin Red

To activate the skin, restart Krang:

  bin/krang_ctl restart

Now when you login to Krang with your browser you'll see a red interface.

Replacing Images

If you look at your newly red Krang you'll see that not only are the HTML elements red, but the images are too. For example, the arrow on the left nav is now colored with the dark red chosen for dark_color above. Thus you can change Krang's colors and the images will be colored to match.

In some cases this may not be what you want. For example, you might want to change the logo displayed in the top-left corner to advertise your company instead of Krang. To do so, simply create a directory called images/ inside the skin directory and add your replacement images there. For example, if I wanted to create a special Red Krang logo, I would create a file called:

  skins/Red/images/logo.gif

The names of the image files must match files in templates/images. These are the source images used if the skin does not define replacements.

Replacing CSS files

To replace the default CSS files, simply place a templated CSS file in the css/ directory (of the skin you're creating) with the same name as the css file you're replacing.

Replacing Templates

Changing colors and images is fine, but in the end Krang will still look pretty much like Krang. By replacing templates you can accomplish much more radical alterations. To do so, create a templates/ directory inside your skin. Then copy HTML templates from templates/ into this directory and make alterations.

For example, to create a new navigation layout for the Red theme, I would create this directory:

  skins/Red/templates/

Then copy in nav.tmpl:

  cp templates/nav.tmpl skins/Red/templates

Now changes can be made to nav.tmpl that will only be visible when the Red skin is active.

WARNING: replacing templates in your skin carries with it a significant drawback. Your skin may need updating when you upgrade Krang since new template variables may have been added to Krang's code.

Skins Make Great Add-Ons

When you're done with your spiffy new skin, consider packaging it as an add-on for others to use. You can find more information on building a Krang add-on here: Building a Krang Add-On.