Masterpages

Umbraco (since version 4) uses ASP.NET master pages, so if you are familiar with these you will find this a breeze.

When creating a new template via the backoffice, Umbraco generates a masterpage file that inherits from "_{/umbraco/masterpages/default.master", whilst storing the newly created template in "}/masterpages/[Template_Alias].master".

Declaration

When a new template is created, it will by default contain 3 lines of predefined markup:

<%@ Master Language="C#" MasterPageFile="~/umbraco/masterpages/default.master" AutoEventWireup="true" %>

<asp:Content ContentPlaceHolderID="ContentPlaceHolderDefault" runat="server">

</asp:Content>

The first line is the template declaration. It tells Umbraco what language the template is written in and if it inherits from another template. Masterpages in Umbraco will always inherit from another Masterpage. If it's a root template, it will inherit from /umbraco/masterpages/default.master which is the default Umbraco masterpage, which is needed for the templating system to work.

umbraco:item

The umbraco:item element is used to pull a property from the page, currently being rendered, the below sample renders the value with the alias "bodyText" from the current page, if the value does not exist, nothing is rendered

<umbraco:item field="bodyText" runat="server" />

There are several advanced options for usingumbraco:item: for controlling fall-back values, recursive lookups, casing, encoding and so on:

<umbraco:Item field="bodyText" useIfEmpty="contents" textIfEmpty="Fallback value" case="upper" recursive="true" runat="server" />

See the full umbraco:item reference

umbraco:image

Introduced in Umbraco 4.11.0, the umbraco:image control enables you to add images from your content to your templates. The control is used as such:

<umbraco:image runat="server" field="bannerImage" />

This will output an <img/> tag when the template renders:

<img src="/media/19/imagename.jpg" />

See the full umbraco:image reference

umbraco:macro

The umbraco:macro element renders the out of a macro with a given alias. Attributes on the element are passed to the macro as parameters for the rendering. In the sample below, the macro with the alias "topnavigation" is rendered, and the parameter "className" is set to "greenList" which is passed on to the script associated with the macro.

<umbraco:macro alias="topnavigation" className="greenList" runat="server" />

See the full umbraco:macro reference

Template inheritance

Templates can inherit other templates and uses 2 elements to merge them. <asp:contentplaceholder> and <asp:content> To connect one template with another, use the dropdownlist in Umbraco to specify the master template. This will change the template declaration and make a database change.

Let's imagine we have defined the below template structure.

• Master.master
  • Homepage.master
  • Textpage.master

For inheritance to work, the parent template (master.master) needs to have a placeholder and the child-templates needs to have a content area which matches the placeholder alias.

So in master.master we have the default asp:content element, and inside of that, we have a placeholder with id "myarea"

<%@ Master Language="C#" MasterPageFile="~/umbraco/masterpages/default.master" AutoEventWireup="true" %>
<asp:Content ContentPlaceHolderID="ContentPlaceHolderDefault" runat="server">
    <div id="myDiv">
        <asp:contentplaceholder id="myarea" runat="server"/>
    </div>
</asp:Content>

In the child templates, we will now need to have a asp:content area which matches the placeholder id

<%@ Master Language="C#" MasterPageFile="master.master" AutoEventWireup="true" %>
<asp:Content ContentPlaceHolderID="myarea" runat="server">
    <h1>this is my child template</h1>
    <p>body text</p>
</asp:Content>

When the page is rendered, the resulting html in the browser will look like this:

<div id="myDiv">
    <h1>this is my child template</h1>
    <p>body text</p>
</div>

asp:contentplaceholder

ContentPlaceholder is, as the name implies, a placeholder for content being merged from another template. The element requires an Id, and runat="server"

<asp:contentplaceholder id="myArea" runat="server" />

A placeholder can also contain a default value, in case it is not used by a inheriting template

<asp:contentplaceholder id="myArea" runat="server">
    <p>Show this, if no inheritance</p>
</asp:contentplaceholder>

asp:content

Content requires a placeholder in its master template to function, so the contentplaceholderId attribute must match the id of contentplaceholder element in the parent template, or you will get a YSOD detailing what content element cannot find its placeholder. All html in the Umbraco templates must be wrapped in a asp:content element.

<asp:content runat="server" contentplaceholderid="placeholder">

inline code

it is possible to run C# code directly in the template, but is not in any way recommended. However, if it is required, the standard masterpages syntax can be used:

<%
    if(SomeCondition){
        throw new Exception("Explosion!");
    }
%>