Macro Parameters syntax

What is Macro parameters?

A macro parameter is in short a value you send to a Macro from Umbraco. This could be piece of text, a node ID or even a big chunk of xml. To do this you have a handfull of different form controls you can use:

• bool - A true/false value
• contentPicker - the ID of the selected node as a single integer.
• contentRandom - the xml from a random node.
• contentTree - the xml of the selected node and it's child nodes
• contentType - the alias of a selected content type as a string
• contentTypeMultiple - a comma separated list of selected content type aliases
• mediaCurrent - the xml of the selected media item
• numer - an integer
• propertyTypePicker - the alias of the selected property type
• propertyTypePickerMultiple - a comma separated list of selected property type aliases
• tabPicker - the caption of the selected tab
• tabPickerMultiple - a comma separated list of selected tab captions
• text - a text string
• textMultiline - a text string.
  

Let's continue and look at how you use macro parameters with an xslt macro and what they look like in your xslt.

Setting up a macro parameter

First let's create a simple xslt script which will have 2 simple parameters, a text string and a contentTree type - to recap: A text type is a simple string and a contentTree type is the xml of a selected node.

• Adding the parameters
• Create a xslt macro
• Look under the "parameters" tab on the macro settings screen.
• Create a new parameter the alias "text" name "Text property" and type "text"
• Create a second parameter called "contentTree" with the name "Select Node" and the type "contentTree

Writing some basic xslt

Okey so now we have a macro with some parameters. Lets get these parameters into the xslt.

Our Xslt code (without the stylesheet info):

<xsl:template match="/">
  <xsl:copy-of select="/macro/text">
  <xsl:copy-of select="/macro/contentTree">
</xsl:template>

Inserting the macro on a template

Write some text and pick a node in the content tree by clicking "choose item" - then save. Go take a look at the page in your browser (try viewing the source of the page to see what it actually returns)

Great, you're done with setting up parameters and getting the data into a xslt macro. Let's continue and look at what that data actually look like and how it actually works...

Working with parameters in xslt

Okey so sofar we've setup a simple xslt script, added 2 parameters and picked some simple data for the parameters when we inserted the macro in a template.

So what does the 2 parameters return?

The <xsl:copy-of select="/macro/text" /> returns:

<text>Hello World</text>

The <xsl:copy-of select="/macro/contentTree" /> returns:

<contentTree nodeID="1053">
<node id="1053" version="a1e061ab-3109-4690-9374-bd0f05882e9b"
parentID="1052" level="2" writerID="0" creatorID="0"
nodeType="1044" template="1043" sortOrder="1"
createDate="2005-12-30T14:01:21" updateDate="2007-06-21T14:06:32"
nodeName="About" urlName="about" writerName="Administrator"
creatorName="Administrator" nodeTypeAlias="wwTextpage"
path="-1,1052,1053">
<data alias="bodyText">Body text...</data>
<data alias="header">My Header text...</data>
</node>
</contentTree>

So as you can see: the text parameter simple sends the text string we entered to the macro and the contentTree paramater sends a big chunk of xml describing the node we selected. If the node had any child nodes these would also be send to the xslt macro as xml.

Explaining how the parameters are send to the macro

When you setup a macro parameter for a xslt macro. You basicly tell umbraco to send some xml to the xslt script. This xml looks something like this:

<macro>
<parameteralias1>Value</parameteralias1>
<parameteralias2>Value</parameteralias2>
</macro>

So with this infomation along with some basic xpath we can query the xml from the parameters. which is what are doing with "/macro/text" which will get the value from the "text" parameter and the "/macro/contentTree" which will get the value of the parameter with the alias "contentTree" we could then go on a do some basic xpath work on the contentTree macro to return the selected nodes name like this:

<xsl:value-of select="/macro/contentTree/node/nodeName"/>

or get it's bodyText value with

<xsl:value-of select="/macro/contentTree/node/data [@alias = 'bodyText'"/>

Okey so now we are able to define parameters, input some data, get the data to the xslt and work with it in the xslt file. Let's continue to take a look at all the different types of parameters and what they look like in xslt

XSLT Logic, Variables and Parameters

Some XSLT Logic

XSLT has some logic commands that useful to processing criteria based output. These commands are the "if" and "choose" commands.

The "if" command is useful for deciding to show content or not based on a single criteria. There is no "else" in XSLT, so, the if is somewhat limited.

<xsl:if test="@nodeName = 'example' ">

<!-- do this -->

</xsl:if>

The "choose" command is a bit more powerful in that it allows for multiple choices to be selected from.

<xsl:choose>

<xsl:when test="">

<!-- do this -->

</xsl:when>

<xsl:otherwise>

<!-- do this -->

</xsl:otherwise>

</xsl:choose>

In this example, you can have as many when statements as you like, but must have the otherwise statement.

Using Variables and Parameters

Variables and parameters are temporary storage devices in XSLT for holding simple values to complete node sets of data.

Variables are defined with a name, and can be filled two different ways. The first method is to select the data into the variable as follows:

<xsl:variable name="myID" select="$currentPage/@id"/>

The second method is to fill the variable by having the content rendered into the variable.

<xsl:variable name="myID">

<xsl:value-of select="$currentPage/@id"/>

</xsl:variable>

The second method is useful when applying logic to filling the variable, in which case an if command or choose command would allow you to have the value selected logically.

Parameters are handled the same way, except their command is "xsl:param".

As for the difference, it is a matter of where they can be assigned.

Using XPATH

Now that we know what is stored in the XML, and know where the XML is in our XSLT, we can now try to retrieve the data, and format it to our needs.
As previous mentioned, XSLT uses an XML structure to define the processing rules. So we need to learn what a few of the processing elements for XSLT are.
Displaying content from the XML document
First, one of the most important elements is the "value-of" command. It is written as follows:

<xsl:value-of select="...."/>

This command is one of the most prevalent, and has a couple additional attributes to allow for the output to be controlled as needed. We will look into that later.

In the template area of the XSLT file, we can write our first output now using the value-of command. We know our data is in the $currentPage parameter, and its context is focused on the requested page's node. Thus, if we want to get the name of the current page, we can use the "nodeName" attribute of the node to display the name. Attributes are referenced in XPATH using the "@" with the name of the attribute following, thus "@nodeName".

<xsl:template match="/">

<xsl:value-of select="$currentPage/@nodeName"/>

</xsl:template>

To explain, the "$currentPage" is looking at the node in the XML document for the current requested page. The "/" is telling us to look at all child elements and attributes. The "@nodeName" says we want the attribute named "nodeName".
Placing the macro on a template would render the name of the current page when the template is displayed.
Going a bit deeper, we may want to display user input content, such as a simple text field named "Website". This is set up in the document type as a text field with the alias "Website". Since this is not a default property, it is referenced using the data element, which there may be multiple of, depending on the number of custom properties on the document type. Thus, referencing this property, our template would look like this:

<xsl:template match="/">

<xsl:value-of select="$currentPage/data [@alias='Website']/text()"/>

</xsl:template>

To explain, we are again focused on the child elements of the current page, which we select the ones that have the element name of "data". We go one step further, and filter that selection with the usage of "[@alias = 'Website']", which is called a predicate.
The predicate acts as a filter, only returning the results that match the test specified. In this case, only returning the data element that has an "alias" attribute with the value of "Website".
The results are then passed along to the next item that selects the child items, and we return the text of this element. (The "/text()" is optional, but typically helps some understand the context of their statement.)
Now that we can list out the data from our documents, it is time to go deeper.

XPATH and XSLT Loops

Another useful command in XSLT is the "for-each" command. This command takes an XPATH statement and iterates the results for each match, executing the nested commands each time. The "for-each" command looks as follows:

<xsl:for-each select="....">

...

</xsl:for-each>

So using this command, we can select multiple items and list them out with a very simple call.

Lets say that our current page has 5 sub-pages, named one, two, three, four, and five. We want to list those 5 pages names on the current page. Thus, we need to loop through the child nodes of the current page.

<xsl:for-each select="$currentPage/node">

<xsl:value-of select="@nodeName"/>

</xsl:for-each>

To explain, we are selecting all child node elements from the current page, looping each node. The value-of is selecting only the attribute named @nodeName.

Confused? Don't be. The value-of inherits the context of the for-each command, thus, it knows it is on the current node in the loop. If that confuses you too much, you can always write the statement as such:

<xsl:for-each select="$currentPage/node">

<xsl:value-of select="current()/@nodeName"/>

</xsl:for-each>

or

<xsl:for-each select="$currentPage/node">

<xsl:value-of select="./@nodeName"/>

</xsl:for-each>

Using "current()/" allows you to easily see that you are working against the current item in the loop, and the "./" notation is actually saying select myself.
The resultant output of this will be the five pages listed without any markup, which will be rather difficult to read. So, lets add some unordered list markup for usage in our website.

<ul>

<xsl:for-each select="$currentPage/node">

<li><xsl:value-of select="current()/@nodeName"/></li>

</xsl:for-each>

</ul>

Now, we will get bulleted list of page names.

Understanding "currentPage"

As mentioned on the previous page, the currentPage parameter is important for us in Umbraco. It is the complete XML document of the published site, and is how we reference the data stored in each document. By default, the context of the XML document is set to the requested page.

In XSLT, to reference the parameter, and other variable types, we use the "$" and the name of the variable or parameter, thus $currentPage. However, before we use this parameter, we need to know what is in the XML document, and how to reference the content.

XML is referenced in XSLT through the use of XPATH, a query syntax that resembles that of DOS file commands. Since XML has the ability to contain various levels of information, XPATH has means to traverse these levels, and retrieve data based upon the current context. But again, before we can use XPATH, we must know what is in the XML document.

The XML document, as mentioned before, contains all the content of the published documents. This data is stored in the XML document structured in the same manner as your tree is laid out in Umbraco. So, documents are nested to create the hierarchy that we can easily use.

Each document in Umbraco consists of several common pieces of data, and they are:

• id


• version


• parentID


• level


• writerID


• creatorID


• nodeType


• template


• sortOrder


• createDate


• updateDate


• nodeName


• urlName


• writerName


• creatorName


• nodeTypeAlias


• path

These are store as attributes of the document, which is called "node". The properties that are added to the document in Umbraco, and what the user edits are referenced as "data". Data consists of a couple common pieces of data, which are attributes on the data elements. These are:

• alias


• versionID

This is structured similar to the following in the XML document.

<!DOCTYPE umbraco [

<!ELEMENT nodes ANY>

<!ELEMENT node ANY>

<!ATTLIST node id ID #REQUIRED>

]>

<root id="-1">

<node

id="numeric-value"

version="guid-value"

parentID="numeric-value"

level="numeric-value"

writerID="numeric-value"

creatorID="numeric-value"

nodeType="numeric-value"

template="numeric-value"

sortOrder="numeric-value"

createDate="datetime-value"

updateDate="datetime-value"

nodeName="text-value"

urlName="text-value"

writerName="text-value"

creatorName="text-value"

nodeTypeAlias="text-value"

path="csv-numeric-value"

>

<data

versionID="guid-value"

alias="text-value"

>

field-value or <![CDATA[field-value]]>

</data>

<data ...>...</data>

<node ...>...</node>

</node>

<node ...>...</node>

</root>

XSLT Basics

What is XSLT

XSLT, or eXtensible Stylesheet Language Transformations, is a document that is applied programmatically to an XML Document to manipulate the data. The structure of XSLT resembles that of XML, and contains specialized tags to perform specific actions to the data.
In umbraco, XSLT is utilized through the use of macros, which are the dynamic building block of front-end content. These templates can be used for various tasks, including the building of navigation structures, display of content nodes in a customizable format.
umbraco also exposes a series of functions to XSLT documents for the manipulation of the data beyond the standard capabilities of XSLT functions. These XSLT Extensions are easily referenced within the mark-up of the XSLT, allowing for easy manipulation of the data for even the most novice developers.

How umbraco uses XSLT.

Umbraco utilizes XSLT to dynamically render content such as navigational structures, lists, and nearly anything you can dream of. This is accomplished through the use of Macros.

Creating Your First XSLT Macro
Creating an XSLT macro is very easy.
1. Go to the developers section in the administration area.
2. Right click on the XSLT folder, and select create.
3. You will receive a dialog where you can specify the name, select an XSLT template, and specify if you want to automatically create the Macro for this template.
4. Specify the name of the new XSLT file, check Create Macro, and select a template if you desire. Click Create.
5. You have now created the XSLT file and the Macro for rendering the content.

Now that we have the XSLT created, we need to customize it to output our content the way we like.

XSLT - The Basics

The standard XSLT file consists of a few different parts. Understanding these parts will allow you to do much more with XSLT than you probably realize.
First, we have the declaration of the XML file, since XSLT is structured off of XML. This consists of the various entries at the top of the file. Unless you are adding customized functions to your XSLT, this will typically not be edited.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE xsl:Stylesheet [ <!ENTITY nbsp "&#x00A0;"> ]>

<xsl:stylesheet

version="1.0"

xmlns:xsl="http://www.w3.org/1999/XSL/Transform%22

xmlns:msxml="urn:schemas-microsoft-com:xslt"

xmlns:umbraco.library="urn:umbraco.library"

exclude-result-prefixes="msxml umbraco.library">

<xsl:output method="xml" omit-xml-declaration="yes"/>

Next, we have a parameter declaration that is very important to us as it is the default link to the content published in the site. This parameter contains all the data in the site, but is focused on the current page that is loaded. Thus it is named "currentPage".

<xsl:param name="currentPage"/>

Below this, we have our template. This is the portion that is responsible for the output.

<xsl:template match="/">
</xsl:template>

And finally, we close out the template, since this is XML, everything must be properly structured.

</xsl:stylesheet>

Now that we know what the basic things are here, we can look into what can be done.

Templates part III - Using Master Templates

Thursday, December 13, 2007 by Niels Hartvig

Master Templates

A master template is the exact same thing as ordinary Templates and they're created in the same way as we created our "Home Page" template in the previous tutorials. The only difference is that a Master Template includes a bit of information about where Child Templates should be inserted. This is a very simple, but efficient way to ensure that you don't repeat yourself and only need to make modifications in one place. You can even nest multiple master templates for maximum flexibility.

For a start we'll create a Master template based on the markup in our "Home Page" template. Then we'll update our "Home Page" template to use our new master template and at last we'll do the same for our "Text Page" templates. So head over to the "Settings" section of umbraco and let's get started.

Creating a Master Template

To create a Master Template, simply right click "Templates" and choose create:

In the Dialog, call the new Master Template "Master" and click "Create:

As you can see in the tree view, a new template has been created, so let's copy the markup from our "Home Page" template to the master.

Click the "Home Page" template in the tree view and copy the markup (by either using the mouse or keyboard short-cuts: CTRL+A and CTRL+C):

Now, click the "Master" template in the tree view and paste the contents into the text area.

The next step is to make a little modification to our markup which will turn this template into a Master Template. We'll replace the with an instruction to insert a child template instead. That instruction is called "" and remember that you can always get a list of template elements by clicking the little blue help icon in the toolbar. Remember to click the "Save" icon and then your final markup should look like this:

Using the Master Template

The next step is to modify our "Home Page" template so it uses our Master Template. It's very simple, all you need to do is to choose the Master Template from the "Master Template" dropdown. Once that's done, we can remove all the markup from the "Home Page" template which now is stored in our Master Template. So edit the "Home Page" template, choose "Master" as the Master Template and modify the template markup so it looks like this (and remember to save):

As you can see our Home Page template is much cleaner and because we can repeat this technique on all the other templates we'll use on our site, future changes in the central markup will be very easy to maintain, as it's stored in one single template instead of being spread across all.

Templates part II - Adding page information to templates

Wednesday, December 12, 2007 by Niels Hartvig

Before we start, it might be a good idea to recap what we've done so far:

- We've created two Document Types and templates - "Home Page" and "Text Page"
- We've added some properties to the Document Types, so an author could edit some content in a WYSIWYG editor as well as add some Meta data information. These properties had:
A "Name" which the author will see An "Alias" which is used in code and templates to access the property
A "Tab" so we can divide properties into different section for better overview
A "Type" which very simplified determines how the property looks like when editing it - is it an upload field, a WYSIWYG editor and a date chooser
- We've added a few pages to the content tree
- We've edited the "Home Page" template and hard coded Hello World

Adding html to our template

Now it's time to create a little more advanced template where we'll use the values stored on our pages. Have no fear, it's very easy and we'll take it slow.
Start by going to "Settings", fold out the "Templates" tree and click the "Home Page" template:

We'll replace the "Hello World" with some proper markup, so remove the "Hello World" and paste the following html:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

    <head>

        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

        <title>[A title should be placed here]</title>   

    </head>

    <body>

        <div id="container">

            <div id="navigation">

                [Add navigation here]

            </div>

            <div id="content">

                [Add page content here]

            </div>

        </div>

    </body>

</html>

Click the Save icon in the toolbar and your screen should look like this:

As you can see, this is some very bare bone html complete with placeholders which will replace with some umbraco template elements in a moment. For now, go look at the website and do a view source:

Notice how the markup outputted by umbraco is completely identical to the markup you added in the template, including whitespace (tabbing). It shouldn't come as a surprise, remember I promised that umbraco wouldn't mess with your markup, but now you got evidence. With umbraco, you finally have a ASP.NET CMS that respects your markup. Now it's time to add some dynamics to the placeholders!

Accessing page properties in the templates
Let's head back to our "Home Page" template and replace the placeholders (the text in the square brackets) with some dynamic content - it's time to play with some umbraco template elements. So far we've just been adding good old html to the template, but if you want other than hard coded content in your templates (and that would be nice wouldn't it?) then you'll need to learn a little more.

In the previous tutorial I showed you the five different umbraco elements, but I also promised that you didn't really needed to write them yourself because the template editor offers build in UI.

We'll start by adding the title of our umbraco page to the html title header, so remove the text "[A title should be placed here]" and place your cursor inside the "TItle" elements and click the "Insert umbraco page field" button in the toolbar:

A new dialog will appear giving you some handy options for inserting page properties to your template. For now we'll focus on the simplest way to insert a property and then we'll get back to the various options in a later tutorial. If you open the dropdown from the "Choose field" you can see a list of all the page properties that's currently created in your umbraco installation. The ones in the bottom of the list, prefixed with a "@" is build-in properties that exists on all pages created. The ones in the top is the custom ones you've created.

For now choose "@pageName" from the "Choose field" drop down and click the "Insert" button in the bottom of the window:

umbraco will insert the template markup needed for the title of the page into your template:

Now do the same for the [Add page content here]:
Remove the placeholder text
Click the "Insert umbraco page field" button in the toolbar
Choose "bodyText" in the dropdown (that's the alias of our WYSIWYG property we created in a previous tutorial, remember?) and click "Insert"
Click "Save" in the toolbar
The final result should look like this (we'll work on the navigation in a later tutorial):

Now, go see your "Home Page" of your website. Notice how umbraco automatically insert the content into the template. You can try modifying the contents of the WYSIWYG editor or the title of your page. Just remember to Publish the page and then view it afterwards:

And again - view source will reveal the cleanest markup ever seen from a .NET powered CMS:

Templates part I - The introduction

Friday, December 07, 2007 by Niels Hartvig

Introducing templates

One of the things that people really likes about umbraco is that it gives you complete - as in total, non-destructive and non interfering - control over the output. This assures that you can create valid, semantic and accessible markup in anyway you want. And so far we haven't told umbraco anything, so it proves it's worth; I won't do anything, because that's what I'm told. If only I could raise my kids like I raised umbraco ;-)

The solution to our blank page is adding markup to our templates, but before we do that I'd like to take a moment to explain what a template in umbraco actually is - which is very simple. An umbraco template is basically text - usually (X)Html - combined with umbraco tags (elements). This means that you can simply take your own markup and replace the chunk of "Lorem Ipsum" (or whatever you call your placeholders) with umbraco tags. That's it! umbraco will respect your attention to detail when it comes to markup and output exactly the same as you created, including whitespace, tabs and linebreaks and it gets even better - you don't need to learn a new proprietary and obscure template language.

The Template Tags

Instead of having it's own template language and re-inventing the wheel by having yet-another-way-to-handle-presentation-logic, umbraco is based on standards for dynamic content, which we'll get back to in a moment. For know, let's focus on the simplicity of the template elements which consists of five element (yes, just 5!):

1. : This is for inserting a property from the current page that's rendered. So if we wanted to output the name of the page we would simply write: (in fact we wouldn't as there's a complete UI - you don't even have to learn the element syntax!)
2. : This is for inserting dynamic content like lists or forms. We'll explore macros in depth in a later tutorial, but basically a macro is a wrapper for either a .NET control or an XSL Template, which is a standard made by W3C, the same group who developed Html.
3. : With umbraco you can have the central layout stored in Master Templates and this element will determine where to insert child templates that uses the master.
4. . As umbraco is based on Microsoft ASP.NET, but don't output any markup unless told (you get the picture now, right!) you'll need to tell umbraco where to put a serverside form if you use .NET Controls.
5. . If you wish to use an ASP.NET server side Head element, you'll use this element
Help on the elements is always near by - simply click the "Help" button in the toolbar when editing a template and you'll get the list:


Updating our template

Enough with the theory - let's try to make a simple templates. Go to the Settings section and foldout the templates. If you've followed the previous tutorials, you can see we have two templates which was automatically created when we added the corresponding Document Types (because we checked the "Create matching template" box when creating the Document Type):

Click the "Home Page" template and you'll see this view:

For now we'll concentrate on the "Template" textbox, so try to add "

Hello World

" into the big textarea and click the Save button in the toolbar. Now try go previewing your Home Page:

Stunning!

Adding page information to the template

Now you always need a Hello World Sample, but wouldn't it be great to improve just a little? Well, come back tomorrow and we'll start using the elements (I would have liked this tutorial to been a little longer, but I ran out of time!)

Document Type Part II

Document Type Creation Walk Through

Step 1 - Open the umbraco administration application.

Step 2 - Click on the Settings section icon in the lower left corner of the screen.

Step 3 - Right-Click on the Document Types node in the Settings tree.

Step 4 - Click the Create menu option.

Step 5 - Type the name of the Document Type you are creating and check the "Create matching template" checkbox.

Note: The majority of the time you will want a template associated with the Document Type. Future versions of umbraco may have the checkbox checked by default, but as for now make sure it is checked. In this walk through we will create a Text Page which is a simple type that just has a single property "Content". This type will allow the content editors to create basic pages.

Step 6 - Create a Tab be first selecting the Text Page document type in the settings tree and selecting the "Tab" tab. Type "Content" into the New Tab text box and then click the New Tab button. This will add the tab to the tabs list displayed below the text box.

Step 7 - Click the save icon.

Note: VERY IMPORTANT! The administration application is a web page, this means you will not be warned if you change pages by selecting a different section and you HAVE NOT SAVED your current work. You should get in the habit of clicking the save icon every time you make changes. This applies to every part of the administration application.

Step 8 - Click on the "Generic properties" tab and click the "Click here to add a new property" bar under the "Add New Property Heading.

Step 9 - In the Edit "Creation new property" fields enter the following information: In Name enter "Content", in Alias enter "bodyText", in Type select "Richtext editor", and in Tab select "Content".

You may be wondering why bodyText is used. There is no requirement that says you must use this alias however, bodyText is generally used in umbraco and by using it we save ourselves work in other areas because we don't have to keep changing the value to whatever we used instead.

Step 10 - Click the save icon.

Step 11 - Click on the "Structure" tab and put a check in the Text Page check box.

Step 12 - Click the save icon.

Step 13 - Click on the "Info" tab and select the doc.gif item from the icon list, select the doc.png item from the thumbnail list, add a description and ensure that "Text Page" is checked in the Allowed Templates and that it is also selected in the Default Template list.

Step 14 - Click the save icon.

Summary
If you have followed the steps above, you have successfully created a Document Type. You are now only 1/2 way done. You can now create pages in the content section however when you view them you will see nothing. The reason is you have only created the data structures, you have not created any view. In order to create views for your site You will need to create Templates. Templates are a topic for another book. However, this walk through is not very useful if you can't see your data so we will do one minor extra step to enable at least a basic view of your content.

Bonus Step - Select the Text Page template under the Templates node in the Settings tree. The metadata for the template will show up in the right pane of the screen. In the Template field type in the following value and click the save icon:


You can now go to the content section and create new pages for your site by right clicking on the Content node and selecting "Create". If you were able to follow this walk through you should have no problems creating content as it works in the same manor.

Don't be afraid to experiment and have fun!

Document Types Part I

Document Types

Umbraco defines two basic structures, Document Types and Templates. While Templates are important, they are not discussed here. If you want to read about Templates you can find that infomration in a separate book called "Templates Explained". Today we will focus on Document Types. A Document Type is a structure used to define how and what data to collect from a user during content editing. You can think of a Document Type as a definition much like that of a database table. A Document Type is made up of Properties, Tabs, Structure, and Info. I describe them below in the order I found important to understand.

Properties

When you are creating a Document Type you are defining fields that will be used to enter data. These fields are called Properties in umbraco. Properties are defined on the "Generic Properties" tab. Creating properties is not the first step, first you will want to create Tabs which are explained next. Properties have metadata (a term used to define data that is used to define or describe an object). Items in the metadata include: Name, Alias, Type, Tab, and others. Tip: If you create a new page but cannot enter the content you expect, check and ensure you have created a Property for it and that you are looking at the tab the property was set to.

Name - This item is the user friendly name of the property. The typical example used in many tutorials for this is "Content". This is the text that the user will see describing the property during content editing.

Alias - This item is the text used by umbraco during the GET_ITEM calls. Basically this means anytime you want to refer to the property within code such as a template you will use the Alias.

Type - This item is a selection from a list of Data Type objects. Data Types are not the same as those in computer programming. A Data Type in umbraco is an editor type associated to the Property. A common Type used is "Rich Text Editor"; selecting this type will display a rich text editing control to the user during content editing of this Property.

Tab - This item allows you to select which Tab this property will be presented to the user during content editing. This list is populated from tabs created in the Tabs section. General Properties is a selection in the list, this is a little confusing, but it is actually referring to the Properties tab that is displayed during content editing. The Properties tab is a good place to define properties you want to use as metadata fields.

Tabs

Document Types organize Properties on the screen by using Tabs so the first thing you will want to do when creating a Document Type is create one or more tabs. Later in this book we will walk through the steps of creating a Document Type so many of these items will be clearer. Tabs only have one piece of metadata: Name which is the text display used to identify the tab and is the text displayed in the Tab.

Structure

The Structure tab is where you control the hierarchy of your site. Structure allows you to determine which Document Types can be nested as children to the one you are creating. This means that if a user tries to create a new page of content under the Document Type, they will only have options of the Document Types checked in the Document Type's Structure. Tip: If you try to create a new page of content under another and you cannot add a type you expect, check the structure tab of the parent Document Type and ensure the expected type has been checked.

Info

While the Info tab is the first tab on the Document Type, it is less important than the others. This is because the Info tab primarily entails the display options for the Document Type while the other tabs define the Document Type itself. Metadata set on the Info tab include: Name, Alias, Icon, Thumbnail, Description, Allowed Templates, and Default Template, this data is described below.

Name - This item is the user friendly name of the Document Type. This is the text that the user will see in the type selection drop down list on the Create Page dialog. Tip: If you see Document Types in the drop down list that you didn't intend, you should modify the structure of the parent page's Document Type.

Alias - This item is the text used by umbraco.

Icon - This item is a selection from a list of images. The icon is the image that is displayed in the content tree.

Thumbnail - Do not confuse the Thumbnail with the Icon. The Thumbnail is a larger image that shows on the Create Page dialog.

Description - The description text is displayed on the Create Page dialog. This is a good place to inform the user about what the Document Type is intended for.
Allowed Templates - Document Types only define the content data not how that content is displayed. Displaying the content is the job of the Template. A Document Type could be used in more than one template. The Allowed Templates allows you to control which templates are allowed to access this Document Type. This is important because it lets you display the same data differently in different areas of your site.

Default Template - The default template is the template used by default when creating a page of this Document Type.

Configure Umbraco

Configure IIS

Do not attempt to install umbraco v3.0.x into a virtual folder. This is not supported.

If you need to run multiple web sites on Windows XP, consider using XP Pro IIS Admin, which can be downloaded from http://jetstat.com/iisadmin/.

1. Click Start, click Control Panel.
2. Click Performance and Maintenance.
3. Click Administrative Tools.
4. Double-click Internet Information Services.
5. Expand the (local computer) folder, expand the Web Sites folder, and click on Default Web Site.

Note: if you extracted the umbraco files to a folder other than C:\Inetpub\wwwroot, you will need to change the default web site directory within IIS, or with the XP Pro IIS Admin tool mentioned above.

6. Right-click on Default Web Site, click on Properties.
7. On the ASP.NET tab, select ASP.NET version of 2.0.xxxxx.
8. Click OK.

Set file permissions

Using My Computer or the Windows Explorer, navigate to the folder containing the umbraco web site files.Note: C:\Inetpub\wwwroot, according to these instructions.

1. Hold down the CTRL key, and click the following folders and file to select them: bin config css data media python scripts umbraco usercontrols xslt web.config
2. Right-click on any of the selected folders, click Properties.
3. On the Security tab, click Add.
4. Click Locations.
5. Select the local machine
6. Type ASPNET into the “Enter the object names to select” text box.
7. Click Check Names.Note: the text field should change to prefix the local machine name to ASPNET, and underline the name, indicating the local ASPNET account has been found and validated.
8. Click OK.
9. On the Security tab, click the ASPNET Machine Account.
10. Place a check mark in the box next to Full Control, in the Allow column.
11. Click OK.

Configure umbraco 3.0.x

You will need to edit the web.config file to specify the location and connection string information for your database.

1. Using My Computer or the Windows Explorer, navigate to the folder containing the umbraco web site files.Note: C:\Inetpub\wwwroot, according to these instructions.

2. Double-click the Web.config file.
3. If prompted, select the radio button next to “Select the program from a list”, click OK, click Notepad, place a check mark in the box next to “Always use the selected program to open this kind of file”, and click OK.
4. Near the bottom of the file, find the following line:

5. Modify the following umbracoDbDSN items to match your database configuration.Note: according to these instructions, the values would be as follows, though your settings will likely be different: Server=127.0.0.1 Database=umbracoCMS User ID=umbracoUser Password=denmark Trusted_Connection=False
6. Save the Web.config file.

Set up umbraco from a web browser

1. Using a web browser, navigate to http://localhost.
2. Click Next.
3. Click Next.
4. Click Install.
5. Click Next. Note: If there are any permission problems, return to Set File Permissions, above.
6. Click Next.
7. Enter a password for the umbraco user interface, and click Change Password.
8. Click Next.

Finalize umbraco configuration

Finally, delete the \install folderNote: C:\Inetpub\wwwroot\install, according to these instructions.

Congratulations!

You are now ready to start creating an umbraco website!
As you have experienced, installing all the pre-requisite software (.NET 2.0, IIS, SQL Server, and various supporting tools) can be a time-consuming task. In a production environment, your IT staff or ISP would have performed most of these steps for you. Installing umbraco for use with existing servers is much quicker.
From now on everything you need to do with umbraco can be done entirely through the web interface.

Please note that if you now browse to http://localhost/, you will see an alert page because, "your website doesn't contain any published content yet."

Log in to the umbraco interface

1. Using Internet Explorer (6.0 or higher), navigate to http://localhost/umbraco.
2. The username is admin.
3. The password is that which you entered when you set up umbraco from your web browser, above.
4. Once you have logged in, you will see the full umbraco interface.

You may wish to follow the links to Browse Starter Kits, above, to install a sample site using the WebSiteWizard or Blog package (more packages are being developed).
Or, if you will be attending umbraco training, leave the site empty until the course begins.

Install Umbraco on Window XP

Install Umbraco on Window XP

These instructions will show every step in detail, for those who are unfamiliar with Windows system administration tasks.However, you will need to install and configure a number of pre-requisite software packages on your Windows XP computer that would normally be running on servers maintained by your IT department or ISP.Umbraco is a very simple application to install.If you have already installed some software packages you may skip those steps, though we recommend you review the settings to confirm your configuration.

These extra steps might seem daunting. Don't worry.

Recommended hardware
· 1 GHz or faster processor
· 512 MB or more memory
· 2 GB or more available disk space
· SVGA (1024 x 768) or higher monitor resolution
· Internet Explorer 6 or higher

Note: You will need your Windows XP Professional CD

1. Install Microsoft's web server, Internet Information Server 5.1 (IIS) from the Windows XP Pro installation CD.

Place the Windows XP Professional CD-ROM in your CD Drive.

Once IIS is installed on your machine you can view your home page in a web browser by typing http://localhost into the address bar of your web browser. Since you have not yet created a web site you should see the default start page and the IIS documentation.

You will configure IIS in a few moments, after installing a few other software packages.

2. Install .NET 2.0 Framework

Note: Umbraco 3.x requires .NET 2.0.
You can download the .NET 2.0 Framework from the Microsoft web site at:http://www.microsoft.com/downloads/details.aspx?familyid=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=en

3. Install ASP.NET AJAX 1.0

Download ASP.NET AJAX 1.0 from the Microsoft web site at:http://www.microsoft.com/downloads/details.aspx?FamilyID=ca9d90fa-e8c9-42e3-aa19-08e2c027f5d6&displaylang=en

4. Install MSXML

Note: The Microsoft Core XML Services (MSXML) are a pre-requisite for SQL Server Management Studio Express, which will be installed in a moment. You can download the Microsoft Core XML Services (MSXML) 6.0 from the Microsoft web site at:http://www.microsoft.com/downloads/details.aspx?familyid=993c0bcf-3bcf-4009-be21-27e85e1857b1&displaylang=en

5. Install SQL Server 2005 Express Edition SP2

Microsoft SQL Server 2005 Express Edition is the free, easy-to-use, lightweight version of SQL Server 2005. SQL Server Express can be seamlessly upgraded to more sophisticated versions of SQL Server.
You can download Microsoft SQL Server 2005 Express Edition SP2 from the Microsoft web site at:http://go.microsoft.com/fwlink/?LinkId=65212

6. Install SQL Server Management Studio Express

SQL Server 2005 Management Studio Express Edition (SSMSE) provides a robust set of graphical tools for working with Microsoft SQL Server Express Edition.
You can download Microsoft SQL Server 2005 Management Studio Express from the Microsoft web site at:http://go.microsoft.com/fwlink/?LinkId=65110

7. Configure SQL Server 2005 Express

There are many steps here, so take your time and be sure you perform each step. Various problems can occur if you don't have SQL Server configured properly.

SQL Server 2005 Configuration Manager

1. Click Start, click All Programs, click Microsoft SQL Server 2005, click Configuration Tools, and click SQL Server Configuration Manager.

2. Expand the SQL Server 2005 Network Configuration folder, click on Protocols for MSSQLSEVER.
3. Right-click on the TCP/IP protocol, and select Properties.
4. On the Protocol tab, select Yes for Enabled.
5. On the IP Addresses tab, select Yes for both Active and Enabled for all IP Address entries.
6. Click OK.
7. Click OK.
8. Select the SQL Server 2005 Services folder
9. Right-click SQL Server (MSSQLSERVER), and click Restart.
10. Exit SQL Server Configuration Manager.

SQL Server 2005 Surface Area Configuration

1. Click Start, click All Programs, click Microsoft SQL Server 2005, click Configuration Tools, and click SQL Server Surface Area.
2. Click Surface Area Configuration for Services and Connections.
3. Expand the MSSQLSERVER folder, expand the Database Engine folder, and click on Remote Connections.
4. Select the radio button next to "Local and remote connections".
5. Select the radio button next to "Using TCP/IP only".
6. Click OK.
7. Exit SQL Server 2005 Surface Area Configuration.
8. Restart SQL Server using the SQL Server Configuration Manager.
9. Exit SQL Server Configuration Manager.

SQL Server Management Studio Express

1. Click Start, click All Programs, click Microsoft SQL Server 2005, and click SQL Server Management Studio Express.
2. Select SQL Server Authentication, enter sa for the login, and type the password you specified when you installed SQL Server 2005 Express, above.
3. Click Connect.
4. Right-click on the Databases folder, and select New Database.
5. Enter a Database name.(we'll use 'umbracoCMS' in these instructions)
6. Leave the Owner as .
7. Click OK.
8. Expand the Security folder.
9. Right-click on the Logins folder, and select New Login.
10. Select the General page:
11. Enter a Login name.(we'll use 'umbracoUser' in these instructions)
12. Select the radio button next to "SQL Server authentication", and enter and confirm a Password.
13. Remove the check mark in the box next to "Enforce password policy".(note: this is optional and should not be done in a production environment)
14. Select the User Mapping page:
14.1 Place a check mark in the box next to the Database you created.('umbracoCMS' in these instructions)
14.2 Place a check mark in the boxes next to the following Database role memberships: db_datareader db_datawriter db_owner public
15. Click OK.
16. Right-click on the root server folder (the parent of Databases, Security, etc.), and select Properties.
17. Select the radio button next to "SQL Server and Windows Authentication mode".
18. Click OK.
19. Right-click on the root server folder (the parent of Databases, Security, etc.), and select Restart.
20. Click Yes.

Test the configuration by disconnecting and logging in as the user you just created.

1. Click File, click Disconnect Object Explorer.
2. Click File, click Connect Object Explorer.
3. Select SQL Server Authentication, enter the name of the login user you create ('umbracoUser' in these instructions), and type the password you specified when you created the login user, above..
4. Click Connect.

Install umbraco Files

You can download umbraco from the umbraco web site at:http://www.umbraco.org/download

When downloading has finished, double-click the zip file on your desktop.
Extract all files and folders to C:\Inetpub\wwwrootNote: it is vital that you keep the file and folder structure intact!

If you already have web site content in C:\Inetpub\wwwroot, create a new folder and extract the files and folders into the new location (such as, C:\Inetpub\umbraco).

Do not attempt to install umbraco into a virtual folder. This is not supported.

About Umbraco

umbraco is an open source project with roots back to year 2000 even though it wasn't released as open source until 2004. Prior to that it was founder Niels Hartvig's home-grown weapon of choise for working as a freelancer.

umbraco was founded and is owned by Niels Hartvig, but is made possible by loads of individuals helping out and the core team who's doing the development. http://www.090978.org/

MVPs 2008/2009 (Most Valued Persons):
· Casey Neehouse
· Warren Buckley
· Douglas Robar
· Morten Bock
· Tim Geyssens
· Paul Sterling

· Dirk De Grave