Issuu on Google+

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 â&#x20AC;&#x201C; 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. 2. 3. 4. 5. 6. 7. 8. 9.

Create the skin’s CSS, script, and images Optionally create the skin’s .master Templates Place the skin files in a unique folder under the Umbraco site’s /masterpages/ folder Create the skin manifest (skin.xml) in the root of the skin folder Set skin name, description, and author information in the skin manifest Specify which Document Types are allowed to use the skin Specify which root Template the skin may be applied to Create custom property definitions and tasks 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 â&#x20AC;&#x201C; 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 â&#x20AC;&#x201C; 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â&#x20AC;&#x2122;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 â&#x20AC;&#x201C; 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â&#x20AC;&#x2122;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 â&#x20AC;&#x201C; 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 â&#x20AC;&#x201C; 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 â&#x20AC;&#x201C; 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 â&#x20AC;&#x201C; 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 â&#x20AC;&#x201C; 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 â&#x20AC;&#x201C; Beta | Umbraco I/S


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

27

umbraco.org | Reference â&#x20AC;&#x201C; Beta | Umbraco I/S


The test PDF Viewer