USING SPECIAL UMBRACO TAGS
Like most CMSs, Umbraco utilizes special tags to render any content that is entered by a user in the backoffice. If you're at all familiar with .NET syntax for including user controls or custom tags, this should make you feel right at home. Here's what a basic tag looks like:
<umbraco:Item field=“pageName” runat=“server”></umbraco:Item>
This is the tag in its simplest form. It can get more complex than this—in fact, a lot more complex. The Umbraco backoffice UI has a widget to insert these Umbraco items in your templates, so you don't have to do the heavy lifting. This includes built-in fields, like the one field reference in the previous code snippet, as well as custom document type properties. You can launch the Insert Umbraco page field dialog (shown in Figure 4-9) by clicking the insert Umbraco page field button located toward the top of the right-hand pane next to the Save button.
The Insert Umbraco page field dialog contains the fields presented in Table 4-1.
TABLE 4-1: Umbraco Page Fields
| FIELD | DESCRIPTION |
| Choose field | Allows you to pick from any of the built-in properties provided by Umbraco or any of the custom properties that you defined in your document types. |
| Alternative field | Offers the same list of properties as available in the Choose Field, only the Alternative Field option is used if the Choose Field value is null or empty. For example, you may have specified a property called contentPageTitle that is optional for the user to fill in. Because it is optional, and it is the heading of the page, you must ensure that some value is in place. So, if the user leaves this field blank, you can tell Umbraco to use an alternate field instead (such as @pageName, which is always available as a built-in property). |
| Alternative Text | You can specify this static string if, for some reason, both of the preceding properties are empty. |
| Recursive | Indicates if the selected page field is recursive and tells Umbraco to traverse up the content tree hierarchy to look for a value in parent nodes if one is not available on the page where this field is being rendered. This is especially useful for something like meta keywords that you can add to the homepage node and then only specify on a page-by-page basis where the keywords may differ from the overall website. See Chapter 3 and master document types for more information on this. |
| Insert before field/Insert after field | Comes in handy when you want to concatenate strings with Umbraco property values. To piggy-back on the previous example, you can use this when implementing meta tags in your header.
<umbraco:Item field=“metaKeyWords” insertTextBefore=“<meta name="keywords" content="“ ; insertTextAfter=“"/>” runat=“server”></umbraco:Item> |
| Format as date | If your field is a date, Umbraco can automatically format the date for you. This is also locale or culture specific. |
| Casing | Umbraco can output the value of your field by converting it to either uppercase of lowercase. |
| [encoding] | Encodes the string into either HTML or URL structured formats. |
| Convert Linebreaks | If the displayed property is of type Textbox Multiple, Umbraco can automatically convert any newline characters with HTML-friendly <br /> tags. |
| Remove Paragraph tags | Conveniently removes the paragraph tags from single paragraph text (created in either the Textbox Multiple or Rich Text Editor data types). |
As of Umbraco version 4.x, you can include what is referred to as Inline XSLT statements. This provides you with far greater capabilities to manipulate the output of any given field. For example, if you wanted to format the date of a field in a particular way, different from the standard format that Umbraco field attributes provide, you could add the optional XSLT attribute to the umbraco:Item tag, like so:
<umbraco:Item field=“dateField”
xslt=“umbraco.library:FormatDateTime({0},‘MMM dd, yyyy’)”
runat=“server”>
Now that you know what all of these attributes mean and do, take a look at the Textpage.master template again, but this time populated with document type properties and the <umbraco:Item…> tag.
Fields that are prefixed by the @ (at) symbol in the list are built-in Umbraco properties and are populated automatically by Umbraco, as covered in Chapter 3. The properties that do not have this prefix are custom properties defined for each individual installation.
LISTING 4-3: Textpage.master (continued)
<%@ Master Language=“C#” MasterPageFile=“~/masterpages/Master.master”
AutoEventWireup=“true” >
<%-- Populate the header container -->
<asp:Content ID=“HeaderContent” ContentPlaceHolderID=“HeaderContentCtr”
runat=“server”>
<h1><umbraco:Item field=“siteName” recursive=“true”
runat=“server”></umbraco:Item></h1>
</asp:Content>
<%-- Populate the body container -->
<asp:Content ID=“BodyContent” ContentPlaceHolderID=“BodyContentCtr”
runat=“server”>
<h2><umbraco:Item field=“pageTitle” useIfEmpty=“pageName”
runat=“server”></umbraco:Item><umbraco:Item field=“pageTitle”
useIfEmpty=“pageName” runat=“server”></umbraco:Item></h2>
<umbraco:Item field=“bodyText” runat=“server”></umbraco:Item>
</asp:Content>
<%-- Populate the footer container -->
<asp:Content ID=“FooterContent” runat=“server”
ContentPlaceHolderID=“FooterContentCtr”>
<p>Last Published: <umbraco:Item field=“updateDate”
formatAsDateWithTime=“true” formatAsDateWithTimeSeparator=“ ”
runat=“server”></umbraco:Item></p>
</asp:Content>
You may be wondering where the navigation and all the fun stuff is. Chapter 5 covers this in the discussion about macros. Macros bring endless power and flexibility to the table via .NET user controls, XSLT stylesheets to render cached content, and even IronPython and Ruby, as well as other supported languages on the .NET DLR (dynamic language runtime).
Applying the Template
You've worked very hard on making the templates look great, but so far you really have no way to display them. The next step is to apply them to the content; that is, associate the template(s) with applicable document types. You accomplish this task, too, in the backoffice UI.
- Navigate to the desired document type in the Settings section.
- Make sure the Info tab is selected.
- As shown in Figure 4-10, select which template(s) you want to allow for this document type. If you want to allow more than one, choose the default template.
Nesting and Inheritance with ASP.NET Master Pages
As you can see from the earlier examples and descriptions, Umbraco's leveraging of the .NET master page implementation natively is an immense benefit to you as a developer. Thus far, this chapter has covered how to use nesting and how children fill in content regions in parent templates. So, how does this all work? Take a look at Figure 4-11, and see how it starts.
.NET compiles the view that is presented to the user from the bottom up. Figure 4-11 illustrates what it would look like at this juncture.
Up until now, view and master page were two separate objects, each with its own hierarchy. Figure 4-12 illustrates this hierarchy. The master page applies itself during runtime—it replaces the page's children with itself.
Now the master page looks for <asp:Content> controls associated with the view. When it finds an <asp:Content> control that matches an <asp:ContentPlaceHolder>, it moves the controls into the matched <asp:ContentPlaceHolder>. In your simple setup, the master page will find a match for ContentPlaceHolder1 and copy over the Label. You wind up with what is shown in Figure 4-13.
All of this work occurs after the content page's PreInit event, but before the content page's Init event. During this brief slice of time, the master page is deserving of its name. The master page is in control, giving orders and rearranging controls. However, by the time the Init event fires, the master page becomes just another child control inside the page. In fact, the MasterPage class derives from the UserControl class. Think of master pages as masters during design time. However, when the application is executing, treating the master page as just another child control is more accurate.