UMBRACO I/S

Umbraco Skins
Creating a skin for Umbraco

Umbraco
12/23/2010

This document walks through the different components of a skin for Umbraco. It is based on the Umbraco
Simple Starter Kit which serves as a simple base for applying your own skins. Important note: The
descriptions and screen shots in this document are preliminary, based on a beta version, and are subject to
change prior to final release.
Contents
About Skins ........................................................................................................................................................ 4
How do Skins Work in Umbraco? .............................................................................................................. 4
What Can a Skin Change? .......................................................................................................................... 4
How Do You Customize a Skin? ................................................................................................................. 5
Changing Skins ........................................................................................................................................... 6
Advanced Skins .............................................................................................................................................. 7
The Structure of a Skin .................................................................................................................................. 9
What Does a Skin Package Contain? ......................................................................................................... 9
Supported Website Starter Kits ................................................................................................................... 10
Applying a Skin from the Installation Wizard .............................................................................................. 11
Creating Skins .................................................................................................................................................. 12
Steps to Create a Skin .................................................................................................................................. 12
Required Files .......................................................................................................................................... 12
The Skin Manifest .................................................................................................................................... 13
Optional Files ........................................................................................................................................... 16
Packaging the Skin ................................................................................................................................... 16
Testing the Skin ........................................................................................................................................... 16
Submitting the Skin to the Repository ........................................................................................................ 17
Enabling a Starter Kit to Support Skins .................................................................................................... 17
Walkthrough: Creating a Skin for Simple Starter Kit ...................................................................................... 18
Step 1 – Install the Starter Kit Developer Package .................................................................................. 18
Step 2 – Create a Stylesheet .................................................................................................................... 18
Step 3 - Modifying the Template HTML .................................................................................................. 18
Step 4 - Preparing and Packaging the Skin ............................................................................................. 18
Step 5 - Testing a Skin .............................................................................................................................. 19
Advanced Skin Tasks .................................................................................................................................... 19
Altering Template Markup ...................................................................................................................... 19
Allowing for User customization of a Skin ............................................................................................... 20
Reference......................................................................................................................................................... 22
Dependency Types ...................................................................................................................................... 22
Text .......................................................................................................................................................... 22
Image ....................................................................................................................................................... 22

2 umbraco.org | About Skins – Beta | Umbraco I/S

Color ............................................................................................................................................................ 22
Option .......................................................................................................................................................... 23
Slider ............................................................................................................................................................ 23
Task Types ................................................................................................................................................... 23
ModifyCSS Task........................................................................................................................................ 23
ModifyTemplate Task .............................................................................................................................. 24
AddStyleSheetToTemplate Task .............................................................................................................. 25

3 umbraco.org | About Skins – Beta | Umbraco I/S

About Skins
How do Skins Work in Umbraco?
When you apply a skin to an Umbraco site, the skin’s styles are used in place of the existing site’s styles.
This is accomplished simply by providing a unique CSS file for the skin, including any images required to
achieve the layout defined by the CSS. A skin can also add or change small portions of the site’s HTML
Templates if needed. In addition, a skin can be customized by the user by adding such items as custom
label text or custom logo images. All CSS, images, and HTML changes can be rolled back to the default skin
for a site as Umbraco creates a backup of the default skin when a new skin is applied.

By default, skins can be applied to the Umbraco Starter Kits; Simple, Blog, Personal, and Business. In order
to apply or change a skin, the user simply navigates to the Settings section, selects the Master Template,
then clicks the Modify Template Skin button. Umbraco will launch the Skin Customization dialog in the
Canvas Editing mode.

What Can a Skin Change?

The recommend approach is that a skin changes only the CSS and related images and script for a site. If
needed a skin may also change small snippets of HTML, such as to add an “id” to an element or create a
new <div> for layout control. In this way, skins are kept as independent of a site’s markup as possible and
maintain maximum flexibility. A skin may also introduce a unique set of script, generally javascript, to add
functionality related to the skin. In addition, a skin may include images used for layout and styling.

Skin Example
For example, in the default Starterkit.Master Template contains this markup:

<asp:contentplaceholder id="cp_top" runat="server">

<div id="top">
<h1 id="siteName"><a href="/"><umbraco:Item runat="server" field="siteName"
recursive="true" /></a></h1>
<h2 id="siteDescription"><umbraco:Item runat="server" field="siteDescription"
recursive="true" /></h2>
<umbraco:Macro Alias="umbTopNavigation" runat="server" />
</div>

4 umbraco.org | About Skins – Beta | Umbraco I/S

</asp:contentplaceholder>

A skin might add a <div> element to apply a particular style to the navigation sections, as below:

<asp:contentplaceholder id="cp_top" runat="server">

<div id="top">
<h1 id="siteName"><a href="/"><umbraco:Item runat="server" field="siteName"
recursive="true" /></a></h1>
<h2 id="siteDescription"><umbraco:Item runat="server" field="siteDescription"
recursive="true" /></h2>
<div id="menu" class="container">
<umbraco:Macro Alias="umbTopNavigation" runat="server" />
</div>
</div>
</asp:contentplaceholder>

Notice in both cases the markup remains unchanged with the exception of the <div> added by the skin to
apply a particular style to the given element, in this case the umbTopNavigation macro rendered output.

In each case the underlying Document Types and Content remain unchanged. In order to apply the skin,
the user only needs to select the desired skin from the Skin dashboard in the site’s Settings section. The
markup, styles, and images associated with the skin are automatically applied by Umbraco.

How Do You Customize a Skin?

A skin can be further customized by editing the site’s Homepage in Canvas mode. Once the site’s
Homepage is opened in Canvas, the customize skin button will open an dialog containing any properties
that can be customized.

The dialog will contain input fields for any custom properties the skin contains.

5 umbraco.org | About Skins – Beta | Umbraco I/S

Once a user inputs or selects the custom property values and clicks OK, the new values are used in place of
the default values. These custom properties my be anything from text, as above, to images and color
pickers. An example of an image dependency type is shown below:

Changing Skins
By clicking on the change skin link the user can easily select a different skin available for the current
Template, or remove the skin by selecting the I prefer not to install a skin link. By clicking the customize
link the user is returned to the customize skin dialog above.

6 umbraco.org | About Skins – Beta | Umbraco I/S

Advanced Skins
A skin is located in a unique folder which contains all required files. Umbraco detects if a skin is selected
and applies the selected skin’s CSS, images and script. The skin applied to a site can be easily changed by
selecting the desired skin form the site’s Skin dashboard in the site’s Settings section.

An advanced skin can contain one or more templates which will be used in place of the existing templates.
Although the recommended approach is to use a pure-CSS approach, there may be times when applying a
new Template to the site is advantageous; such as when there are many HTML changes to be made. In this
case, a skin may apply a new .master Template to the site. This Template (or Templates) will replace the
default site Templates, though Umbraco will create a backup of the original site Templates to allow the skin
to be rolled back easily.

Advanced Skin Example

For example, in the default Starterkit.Master Template contains this markup:

<asp:contentplaceholder id="cp_top" runat="server">

<div id="top">
<h1 id="siteName"><a href="/"><umbraco:Item runat="server" field="siteName"
recursive="true" /></a></h1>
<h2 id="siteDescription"><umbraco:Item runat="server" field="siteDescription"
recursive="true" /></h2>
<umbraco:Macro Alias="umbTopNavigation" runat="server" />
</div>
</asp:contentplaceholder>

A skin’s Starterkit.Master Template might contain this markup:

<asp:contentplaceholder id="cp_top" runat="server">

7 umbraco.org | About Skins – Beta | Umbraco I/S

<div id="wrapper">
<div id="header" class="container">
<div id="logo">
<h1><a href="/"><umbraco:Item runat="server" field="siteName" recursive="true"
/></a></h1>
<p><umbraco:Item runat="server" field="siteDescription" recursive="true" /></p>
</div>
<div id="banner"><img runat="server" src="images/img01.jpg" width="667"
height="118" alt="" /></div>
</div>
<div id="menu" class="container">
<umbraco:Macro Alias="umbTopNavigation" runat="server" />
</div>
</asp:contentplaceholder>

Notice in both cases the id of the Content Placeholder, cp_top, remains unchanged as do the Umbraco
content items,”siteName” and ”siteDescription”, and the Umbraco ”umbTopNavigation” macro. In
addition, the skin applied also contains an image and a different layout structure than the default Starter
Kit skin.

The default Starter Kit Template above renders a page similar to this:

The skin Template above renders a page similar to this:

8 umbraco.org | About Skins – Beta | Umbraco I/S

In this case, it makes sense to apply a new .master Template to the site as part of the skin as there are
many markup changes.

The Structure of a Skin

Skin CSS and skin script files are stored in the default Umbraco folder locations, /css/ and /scripts/
respectively. When a skin is applied to a site, Umbraco copies the skin’s files to the default locations. A
skin contains all of its files in a folder names for the skin, under the /masterpages/ folder and may include
sub folders for organization.

What Does a Skin Package Contain?

Skins are packed in an archive (.zip) format and contian the following items.

 CSS files
 JavaScript files
 Images
 A skin manifest
 Optionally, one or more .master Template files
 Sub folders can be used to organize content

The Skin Manifest File

The skin manifest contains meta-information about the skin, such as author, skin name and description, as
well as specifying which Document Types and Templates are allowed and the definitions for any custom
skin properties.

9 umbraco.org | About Skins – Beta | Umbraco I/S

The CSS File
The skin’s CSS files are standard CSS files and should reference any dependent images required. The
recommended naming convention for a skin’s CSS file is:

Skinname_sitename.css

For a skin named “GoBlue” to be applied to the “Starterkit” site the skin’s CSS file would be named:

GoBlue_starterkit.css

Best practice is to keep the number of CSS files for a skin to only one.

The Script Files

If a skin contains a script file, the recommended target location is under the default /scripts/ folder in a
folder named for the skin as follows:

/scripts/GoBlue/script.js

In the skin folder, the script file can be in the root or in a sub folder.

The .master Template Files

As in the above example, a skin may contain Template files which will be used in place of the site’s default
Templates. These Template files may contain any markup, as long as the site’s Content Placeholders and
Umbraco item and macro tags remain intact. The ability to apply any arbitrary markup to a skin Template
gives skins an almost unlimited potential for layout control and variation.

Adding Custom Properties

A skin can contain any number of custom properties that can be set by the skin user. These properties are
set by the user when the skin is applied to a site. The properties can be of various types, including; text,
images, color picker, and others. By allowing a skin to be customized in this way Umbraco skins can be
made unique to each site by the site user.

Supported Website Starter Kits

By default, Umbraco skins are supported for the following types of Website Starter Packs:

 Simple Starter Kit

o Including the umbTopNavigation macro
o And the umb2ndLevelNavigation macro
 Blog Starter Kit
o Including macros contained by default
 Personal Site Starter Kit
o Including the umbTopNavigation macro
o And the umb2ndLevelNavigation macro
 Business Website Starter Kit
o Including macros contained by default

10 umbraco.org | About Skins – Beta | Umbraco I/S

Applying a Skin from the Installation Wizard
The Umbraco installation wizard allows the user to select a starter kit site and to apply a skin to the
selected site at the time Umbraco is installed. Once the site is installed and the skin applied the user can
customize the skin from the Canvas editing area as with skins applied from the Settings section.

By hovering over a starter kit icon the starter kit’s description will be displayed. By clicking a starter kit icon
the starter kit will be installed. The user can select the I prefer not to install a starter kit link to continue the
installation without installing a starter kit.

One a starter kit has been installed, the configure your site screen will display where the user can select an
available skin to apply to the starter kit. As above, by hovering over a skin icon the skin’s description will be
displayed. By clicking a skin icon the skin will be installed. The user can select the I prefer not to install a
skin link to continue the installation without applying a skin to the installed starter kit. In this case, the
starter kit’s default skin will be applied.

11 umbraco.org | About Skins – Beta | Umbraco I/S

Creating Skins
Not only are Umbraco skins easy to apply to a site, they are simple to create as well. Essentially a skin is
comprised of standard CSS, and optionally HTML, with a specific manifest that defines how the skin may be
used and defines any custom properties. There are no special tools required to build a skin, only a text
editor and/or a CSS/ HTML editor. In addition, a clean Umbraco instance with only the website starter pack
being targeted is recommended for testing.

Steps to Create a Skin

The steps needed to create a skin are as follows:

1. Create the skin’s CSS, script, and images

2. Optionally create the skin’s .master Templates
3. Place the skin files in a unique folder under the Umbraco site’s /masterpages/ folder
4. Create the skin manifest (skin.xml) in the root of the skin folder
5. Set skin name, description, and author information in the skin manifest
6. Specify which Document Types are allowed to use the skin
7. Specify which root Template the skin may be applied to
8. Create custom property definitions and tasks
9. In order to redistribute the skin, package the files in a .zip format archive with a unique and
descriptive file name

Required Files
For a skin, only a CSS file to be used in place of the default CSS and the skin manifest are required.
However, best practice is to include the skin’s styles in a separate CSS file, to store the site’s images in a sub

12 umbraco.org | Creating Skins – Beta | Umbraco I/S

folder, and to store the skin’s script files in a sub folder. A skin may also include additional files, such as a
license, readme, or additional instructions, but these files are ignored by the skin installer.

The Skin Manifest

The skin manifest is an xml file with some required and some optional sections. It must always be in the
root of a skin’s folder structure and must be named “skin.xml.” Following are details of each of a skin
manifest’s sections

Skin Information
Under the <Skin> root are the required elements which should be set for each skin.

<Skin>
<Name></Name>
<Author></Author>
<Version></Version>
<Description><![CDATA[]]></Description>

The <Name> property should be unique per skin as this will be used by Umbraco to display the available
skins to the user.

Setting Document Type permissions

Each skin must specify the alias of the Document Type it is allowed to be used on. This is typically the alias
of the Homepage Document Type for the target site.

<AllowedDocumentTypes></AllowedDocumentTypes>

Setting Template Permissions

Each skin must specify the alias of the root Template it is allowed to be applied to. This is generally the
“Homepage” template for a site.

<AllowedRootTemplate></AllowedRootTemplate>

Specify a Skin Palette

This property is left blank in the manifest and can be set during skin configuration by the user.

<SkinPalette></SkinPalette>

Specifying Custom Properties

Custom properties are defined as dependencies and can contain the property definition and task
definitions. A sample skin manifest snippet is below:

<Dependencies>
<Dependency type="Image" label="Please chose your logo image">

13 umbraco.org | Creating Skins – Beta | Umbraco I/S

 <Properties>
<Output>This is set by the image upload control</Output>
<Height>100px</Height>
<Width>200px</Width>
</Properties>
<Tasks>
<Task type="ModifyCss">
<TargetFile>Style.css</TargetFile>
<TargetRule>#logo</TargetRule>
<TargetParameter>background</TargetParameter>
<Value>no-repeat url( ${OutputPath} )</Value>
</Task>

There are two types of dependencies; Image and Text, and two types of tasks; ModifyCSS and
ModifyTemplate. Using these in combination a custom property can be used to update a logo image in a
Template or update a “background” class in a CSS file, among many other possible uses.

Text Type Dependency

The text type dependency allows a skin user to specify a text value for a property. This value can be used as
a label value, a tool-tip value, a site name value, or any other location where custom text can be used.

<Dependency type="Text" label="">

<Properties>
<Output></Output>
</Properties>

Image Type Dependency

The image type dependency allows a skin user to specify an image as the value for a property. The image
type handles the upload, resize, and crop of images specified by the user. The image type also specifies the
height and width of an image for a given property and will handle resizing an image selected by a use to the
specified dimensions.

<Dependency type="Image" label="">

<Properties>
<Output></Output>
<Height></Height>
<Width></Width>
</Properties>

ModifyCSS Task
The modify CSS task updates the specified target file with the specified value as defined by the properties
of the dependency.

14 umbraco.org | Creating Skins – Beta | Umbraco I/S

 <Task type="ModifyCss">
<TargetFile>Style.css</TargetFile>
<TargetRule>#logo</TargetRule>
<TargetParameter>background</TargetParameter>
<Value>no-repeat url( ${Output} )</Value>
</Task>

ModifyTemplate Task
The modify template task updates the specified target file with the specified value as defined by the
properties of the dependency.

<Task type="ModifyTemplate">
<TargetFile>Textpage.master</TargetFile>
<TargetID>logo</TargetID>
<TargetAttribute>src</TargetAttribute>
<Value>${Output}</Value>
</Task>

AddStyleSheetToTemplate Task
The AddStyleSheetToTemplate task will append a link tag to the head element of the specified file and can,
optionally, add the media attribute.

<Task type="AddStyleSheetToTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<Media>screen</Media>
<Value>${Output}</Value>
</Task>

The AddStyleSheetToTemplate task will append a link tag to the content area that is linked to the
ContentPlaceHolder with the id cp_content.

<Task type="AddStyleSheetToTemplate">
<TargetFile>Homepage.master</TargetFile>
<TargetSelector>//*[@ContentPlaceHolderID = 'cp_content']</TargetSelector>
<Media>screen</Media>
<Value>${Output}</Value>
</Task>

Using the AddStyleSheetToTemplate task, it is also possible to create tasks that will be executed on
installation of a skin. These tasks should be defined in the /Skin/Install element of the skin manifest and
have a fixed value.

15 umbraco.org | Creating Skins – Beta | Umbraco I/S

<Install>
<Task type="AddStyleSheetToTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<Value>/css/<skin name>/style.css</Value>
</Task>
<Task type="AddStyleSheetToTemplate">
<TargetFile>Homepage.master</TargetFile>
<TargetSelector>//*[@ContentPlaceHolderID = 'cp_content']</TargetSelector>
<Media>screen</Media>
<Value>/css/<skin name>/targetstyle.css</Value>
</Task>
</Install>

Optional Files
In addition to the above files, a skin may also include Template files which will be used in place of the site’s
default Templates. These are the standard .master HTML Template files and should have the same file
name as the site’s default Templates they target for replacement. Best practice when creating .master
Template files is to use the same layout in terms of the Template’s Content and Contentplaceholder
structure as the site’s original Templates.

If a skin contains .master Template files, Umbraco will use these in place of the site’s default .master
Template files when the skin is applied to the site. Umbraco will create a backup of the original Template
files for later use; if the skin in uninstalled or a different skin applied the backup files will be used for the
site’s Templates.

Packaging the Skin

Umbraco skins are packaged as archive format .ZIP files, must contain the skin.xml manifest file, a CSS file,
and may contain images, script, and other files as well as sub folders for organization. Best practice is to
create the sub folders with the same name as the default Umbraco folders. For example, the following sub
folders may be contained in a skin package:

 css
 scripts
 images

These sub folders should be created under an Umbraco site’s /masterpages/<skin name>/ folder.

The recommend approach is to use the Umbraco Package Creator located in the Developer section to select
the skin’s folders and files and to create the .zip file. Using the Umbraco Package Creator a readme text can
be included as well as the license to be applied to the skin package.

Testing the Skin

Testing a skin is simply the process of installing the skin to an Umbraco instance with the target starter kit
installed. Verify the skin can be installed, configured with custom properties (if used), and uninstalled.

16 umbraco.org | Creating Skins – Beta | Umbraco I/S

Submitting the Skin to the Repository
The process of submitting a skin to the repository for review and distribution is under development.

Enabling a Starter Kit to Support Skins

In order to enable skinning for a website starter kit, which is packaged as an Umbraco package, the
<enableSkins> element need to be added to the package manifest and set to true. With this element set to
true, the Umbraco installer will connect to the Umbraco repository and fetch skins which can be applied to
the current starter kit.

<enableSkins>true</enableSkins>

17 umbraco.org | Creating Skins – Beta | Umbraco I/S

Walkthrough: Creating a Skin for Simple Starter Kit
Following is a step by step guide to creating a simple skin for the Simple Starter Kit. Using the below steps
one can create a skin for any of the Umbraco starter kits. For the purpose of this walkthrough, assume the
skin name will be BigBlue.

Step 1 – Install the Starter Kit Developer Package

Before getting started, install the Starter Kit Developer package, which will install a feature-complete site,
with all available Umbraco modules installed, as well as a sample HTML page to be used when creating the
new skin.

Step 2 – Create a Stylesheet

Create a new stylesheet, and name it BigBlue_starterkit.css This stylesheet will be located in the folder
/css/BigBlue_starterkit.css

Add a link element to the StarterkitMaster template fot the created stylesheet, just below the included
Starterkit.css reference:

<link ref="stylesheet" type="text/css" src="/css/BigBlue_starterkit.css"></link>

With these items in place the skin specific stylesheet can be edited to change the appearence of the Starter
Kit site,this is the ”skin.” A basic HTML outline of the a Starterkit page is located at the end of this
document.

Including Images
Best practice for including images with your skin, is to create a dedicated folder for them under /css/. All
images will be found under a common path such as /css/SkinName/img01.jpg and the stylesheet can
refernce them directly with a relative path like so:

Background: url(SkinName/img01.jpg);

Step 3 - Modifying the Template HTML

It is possible to add HTML snippets to the default Starterkit template HTML. Best practice is to make any
desired changes using the skin tasks which are discussed in this document.

However, best practices for a Starterkit site skin is to not modify the Starterkit templates but, instead, to
accomplish the desired skin changes exclusively with CSS.

Step 4 - Preparing and Packaging the Skin

When all changes to the skin CSS are complete, the skin is ready for packaging. Preparing a skin for
packaging a skin can be accomplished in three steps

1. Create a new folder under the /masterpages/ folder, so you have path like /masterpages/BigBlue/
2. Copy the sample skin.xml file from the skin documentation to the newly created folder. It is
important that the file be named skin.xml.
3. Edit skin.xml

18 umbraco.org | Walkthrough: Creating a Skin for Simple Starter Kit – Beta | Umbraco I/S
 a. Update the name, author and description properties, leave the allowedTemplate set as:
StarterkitMaster.
b. Navigate to the <install> section. By default a "AddStyleSheet" task is added to the list.
Modify the stylesheet name to the skin’s CSS file name, /css/BigBlue_starterkit.css.
i. This will ensure that Starterkit gets your new stylesheet included in the html

With skin.xml file updated, the skin is complete. In order to allow a skin to be redistributable,it needs to be
contained in a package containing the files and folders for the skin. To create a skin package, follow these
steps:

1. From the Umbraco instance, navigate to the Developer section, expand Packages and right-click on
Created Packages, select Create, input the skin package name, and click Create
2. From the Package Files tab, add the following folder and files
a. /css/BigBlue_starterkit.css
b. /masterpages/BigBlue/
c. /css/BigBlue/images/
3. From the Package Properties tab fill in all the property values
4. Click the Save an Publish button to publish the skin package

When the skin package is published, the skin can be downloaded as a .zip file that can be installed on any
system with a Starter Kit installed.

Step 5 - Testing a Skin

To test a skin packaged as above, simply install the created skin package to an Umbraco instance with
Starterkit installed. Navigate to the content root of the Starterkit site and right-click the Homepage
node,then select Edit in Canvas. In Canvas mode there will be an Edit Skin button on the tool bar, click this
button and a skin editing dialog will be loaded where a skin can be selected and installed by selecting it and
clicking Apply.

To un-install the skin, click the Edit Skin button, de-select the skin, and click Apply. The skin will be
uninstalled and the default Starterkit skin will be applied.

Advanced Skin Tasks

Altering Template Markup
In the previous section we saw how to create a skin using only CSS, and this is the recommended approach
whenenver possible. However, a particular skin design may require that the Template markup be altered
inorder to facilitate the design. In this case it is possible to overridethe default HTML in the
StarterkitTemplate files. This is a more intrusive way of skinning, and has the risk of inadvertantly affecting
other elements that make up a site. As before, altered Tempates are fully uninstallable and the Umbraco
skin engine creates a back-up on when applying a skin so the default Templates are avaibale for a rollback if
needed.

For this example we will continue to work in folder structure created in the previous section. The above
tasks are pre-requisite for this section, so be certain to complete the above example first before continuing.

19 umbraco.org | Walkthrough: Creating a Skin for Simple Starter Kit – Beta | Umbraco I/S
A skin with HTML changes, overrides the default Starterkit Templates, and creates a backup of the original
Templates.

Steps to Change a Skin’s Templates

To change the HTML associated with a skin, simply edit the defaut Templates to accomodate the desired
the design. It is crucial that you keep all ASP.NET Content and Content Placeholder tags intact, do not
change the id, alias or other attributes of these tags. The can be freely moved within the markup, but the
naming should remain intact intact.

Based on the default Starterkit Templates, it is easy to recognoize the various Content Placeholders and
thier positioning.

When the HTML of the skin’s Template files is complete, and the site renders as expected in the browser,
the altered Template files can be included in the skin package.

To include Template in a skin package, copy the completed Templates to /masterpages/BigBlue/ so they
are located in the same folder as the skin.xml file.

Following the packaging step from abov, the skin’s Template files are now automatically included in the
package when the package is published.

Allowing for User customization of a Skin

A skin can contain a list of dependencies a user can edit when the skin is applied in order to personalize the
skin. These dependecies can be logos, header text, or a selected color, among other things. As detailed
above, these dpendencies and related tasks are definined in the skin.xml file (skin manifest).

The skin.xml for adding dependencies to a skincontains two parts:

Dependency
This defines the type of dependency (image, text, etc...)

<Dependency type="Text" label="Enter your company name">

<Properties>
<Output>My Company</Output>
</Properties>

Dependency Task
These are tasks performed based on the value entered for the dependency by the user and can be tasks like
modifying a stylehsheet, adding HTML to a Template or adding content to a page

<Task type="ModifyTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<TargetID>siteName</TargetID>
<Value>${Output}</Value>
</Task>

20 umbraco.org | Walkthrough: Creating a Skin for Simple Starter Kit – Beta | Umbraco I/S
Dependency Example
You wish to allow the user to modify the company name. To do this you add a dependency of the type Text
to the skin.xml:

<Dependency type="Text" label="Enter your company name">

<Properties>
<Output>My Company</Output>
</Properties>

Now that you’ve specified a company name, you need a task to process it. In this case we update the
StarterkitMaster Template with the user specified compnay name:

<Task type="ModifyTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<TargetID>siteName</TargetID>
<Value>${Output}</Value>
</Task>

Additonal tasks can be added to a dependency so the user specified value can be used to update multiple
Templates or CSS files. The complete xml added to skin.xml will be:

<Dependency type="Text" label="Enter your company name">

<Properties>
<Output>This is set by the text box control</Output>
</Properties>

<Tasks>
<Task type="ModifyTemplate">
<TargetFile>Textpage.master</TargetFile>
<TargetID>logo</TargetID>
<Value>${Output}</Value>
</Task>
</Tasks>
</Dependency>

21 umbraco.org | Walkthrough: Creating a Skin for Simple Starter Kit – Beta | Umbraco I/S
Reference
This section contains the reference for all dependency and task types.

Dependency Types
Text
Renders a text input box.

<Dependency type="Text" label="">

<Properties>
<Output></Output>
</Properties>
<Tasks></Tasks>
</Dependency>

Image
Renders a file upload control and allows optionally specified dimensions. If dimensions are specified, an
image cropper will be rendered.

Fixed Size

<Dependency type="Image" label="">

<Properties>
<Output></Output>
<Height></Height>
<Width></Width>
</Properties>
<Tasks></Tasks>
</Dependency>

Size determined by uploaded image.

<Dependency type="Image" label="Header">

<Properties>
<Output></Output>
</Properties>
<Tasks>
</Tasks>
</Dependency>

Color
Renders a color picker.

<Dependency type="Color" label="Company name color">

22 umbraco.org | Reference – Beta | Umbraco I/S

 <Properties>
<Output></Output>
</Properties>
<Tasks></Tasks>
</Dependency>

Option
Renders a drop down list input control.

<Dependency type="Option" label="Sample option">

<Properties>
<Options>blue;red;green</Options>
<Output></Output>
</Properties>
<Tasks></Tasks>
</Dependency>

Slider
Renders a jQuery slider control

<Dependency type="Slider" label="Site name size">

<Properties>
<Minimum>0</Minimum>
<Maximum>100</Maximum>
<Initial>10</Initial>
<Output></Output>
</Properties>
<Tasks></Tasks>
</Dependency>

Task Types
ModifyCSS Task
The modify CSS task updates the specified target file with the specified value as defined by the properties
of the dependency.

<Task type="ModifyCss">
<TargetFile>Style.css</TargetFile>
<TargetRule>#logo</TargetRule>
<TargetParameter>background</TargetParameter>
<Value>no-repeat url( ${Output} )</Value>
</Task>

23 umbraco.org | Reference – Beta | Umbraco I/S

ModifyCss Examples

Set color of element with id=companyname

<Task type="ModifyCss">
<TargetFile>starterkit.css</TargetFile>
<TargetRule>#companyname</TargetRule>
<TargetParameter>color</TargetParameter>
<Value>${Output}</Value>
</Task>

Set background image of element with id=company

<Task type="ModifyCss">
<TargetFile>starterkit.css</TargetFile>
<TargetRule>#company</TargetRule>
<TargetParameter>background-image</TargetParameter>
<Value>url(${Output})</Value>
</Task>

ModifyTemplate Task
The modify template task updates the specified target file with the specified value as defined by the
properties of the dependency.

<Task type="ModifyTemplate">
<TargetFile>Textpage.master</TargetFile>
<TargetID>logo</TargetID>
<TargetAttribute>src</TargetAttribute>
<Value>${Output}</Value>
</Task>

ModifyTemplate Examples

Set innertext of element with id=companyname

<Task type="ModifyTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<TargetID>companyname</TargetID>
<Value>${Output}</Value>
</Task>

24 umbraco.org | Reference – Beta | Umbraco I/S

Set src attribute in element with id=companyname

<Task type="ModifyTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<TargetID>companyname</TargetID>
<TargetAttribute >src</TargetAttribute >
<Value>${Output}</Value>
</Task>

AddStyleSheetToTemplate Task
The AddStyleSheetToTemplate task will append a link tag to the head element of the specified file and can,
optionally, add the media attribute.

<Task type="AddStyleSheetToTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<Media>screen</Media>
<Value>${Output}</Value>
</Task>

AddStyleSheetToTemplate Example
The AddStyleSheetToTemplate task will append a link tag to the content area that is linked to the
ContentPlaceHolder with the id cp_content.

<Task type="AddStyleSheetToTemplate">
<TargetFile>Homepage.master</TargetFile>
<TargetSelector>//*[@ContentPlaceHolderID = 'cp_content']</TargetSelector>
<Media>screen</Media>
<Value>${Output}</Value>
</Task>

Install Tasks
Using the AddStyleSheetToTemplate task, it is also possible to create tasks that will be executed on
installation of a skin. These tasks should be defined in the /Skin/Install element of the skin manifest and
have a fixed value.

<Install>
<Task type="AddStyleSheetToTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<Value>/css/<skin name>/style.css</Value>
</Task>
<Task type="AddStyleSheetToTemplate">
<TargetFile>Homepage.master</TargetFile>
<TargetSelector>//*[@ContentPlaceHolderID = 'cp_content']</TargetSelector>

25 umbraco.org | Reference – Beta | Umbraco I/S

 <Media>screen</Media>
<Value>/css/<skin name>/targetstyle.css</Value>
</Task>
</Install>

Complete Dependency with Tasks Example

<Dependencies>
<Dependency type="Text" label="Company name">
<Properties>
<Output></Output>
</Properties>
<Tasks>
<Task type="ModifyTemplate">
<TargetFile>StarterkitMaster.master</TargetFile>
<TargetID>companyname</TargetID>
<Value>${Output}</Value>
</Task>
</Tasks>
</Dependency>
<Dependency type="Color" label="Company name color">
<Properties>
<Output></Output>
</Properties>
<Tasks>
<Task type="ModifyCss">
<TargetFile>Starterkit.css</TargetFile>
<TargetRule>#companyname</TargetRule>
<TargetParameter>color</TargetParameter>
<Value>${Output}</Value>
</Task>
</Tasks>
</Dependency>
<Dependency type="Image" label="Header">
<Properties>
<Output></Output>
<Height>150</Height>
<Width>600</Width>
</Properties>
<Tasks>
<Task type="ModifyCss">
<TargetFile>Starterkit.css</TargetFile>
<TargetRule>#company</TargetRule>
<TargetParameter>background-image</TargetParameter>

26 umbraco.org | Reference – Beta | Umbraco I/S

 <Value>url(${Output})</Value>
</Task>
</Tasks>
</Dependency>
</Dependencies>

27 umbraco.org | Reference – Beta | Umbraco I/S