Umbraco 2.1The friendly cms

A user guideKasper Bumbech Andersen

12/2005

1

Table of ContentsUmbraco 2.1............................................................................................................................ 11 Introduction....................................................................................................................... 4

1.1 Professional support and help ............................................................................... 41.2 Logging on to the Umbraco admin console......................................................... 41.3 Umbraco console interface...................................................................................... 41.4 General navigation and interaction with nodes in the treeview......................... 51.5 Interaction feedback................................................................................................. 61.6 Navigating the different sections............................................................................ 61.7 Umbraco sections..................................................................................................... 6

2 Managing web documents................................................................................................ 82.1 Creating a new document/page:............................................................................. 82.2 Edit a document/page............................................................................................. 92.3 The Webpage/Document Toolbar:..................................................................... 102.4 Common dataeditors.............................................................................................. 12

2.4.1 The single line textbox.................................................................................... 122.4.2 The Multiple line textbox............................................................................... 122.4.3 The numeric field............................................................................................ 122.4.4 The upload field............................................................................................... 122.4.5 Content picker................................................................................................. 132.4.6 The media picker............................................................................................. 142.4.7 Approved color................................................................................................ 142.4.8 Checkboxlist..................................................................................................... 142.4.9 Radiobuttonlist................................................................................................. 152.4.10 Dropdownlist................................................................................................. 152.4.11 Multiple selectbox......................................................................................... 152.4.12 Date picker..................................................................................................... 152.4.13 The date picker /w time............................................................................... 152.4.14 The WYSIWYG dataeditor.......................................................................... 16

Wysiwyg icons / actions performed when clicking the icons in the toolbar................................................................................................................................. 17

2.5 More on:................................................................................................................... 263 Layout, Content definitions and dictionary. ............................................................... 28

3.1 Stylesheets................................................................................................................ 283.1.1 Create a new stylesheet:.................................................................................. 283.1.2 Applying custom styles in the Wysiwyg editor............................................ 30

How does it work?............................................................................................. 30 Stylesheet class'es or html element marking................................................... 30

Stylesheet class'es............................................................................................. 30HTML element marking................................................................................. 30When to use html markup and when to use stylesheet class'es:............... 30

3.1.3 Create a heading using custom stylesheet properties................................. 313.1.4 ............................................................................................................................ 323.1.5 Change the background of a selection.......................................................... 35

2

3.2 Templates................................................................................................................. 383.2.1 Create a template:............................................................................................ 383.2.2 Template section user interface..................................................................... 39

Toolbar................................................................................................................. 393.2.3 Master templates.............................................................................................. 393.2.4 Template contents........................................................................................... 403.2.5 The “Hello world” example........................................................................... 403.2.6 Insert fields from the document in the template........................................ 43

3.3 Documenttype definitions..................................................................................... 483.3.1 Creating a “Textpage” documenttype.......................................................... 48

“Info” panel ....................................................................................................... 49 “Structure” panel ............................................................................................... 49 “Generic properties” tab................................................................................... 49 “Tabs” panel ...................................................................................................... 49

3.3.2 Creating the document................................................................................... 523.4 Dictionary................................................................................................................ 55

3.4.1 Create a dictionary item:................................................................................. 553.4.2 Insert the dictionary item in a template........................................................ 573.4.3 Testing the output........................................................................................... 58

3.5 Mediatypes............................................................................................................... 623.6 Languages................................................................................................................. 62

4 Datatypes, Macros and xsl transformations................................................................ 694.1 Creating dynamic components............................................................................. 69

4.1.1 The macro concept.......................................................................................... 694.2 Umbraco runtime data........................................................................................... 69

5 Performace....................................................................................................................... 706 Appendix A...................................................................................................................... 70

6.1 Configuration files.................................................................................................. 706.1.1 Web.config....................................................................................................... 70

Paths..................................................................................................................... 706.1.2 Fonts for graphic headlines............................................................................ 71

3

1 Introduction

Umbraco - is a web content management platform, that allows you to manage the content and presentation of your website. This user’s guide will show you how to create content and files, how to manage users, and their permissions and how to define new documenttypes, templates, macros (dynamic content) and how the different concepts mentioned interacts.

1.1 Professional support and help The umbraco team are available for professional support. Advise on how to get help from the Umbraco team visit http://www.umbraco.org for contact information and pricing.

1.2 Logging on to the Umbraco admin console.Before using umbraco, you need to log on to the system, the default user account (in a blank/new umbraco installation) are "umbraco” with the password "default” (which resembles the "Administrator” account on MS Windows or the "root” on *nix platform)

The umbraco console is usually accessible at http://www.yourwebsite.com/umbraco (replace www.yourwebsite.com with the Url of your website.)

1.3 Umbraco console interfaceThe interface of umbraco is divided in 4 different parts

The topbar, from which you can perform a search in created documents/webpages of your website, create new documents, access the online help system, and logout of umbraco.

The treeview, where you can navigate the data stored within umbraco

The sections an overview over the available sections/modules to the current user.

The dashboard - the selected sections "frontpage” – it can be empty as it is in the following figure or it could have different dashboard widgets, giving an overview of the section and providing simple shortcuts and help to perform various tasks. Navigating in the treeview changes this view from dashboard to the selected view.

4

1.4 General navigation and interaction with nodes in the treeview

The contents of umbraco is accessible through the sections treeview, this works alike the explorer in MS Windows, a left click on the "+” sign expands a node and a leftclick on the "-" closes the node.

Leftclicking the node itself (on the icon or the text) navigates to the default view of the node (which most often is "edit view”)

Right clicking the node itself pops up a context menu with the actions you can perform on the node. (Most common actions are "Create, delete, reload”)

5

Context menu from a document.

1.5 Interaction feedbackWhen an action has been performed, umbraco notifies the user using a "speech bubble” in the lower right corner, with text and an icon representing the action performed.

1.6 Navigating the different sectionsThe icons of the "Sections” area each represent a logic module (or a module collection) of umbraco, note that its possible configure the access to sections of umbraco by user (this can be configured in the "Users” section)

A leftclick on either of the section icons navigates the treeview to the selected section tree and the dashboard to the sections dashboard – the items of the topbar is context sensitive and may therefore react different in different sections.

1.7 Umbraco sectionsThe "Content” section (default section) represents the documents and structure of your website, the documents are equvalent to the webpages of your website.

The "Medias” section where its possible to maintain media files associated to the content of your website - structured in folders. This section is used for handling images and pdf/doc/txt files – which is being linked up or inserted as graphics from within the pages of your website.

6

The "Users” section is handles the administrative users, which should have access to the umbraco console.

The "Settings” section is a placeholder for several modules, which are related to layout, definition of content types and the built in dictionary.Modules: Stylesheet, Templates, Documenttypes, Mediatypes, Dictionary.

The "Developer” section is a placeholder for several modules related to development of dynamic content.Modules: Macros, Datatypes, Xsl and a simple Cache browser.

The "Member” section handles registered members of you website.

7

2 Managing web documentsSection: Content

Applies to: All.

This section describes the handling of documents in umbraco, most often a document is equevalent to a webpage.

All documents in umbraco has a documenttype that defines the data and layout of the document - in addition the document has a basic set of properties which are related to the websites structure.

A published document always has an Url, which resemble the location of the document in the hierachy, information regarding publishstatus – publishdate, last modification date and an option to override the default template (layout) of the document, the creator of the document, and the last person who edited the document.

It's possible to define a daterange in which a document should be published.

2.1 Creating a new document/page:In the “Content” sections tree – rightclick the node under which you wish to create a new document and select the “Create” item in the context menu.

A “New document” dialog appears, select the type of the new document from the list and type the name of the document in the textbox and click “Create”

Create document/page dialog

The content tree reloads and the new document appears in the structure.

8

2.2 Edit a document/page

In the content tree leftclick the document you wish to edit.

All documents in umbraco has a document type, the documenttype defines which tabs and fields are on the document, all documents has a “properties” page, we start by navigating to the “properties page” by leftclicking the tab labelled “Properties”.

The properties page of a webpage/document.

Editing the “Name” property, changes the name of the document, this also affects the document url. The document node in the content tree is labelled with its name.

The document contains information on creator, last modified date, last published date, and a link to the document (if it’s been published).

Save your changes to the document by clicking the “disk” icon to the left in the tool

9

bar

Note:

All other data on the document is generic and can be defined by editing the documenttype of the document, here you can add/edit/remove datafields and tabs of the document – I.e. You can see a document/webpage as the collection of generic data sorted out in different logic groups on tabs (as defined by its documenttype) + the standard properties of a document which are

Name, Creator, Createdate, Updatedate, Publishdate, Template and the Url of the webpage (the webpage is the output produced by the runtime given a document and a template)

All datafields has an editor associated, for editing the data of the datafield, each “datafield editor” has it’s own characteristics, the most common are the

“Textbox editor” a simple textbox for input like the “name” textbox in

“Wysiwyg editor” (WhatYouSeeIsWhatYouGet) resembles the function of word or another text processing application, to easily add and edit formatted/rich text on your webpages.

“Number editor” a textbox editor which only accepts numeric values.

More sophisticated dataeditors as the colorpicker, checkboxlist, radiobuttonlist, dropdownlist and pagepicker are also available in the default distribution.

Some of the “datafield editors” adds extra icons in the toolbar for use when editing the data – these will be described when describing the “datafieldeditor”

2.3 The Webpage/Document Toolbar:

All tabs in the webpage/document edit view have at least 3 icons.

The save icon, clicking this icon saves the changes made to the document/webpage.

10

The save and publish icon, which saves the changes made to the document/webpage and then publishes the document/webpage, which makes the changes visible to the public in your website.

The preview icon – clicking this icon will open a new browser window, displaying the current webpage/document, as it would look like if the changes made are published, primarily used for checking formatting and reading the different data parts in the public websites context.

11

2.4 Common dataeditors

2.4.1 The single line textboxA simple textbox for inputting a single line of text, most dataeditors (as the textbox) has a label with the name of the field positioned to the left of the dataeditor.

2.4.2 The Multiple line textboxAs with the single line textbox, additional this textbox allows multiple lines of inputtext.

2.4.3 The numeric fieldThis dataeditor resembles the textbox, but allows only numeric values.

2.4.4 The upload fieldFile upload dataeditor, allows selecting a file on your local machine for upload when the webpage/document is saved. This dataeditor has different states and views based on the if a file has been uploaded and which type of file it contains.

Empty upload field.

12

Upload field with text file

It is possible to delete the uploaded file and reset the upload field by checking the “Remove file” checkbox and save the webpage/document, clicking the url of the file will open the file in a new window.

Upload field with image

If the uploaded file is an image, a thumbnail is automatically generated at upload and this will be displayed above the upload field.

2.4.5 Content pickerThe content picker is used primarily to relate one document to another – by clicking the “Choose..” link, the webpage/document browser dialog appears the one selected sets the value.

Clicking the “Choose..” brings up the picker dialog

13

The content picker dataeditor reflects the selected document

2.4.6 The media pickerAs with the content picker – but instead picks medias

Clicking the "choose" brings up the pick media dialog page

after picking the media – the mediapicker is updated with the selected media

As with the content picker – it’s used to relate a document/webpage to a media in other ways than inserting them in the Wysiwyg editor

2.4.7 Approved colorThe “Approved color” dataeditor allows for a designer to define a color scheme, which can be selected by the editor – usually the choice defines the background color of one or more elements on the specific webpage/document.

Clicking on one of the colors to the right changes the value

2.4.8 CheckboxlistThe checkboxlist dataeditor – enables multiple selection in a predefined list

14

2.4.9 RadiobuttonlistThe radio button list dataeditor enables single value selection in a predefined list

2.4.10 DropdownlistThe dropdownlist dataeditor – enables single value selection in a predefined list

2.4.11 Multiple selectboxEnables multiple selection in a predefined list

2.4.12 Date pickerThe date picker dataedit or allows simple input of date data.

2.4.13 The date picker /w timeAs the date picker now with time

15

2.4.14 The WYSIWYG dataeditorUsed for inputting rich text, outputs html, an excellent way of easy formatting of text – in order to publish it on the web.

Wysywyg Editor with simple formatting

The WYSIWYG/Richtext dataeditor, adds a number of icons to the toolbar, most of these icons represent formatting options used when editing and setting up the text for your webpages.

Depending on the screen resolution of your monitor, some of the icons might be “hidden”, you can “scroll” to see all icons in the toolbar by placing the cursor over the tiny arrows to the leftmost and rightmost (scrolling the contents of the toolbar left or right).

16

Wysiwyg icons / actions performed when clicking the icons in the toolbar

“Edit html” – opens a simple HTML editor, allowing to view the html source of the Wysiwygeditor.

“Choose style”, applies the selected “style” to the selected/highlighted text in the Wysiwyg editor – the values of the dropdownlist is defined in the “/settings/stylesheet” section, read more here (link up).

“Show styles” displays a little “styleicon” around elements in the Wysiwyg editor where a style has been applied.

“Bold” bolds the highlighted text.

“Italic” applies Italic to the highlighted text

“Graphic headline”, opens a “Graphic headline” dialog page

17

Which based on the input text, selected font, font size, text colour and background colour, inserts an graphic headline (auto generated image) in the Wysiwygeditor, this is very convenient if you need to use for an example a corporate font which most likely are not installed on the client computer used by the visitor, in order to stay within design guidelines.

Add, Edit, Remove fonts, sizes and colors see section ..

“Align left” – left aligns the highlighted element.

“Center” – center the highlighted element.

“Right align” – right aligns the highlighted text.

“Unordered list” – starts an unordered list.

”Ordered list” – inserts an ordered list.

“Decrease indent” –decreases indent on the selected element (right to left)

“Increase indent” – increases indent on the selected element (left to right)

“Insert hyperlink” Opens an “Insert hyperlink” dialog

18

You can select a webpage/document from your website or you can type an external Url, checking the “Open in new window” checkbox, will set the target of the hyperlink to a new browser window. If you wish to link up an internal media – click the “medias” tab and select the media you wish to link up – click “Ok” to apply the link to the highlighted text in the Wysiwyg editor.

Note you need to have a selection highlighted in the Wysiwyg editor in order to see the dialog.

“Anchor link” opens a “Insert anchor link” dialog

Type the name of the anchor and click “insert”, an anchor link with the attribute

19

Name=”[typed value]” will be set on the link.

“Insert image” opens a dialog page “Insert image” which allows you to select any media from the media library of umbraco.

If the media does not exist within the media library, you can create a new media by shifting to the “Create new” tab.

Type the name of the new media, select the file associated to the media, select the

20

target folder in the media library and click the “save” button, the file uploads and is inserted in the Wysiwyg editor.

“Insert macro”

This is one of the most powerful features of umbraco; a macro represents dynamic content, this could be an auto generated list based on documents in umbraco, an mail form, a login form, advanced or simple navigation etc. pretty much anything, which relies on more than just simple text 1:1 text output.

It’s possible to pass parameters from and to a macro, with an auto generated UI much like the generic data properties of a document and their data editors.

Given the wide frames for macro voodoo, it’s difficult to give a fulfilling example; in the following I show how to insert a macro, which lists the child webpages of a given node in a unordered list, where the “parent node” is passed to the macro as a parameter.

Here’s the document/webpage structure used in this example:

Start by clicking the “Insert Macro” icon – the “Insert macro” dialog appears

21

Select the macro “List children” in the dropdownlist and click “Ok”, then the “Input macro parameters” dialog appears

The “Choose item” link is clicked and a webpage/document browser dialog appears

The “Frontpage” webpage/document is selected, as the source/parent node

The “Input macro parameters” dialog updates with the “Frontpage” node, then click "Ok"

The wysisyg editor updates the view and now contains the macro output (you can distinguish the macro content from regular Wysiwyg content by the dotted orange frame)

22

The output from the macro is not saved as html, but as a placeholder for that macro with the given parameters, this means that any new webpages created underneath the “Frontpage” node will automatic appear in the macro generated list.

Since the macro content is a placeholder, it's not possible to edit the contents of the list, but instead its possible to rightclick the list and a via a contextmenu open the edit macro dialog, the dialog will display upon doubleclick too.

23

Click “Edit macro” and the “Input macro parameters” dialog appears again with the source set to “Frontpage”

It's now possible to select another sourcenoce – ex. “Sub page 1”, click “Ok” and the Wysiwyg editor updates

As you can see the macro now outputs the children of “Sub page 1”, again its important to notice that this content even though it appears static, in fact is dynamic and will resemble the actual list I.e. The changes made to “Subpage 1” and the collection of child webpages/documents.

“Insert table”

Opens the “Insert table” dialog, in this you can configure the number of rows and

24

columns of your table, adjust alignment set border width and so forth

A table with 3 columns and 4 rows, with a width of 90%.

In the WYSIWYG editor, the table is outlined with dotted lines, this is for easy editing, the borders itself will not be shown on the final webpage (unless you have

25

chosen, in the “Insert table” dialog, to have a border > 0), you can select any of the table cells and edit the contents, you can insert images, macros headers and so forth.

Rightclick the table to get a context menu, this enables you to align the text within the cells, insert new rows and columns, remove rows and columns, split the cell where the cursor is places, collect the selected cell with the cell to the right, and edit the selected cells properties

Table context menu.

Edit table cell properties.

2.5 More on:

Sort

Move

Copy

26

Versions

Recursive publish

27

3 Layout, Content definitions and dictionary. Section: SettingsApplies to: Administrators, developers.Modules: Stylesheet, Templates, Languages, Mediatypes, Documenttypes, Dictionary.

3.1 StylesheetsApplies to: Webdevelopers

Handling your CSS within umbraco, brings a few advantages over the “edit / ftp” way, first it will allow you to stay within one application during the development (not switching from one view to another), and secondly – enables you to specify style properties and HTML tags (like the <h1></h1>, <em></em> and so forth) to be used by the editors within the Wysiwyg editor.

3.1.1 Create a new stylesheet:Rightclick the Settings/Stylesheet folder and select the “Create” menu option.

The “Create stylesheet” dialog appears

28

Type the name of the stylesheet and click the “Create” button, the tree refreshes and leftclicking the new “screen” node opens the edit view of the stylesheet.

The toolbar only contains the “save” button (disc icon), which when pressed saves the stylesheet to the server.

Changing the name, changes the name of the physical file on the server, as well as the label of the node in the tree.

The “Styles” editor contains the contents of the file.Delete the stylesheet by rightclick the node in the tree and select the “Delete” menu option.

29

3.1.2 Applying custom styles in the Wysiwyg editorThis is where the stylesheet of umbraco differ from a regular stylesheet, its possible make definitions of styles, which can be applied to selections in the Wysiwygeditor.

How does it work?The easiest way to explain how this works is first to describe how it works and then to show some of the things that are behind the scenes:

Stylesheet class'es or html element marking.

Stylesheet class'es1: you can either define a class, then a span tag with the class attribute set to the defined class i.e.:

HTML output<span class=”[classname]”>[selection]</span>

HTML element markingYou can define an HTML element, which will be inserted around your text i.e.HTML output<[tagname]>[selection]</[tagname]>

When to use html markup and when to use stylesheet class'es:Which scheme to choose depends on what the custom style does, the html element based scheme enables semantics – even though a Wysiwyg editor generates the code.

An example is a heading – in this case you would most likely define the heading like an

<h1>[selection]</h1> (or <h2>[selection]</h2>, <h3>[selection]</h3> ….)

Another example is when you want to enable the enduser to mark up text in the Wysiwyg editor as code i.e:

30

<pre>[selection]</pre>

If the style applied does not have any semantic meaning, and solely is for a nice UI, which occurs in some scenarios, then you should use the class-based scheme.(if you are not quite sure what semantic html means, or why it’s important to use it, try asking Google).

3.1.3 Create a heading using custom stylesheet propertiesThe target is to create a heading which puts “<h1>” tags around the selected text in the Wysiwyg editor (selected text = selection) and define what style the h1 should have.

Right click the stylesheet node in the tree (in this case the “screen” stylesheet), and click the “Create menu option

The “Create” dialog appears.

Type “Heading 1” as title and click “Create” – the tree reloads and the “Heading 1” node appears underneath your stylesheet.

Left click the “Heading 1” node to edit it.

31

3.1.4

Type “H1” in the “Alias field, and

font-size:160%;font-weight:bold;

in the editor textarea. then click the “Disk” icon to save the changes.

32

The page updates and the text in the bottom displays an example of the style applied.

Now switch to the “Content” section and select a webpage with a Wysiwyg editor.

(the example page is filled with text most often refered to as “Lorem ipsum” text – if you are in need of “Lorem Ipsum” like text go to http://ungreek.toolbot.com, and get it for free ;))

33

The first line of text is selected.

Select the “Heading 1” option from the “Choose style” dropdown list, which we just defined as a stylesheet property.

34

And the heading is now visible

A quick look at the source of the document reveals that the “<h1></h1>” is inserted around the selected text as expected.

3.1.5 Change the background of a selection.Create a new stylesheet property called “Blue background” (see previous section)

Type “.bluebackground” in the Alias field, and

35

background:blue;

In the editor (textarea) field.

When applied in the Wysiwyg editor, it displays the selection with a blue background, just as in the example text.

36

A quick look at the source of the document reveals that a “<span class=”bluebackground”></span>” is inserted around the selected text as expected.

37

3.2 TemplatesApplies to: Webdevelopers

Templates in Umbraco defines the general layout of the public website, the template combined with a document, outputs a webpage – by ensuring that content and presentation is separated in different layers of the application, it’s guaranteed that you can change one layer without compromising the other.

Umbraco itself does not generate any html, the webpages of the public website, are 100% generated from the html in the templates and data from the documents (for some webpages, a subset of the html comes from macros – more on that subject later).

This means that the web developer is 100% in charge of what kind of the HTML output that is served when a user visits the website.

3.2.1 Create a template:

In the “Settings” section rightclick the “Template” node and select the “Create” menu option and the “Create template” dialog appear.

Type in the title of the template, in this example the title is “Textpage”, leftclick the new node “Textpage” in the treeview, in order to go to the edit view of the template.

38

3.2.2 Template section user interface ToolbarThe toolbar of the edit view of templates contains 4 icons

The first is the “Disk” icon, which is used through out umbraco for saving data.

The second is the “Insert pagefield” icon, which I will come back to later.

The third is the “Insert macro” icon, which also appears in the “Wysiwyg dataeditor” toolbar – to read more on what the “Insert Macro” does go to the “Content” section documentation.

The fourth is the “Help” icon; this pop ups a tiny reference page (in Danish only), which will be removed in the umbraco 2.2 distribution.

3.2.3 Master templates

39

Templates in Umbraco have the ability to inherit from another template, thereby enabling reuse of general layouts, more on how to use master templates later.

3.2.4 Template contentsThis is the editor, in which you should type the HTML of the template.

3.2.5 The “Hello world” exampleIn the “Textpage” template created earlier, input:

<html><head><title>Hello world example</title></head><body>

<h1>Hello world</h1></body></html>If you have previous experience with HTML, you should know what this outputs

In order to test it, go to the “Settings/Documenttype” and create a new document type named “Textpage” (if it does not exists already)

Leftclick the “Settings/Documenttype/Textpage” node to go to the edit view of the documenttype.

In the “Allowed templates” checkbox list, enable the “Textpage” template.

Then go to the “Content section” and create a document of the type “Textpage”

40

Click the “Create” button and the document appears in the tree – left click the document and go to the “Properties” Tab.

In the template dropdown list select the “Textpage” template then click the “Save and publish” button.

41

In the “Link to document” pane of the properties tab of the “Textpage test” document is now a url to the webpage which is the output of the document and the template combined – leftclick the link (in my case – “/presentation/testpagetest.aspx”), a new browser opens and the output should look something like this:

42

3.2.6 Insert fields from the document in the template

You can insert datafields from documents in templates – by placing placeholders in your HTML.

This example assumes that you have at documenttype named “Textpage”

The “Textpage” documenttype should have following specifications:

A tab named “Page content” - this tab has a “Rich text editor” data property with an alias = “bodyText”

43

Allow the “Textpage” documenttype the “Textpage” template.

And go back to the edit view of the “Textpage” template

44

Position the cursor in the html template editor, where you want to insert the data,

then leftclick the “Insert pagefield” icon from the toolbar, and the “Insert pagefield” dialog appears.

In the “Choose field” dropdownlist select the “bodyText” datafield and click the

45

“Insert” button in the bottom of the dialog

Your templates HTML updates and a <?UMBRACO_GETITEM field="bodyText"/> is inserted where the cursor were positioned (for more information on the “<?UMBRACO_GETITEM .. /> tag, go to the appendix a)

Save the template by clicking the “Disk” icon, and go to the “Content” section.

Create a document with the documenttype “Textpage”, and leftclick the node

46

Type in some “Mumbo jumbo” text in the Wysiwyg editor, and click save and publish.

Then go to the webpage and observe the output (the link is in the “Properties” tab)

47

3.3 Documenttype definitionsApplies to: Administrators, developers.

A documenttype defines the datafields/properties of documents; it works much as defining tables in a database, where the datafields are the columns of the table, it differs though, as data in umbraco is hierarchal instead of a tabular nature.

It’s possible to choose an underlying datatype definition on each datafield. Umbraco comes preinstalled with a range of different datatype definitions, each with it’s own dataeditor; the dataeditors are described in the “Content” section, the datatype definitions in the “Developer” section.

Given the generic datastructure, you can resemble almost any type of content, which is a great strength over predefined documenttypes.

A documenttype defines the types of child documents can be created as well as which templates can be applied to documents of the type.

Note: most data in umbraco set up using this “content/contenttype” model this includes “medias/mediatypes” and “member/membertypes”.

3.3.1 Creating a “Textpage” documenttype.In this example we create a simple documenttype, with two tabs (content, metadata) and two datafields - a rich text datafield “bodyText” and a multiple line textbox “resume”. (it’s assumed that you have a “Textpage” template defined.)

Rightclick the “Documenttypes” node and select the “Create” menu option:

Type the “Textpage” in the Title field and click “Create”, the tree refreshes and a new “Textpage” node appears underneath the “Documenttypes” node.

48

Leftclick the “Textpage” node to go to the “Edit mode” of the documenttype, this view is separated in 4 different tabs/sections:

“Info””Structure””Generic properties”“Tabs”.

“Info” panel Enables you to edit the name, alias, icon (the image representation of the node in the content tree) as well as which templates is usable on documents of that type, besides defining a set of allowed templates, it’s possible to set a “default” template, which will be assigned when creating the document.

“Structure” panel Enables you to select what type of documents can be created underneath documents of the type (select more documenttypes by ctrl clicking items the select box)

“Generic properties” tabThis is where you add, edit and remove datafields of the documenttype, as mentioned before the datafields can be assigned to different tabs, but one tab always exists – the “General properties” tab, which besides the generic datafields associated also contains the general data of a document, i.e. the template selector, url, create data, last modified date etc.

“Tabs” panel Is used for defining tabs on the document in “edit view”, this enables you to logically group datafields.

On the “Info” panel select the “doc” icon in the dropdownlist, and enable the “Textpage” template in the list of available templates

49

Click the “Disk icon” to save the changes, and you are now able to select the “Textpage” template in the “Default template” dropdownlist (do so).

In the structure panel, enable the “Textpage” option in the “Allowed child nodetypes” multiple selectbox.

Navigate to the “Tabs” tab and create a tab named “Contents” and one named “Resume”

50

In the “Generic properties” tab – create a new property named “bodyText” with an alias “bodyText”, select the “Richtext editor” in the type dropdownlist and place it on the “Contents” tab.

Click the save icon and the property is shown underneath the “Contents” tab.

51

Then create a new property named “Resume”, with an alias “resume”, select the “Textbox multiple” in the “Type” dropdownlist and place it on the “Resume” tab.

Click the save icon and you are done configuring the documenttype.(you can decide to make you datafield mandatory and/or add an regular expression to validate input)

3.3.2 Creating the document.Go to the “Content” section and rightclick the “Content” node – select the “Create” menuoption:

52

The “Create page” dialog appears and the “Textpage” document type is selectable in the “Choose document type” dropdownlist.

Type a title for your document and click the “Create button”

The content tree reloads and the node appears underneath the “Content” node (note that it’s greyed out, which indicates that the document is not yet published).

Leftcliking the new document brings up the “Edit view” of the document, which now has 3 tabs the two defined by us and the default “properties” tab, which holds the default properties of the document (as you can see on the “properties” panel - “Textpage” template is set as default).

53

54

3.4 DictionaryApplies to: developers

The built in dictionary, is repository for storing common bits and pieces of text, which are used in templates, and macros, these bits and pieces can be translated into the different languages set up in the umbraco environment. The text displayed in the webpages will correspond to the language setting of the webpage.

This applies very well for adding language dependant text pieces like email, addresses, phone numbers etc. in general templates in order not to maintain different versions of templates for each language used in umbraco.

3.4.1 Create a dictionary item:

Rightclick the “dictionary” node and select the “create” menu option:

Type the dictionary key in the title field:

55

The tree reloads and the new key appears underneath the “dictionary” node.

Leftclicking the new node, navigates to the edit view of the dictionary item

As you can see the different languages of the umbraco installation, represented by the culture iso code (here: da, en-US,en-GB, fr, de, es), is placed each on one tab.

In the Danish text I write the Danish text for “Hello world” and in the “en-GB” I write up “Hello world”

56

Save the changes by clicking the “disk” icon.

3.4.2 Insert the dictionary item in a templateSelect the template in which you wish to insert the key

place the cursor where you want to insert the key in the editor and click the “Insert umbraco pagefield” button

57

Type” #[key]” (where [key] is the key of you dictionary item) in the “Choose field” text field and click “insert”

in this case a <?UMBRACO_GETITEM field="#Testkey"/> placeholder is inserted into the html of the template and we are ready to test the output.

The contents of the template is now:<html><head><title>Testing dictionary</title></head></head><body><h1>Testing the dictionary</h1><?UMBRACO_GETITEM field="#Testkey"/></body></html>

3.4.3 Testing the output

Go to the “Content” section and create a document which uses the template used in this dictionary example.

Leftclick the node and select the “Assign domain” menu option

58

The assign domain dialog appears.

In this example, I wont wind up a real domain, but instead I just type a “bogus” domain name and select the “Danish” language in the “Language” dropdownlist.

Click the “Ok” button and the domain and language setting appears in the list of assigned domains

59

Close the dialog and navigate to the output of the document, which should look something like the below figure if you have used the sample template.

Changing the “language” context of the page

60

Go to the umbraco console again – create a new document which also uses the template with the dictionary test

Rightclick the new document and select the “Assign domain” menu option

Type in another bogus domain and select the “English (United kingdom)” language in the dropdownlist and click “Ok”

Close the window and navigate to the newly created webpage which should now displays the English version of the dictionary item:

61

3.5 MediatypesApplies to: Administrators, developers.

Mediatypes works pretty much the same way as documenttypes, you are able to define generic properties, define how to structure medias etc. information on how to handle these refer to the “Documenttype” section.

The similarity medias vs. documents are striking, the difference is that medias doesn’t have a “spoken Url” and a template and that medias in general usually represents a physically file.

Umbraco comes with 3 predefined mediatypes, “folder”, “image” and “file” mediatype, which should cover most scenarios, information on properties of these, and how you should use them can be found in the “Medias” section.

3.6 LanguagesApplies to developers, Administrators.

62

When it comes to culture specific information, such as formatting dates, currencies etc. umbraco relies on the built in culture settings of the underlying .net framework.

You can define the language of your webpage/s in the content tree (see “Content section”) by rightclickin the “Root” node of you website and select the “Assign domain” menu option – which opens the “Assign domain” dialogpage.

By assigning a “Domain” and a Language to the node (You can assign a bogus domain when testing, the culture setting will be applied either ways.)– you defines the culturesettings umbraco should use for formatting of ex. Dates. This works in a recursive way – which means that all subpages of the node will use this setting if its not overridden, by default Umbraco will use the culturesetting of the .net framework installed.

An example on how this works:

63

I have created 2 toplevel nodes, one “Frontpage (uk)” node and a “Forside (dk)” node, I want the “Frontpage (uk)” and all subpages to use the “en-UK” culture and the “Forside (dk)” to use the “da-DK” culture setting.

Leftclick the “Frontpage(UK)” node and select the “Assign domain” dialog.

64

Type in your domain and select the “English (United kingdom)” item in the dropdownlist.

Do the same for the “Forside (dk)” node, with another domain and select the “Danish” item in the dropdown list

In order to test the result, go to the “Settings/template” section (refer to the “Templates” section on how templates work), and select the template used to this pages (in this case the “Textpage” template)

65

Leftclick the “Insert umbraco pagefield” icon and select the “@createDate” in the “Choose field” dropdownlist and check the “Format as date” option.

66

The createdate field is defined on all documents.

Click “Insert”, save your template and go to the “Content section” – leftclick the “Frontpage (uk)” node and navigate to the “Properties” tab – and click the “url” – which opens the webpage with the English (United kingdoms) culture setting, the result is displayed beneath

Then navigate to the “Forside (dk)” node and do the same the result displays the same page, now with the Danish culture setting

This works for both fields inserted into the template, and also applies for the built in

67

date methods in the “umbraco.library” library, which are available as an static function extension in the xsl section of umbraco (see developer/xsl section on this subject).

68

4 Datatypes, Macros and xsl transformations.Section: DeveloperApplies to: Webdevelopers, .NET developers.

4.1 Creating dynamic componentsCreating menus, formulars and lists is a common task in the development cycle of a website:In umbraco, the developer section offers a rich development environment for creating dynamic components, which integrates throgh the macro placeholder in the content and template section.

4.1.1 The macro conceptMacroes are placeholders for either .net user/custom controls or xsl transformations.

You can define properties on a macrodefinition, through these properties its possible to send parameters to the macro and these parameters are editable when the macro is inserted either in the document or in the template. Umbraco generates the UI needed for editing the parameters and as with the documenttypes dataproperties it's possible to select a range of diffent renderings used for editing parameters.

Parameters sent to xsl transformations are added to the underlying xmldocument and are accessible using the xpath expression:

/macro/[macropropertyalias]

.Net control based macroes send parameters via public properties, Umbraco are able to scan the control for public properties and generate the list of properties on the macro – equivalent to the list of public properties of the custom/usercontrol.

Xsl transformation macroes are commonly used when displaying lists in general – most common are menus/navigation, news listings, breadcrums, weblog posts/comments etc.

.Net control macroes are used for input of text, integration to 3. party systems or accessing other datalayers, the only limitation is the .net framework.

4.2 Umbraco runtime data.Umbraco's publishing engine generates an in-memory xmldocument, where all published webdocuments data are present. These data are hieracal ordered as the

69

nodes in the content tree, and are easy to access using xpath expressions in xsl transformations.

In addition to xpaths it's possible to access published data through the modellayer of the runtime – when using .net usercontrols.

5 Performace

6 Appendix A

6.1 Configuration files

6.1.1 Web.configUmbraco stores environment details in the web.config files appsetting region and in the umbraco specific /config/umbracoSettings.xml file.<appSettings>

<add key="umbracoReservedUrls" value=",/presentation/umbracoTextGen.aspx,"/><add key="umbracoReservedPaths" value="/presentation/umbraco/"/><add key="umbracoContentXML" value="/presentation/umbraco.xml"/><add key="umbracoStorageDirectory" value="/presentation/data"/><add key="umbracoPath" value="/presentation/umbraco" /><add key="umbracoDbDSN" value="Server=[ipaddress or

dns];Database=[dbname];User ID=[userid];Password=[password];Trusted_Connection=False"/><add key="umbracoDebugMode" value="false"/><add key="umbracoDirectoryUrls" value="true"/><add key="umbracoTimeOutInMinutes" value="20"/><add key="umbracoUseDirectoryUrls" value="false"/><add key="umbracoDisableVersionCheck" value="true"/><add key="umbracoUrlForbittenCharacters" value="&quot;/.:&amp;?"/><add key="umbracoUrlSpaceCharacter" value=""/><add key="umbracoDisableXsltExtensions" value="true"/><add key="umbracoEditXhtmlMode" value="true"/><add key="umbracoDefaultUILanguage" value="en"/><add key="umbracoProfileUrl" value="profiler"/><add key="umbracoHideTopLevelNodeFromPath" value="true"/><add key="umbracoEnableStat" value="false"/><add key="umbracoSmtpServer" value="[your.smpt.com]"/>

</appSettings>

PathsUmbraco maintains a virtual pagestructure - this means that you have "userfriendly urls" like http://www.mywebsite.com/articles/howdoesitwork.aspx - even though the files does not exist physically..

But in some cases you actually have som physically “.aspx” files, which you don’t want umbraco’s httphandler to handle - therefore its possible in the “web.config” files appSettings area to exclude single files like

umbracoReservedURLS = ", /umbraco/umbracoTextGen.aspx,"

70

In some cases its nice instead of excluding a file to exclude complete folder and its subfolders like:

umbracoReservedPaths = "/umbraco"

(which means that the usual httphandler of the IIS handles all files below the /umbraco folder, you can add more if you like)

umbracoContentXML = "/umbraco.xml" is just where umbraco should store its xml to a file - you can change the filename

umbracoStorageDirectory = "/data"

is the default storage directory - for general purposes, the IIS_WPG group and the ASPNET useraccount should have read/write rights on this directory.

umbracoPath = "/umbraco"

defines the path to your umbraco installation

6.1.2 Fonts for graphic headlinesAdd, Edit, Remove fonts, sizes and colors in the Graphic headlines dialogIn order to add or remove fonts, font sizes or colours from this dialog, locate the Umbraco folder (in the servers filesystem) and navigate into

“\umbraco\config\fonts”

In this folder you will find the installed fonts (they need to be truetype) and a file named “fonts.xml”, the contents of this should look something like this<?xml version="1.0" encoding="utf-8" ?> - <fontConfig>- <fonts> <font filename="verdana">Verdana</font> <font filename="arialn">Arial narrow</font> <font filename="arial">Arial</font> <font filename="TREBUC">Trebuchet (umbraco font)</font> </fonts>- <sizes> <size>10</size> <size>11</size> <size>12</size> <size>13</size> <size>14</size> <size>18</size> <size>24</size> <size>36</size> <size>48</size> <size>72</size> </sizes>- <colors> <color>000000</color> <color>333333</color> <color>666666</color> <color>999999</color> <color>FFFFFF</color> <color>ffcc33</color>

71

</colors>- <bgcolors> <color>000000</color> <color>FFFFFF</color> </bgcolors> </fontConfig>

The scheme should be easy to edit, in order to add a new font to the collection, add a new node to the “/fontConfig/” font nodeFormat:

<font filename=”[fontfilenamewithoutextension]”>[Font displayname]</font>In order to add a new size to the collection add a new node to the “/fontConfig/sizes” node format:<size>[numeric pixel value]</size>

Add text colour to the – add a new node to the “/fontConfig/colors” format:<color>[RGB HEXCODE OF COLOR WITHOUT #]</color>

Add a new background color – add a new node to the /fontConfig/bgcolors” format:<color>[RGB HEXCODE OF BACKGROUNDCOLOR WITHOUT #]</color>

72