Table of Contents

Part I: Creating Your First Site with Umbraco

Chapter 1: Installing for the First Time

Installing Umbraco

Upgrading Umbraco

Utilizing Umbraco Starter Kits

Applying and Manipulating Umbraco Skins

Finding and Installing Umbraco Modules

Take Home Points

Chapter 2: The Umbraco Approach

Separating Content and Structure

Umbraco Content Tree

Umbraco Building Blocks

Take Home Points

Chapter 3: Document Types

The Data Model

Flexible Content Structure

Working with Document Types Outside of Umbraco

Using Document Type Properties

Take Home Points

Chapter 4: Templates, Markup, and Master Pages

Building Website Structure using Templates

Defining Markup

Using Special Umbraco Tags

Umbraco and Your Markup

Using AltTemplate

Styles and Scripts

Take Home Points

Chapter 5: Using Macros

Introduction to Umbraco Macros

XSLT Powered Macros

.NET User Controls

Support for the .NET DLR

User Generated Forms Using Umbraco Contour

Take Home Points

Chapter 6: Languages and Dictionaries

Languages

Dictionaries

Take Home Points

Chapter 7: Multiple Sites, Hostnames, and Localization

Setting Up Multiple Sites

Working with Hostnames

Translation Workflow

Take Home Points

Part II: Content Production

Chapter 8: Creating Content

Content Management Best Practices

Creating a Structure

Organizing Templates for Reuse

Understanding the Rich Text Editor

Take Home Points

Chapter 9: Adding Functionality

Using the Umbraco Tags

Generating Website Navigation Menus

Providing the Latest News, Events, and Posts

Using Examine to Search Content

Take Home Points

Chapter 10: Packages—Whatever You Can Imagine

Understanding Packages

Using Community Packages

Understanding the Package Repository

Using Commercial Packages

Creating Your Own Packages

Take Home Points

Chapter 11: Using XSLT

Using XSLT for Published Content

Understanding XPath

Working with Media

Looking at Some XSLT Examples

Take Home Points

Chapter 12: Working with .NET Controls

Creating a Macro

.NET Samples

Using .NET from XSLT via XSLT Extensions

The Umbraco Event Model

LINQ to Umbraco

Take Home Points

Part III: Deploying, Troubleshooting, and Sample Applications

Chapter 13: Deploying to a Production Installation

Planning Considerations

Using the Packager

Database Synchronizing

Using Courier

Take Home Points

Chapter 14: Troubleshooting

Installation Troubleshooting

Shared Hosting Considerations

Error Handling and Logging

Moved and Missing Web Pages

Take Home Points

Chapter 15: Sample Application: Classified Ads

What to Configure for this Example

Assumptions to Make for this Example

Visual Studio Features

The Umbraco Installation Components

Putting It All Together

Take Home Points

Part IV: Appendices

Appendix A: Upgrading an Existing Installation

Overall Steps to Upgrade

Backing Up Your Files and Database

Checking Package Compatibility

Copying the Right Files

Testing and Troubleshooting

Appendix B: Setting Up Your Visual Studio Environment

Setting Up the Umbraco Folder Structure

Setting Up the Build Events

Referencing the Umbraco Libraries

Appendix C: Resources

Source and Installation Files

Community

Umbraco Headquarters

Appendix D: Data Type Definitions

The Data Type's Purpose

Definition of Built-in Data Types

Configuring a Data Type to Your Needs

Introduction

Part I

Creating Your First Site with Umbraco

• CHAPTER 1: Installing for the First Time
• CHAPTER 2: The Umbraco Approach
• CHAPTER 3: Document Types
• CHAPTER 4: Templates, Markup, and Master Pages
• CHAPTER 5: Using Macros
• CHAPTER 6: Languages and Dictionaries
• CHAPTER 7: Multiple Sites, Hostnames, and Localization

Chapter 1

Installing for the First Time

• What are the steps for installing Umbraco?
• How do you upgrade your current site?
• Which Umbraco starter kit should you use and how do you install it?
• How do you apply and manipulate Umbraco skins?
• How do you find and install Umbraco modules?

Users have installed Umbraco literally hundreds of thousands of times in a variety of environments — everywhere from an entry-level Windows XP machine, to multiserver load-balanced sites, and even to Microsoft Windows Azure. In the vast majority of these cases the installations complete successfully and take no more than a few minutes. The first section of this chapter contains the Umbraco quick start instructions for facilitating a successful install. Read it, install Umbraco, and then continue reading for additional considerations.

You can always find the latest released version of Umbraco on the Umbraco CodePlex home at http://umbraco.codeplex.com/ from the Downloads tab. The latest version of Umbraco is also available via Microsoft's Web Platform Installer and Web Application Gallery (http://www.microsoft.com/web/gallery/umbraco/). This chapter offers a detailed overview for installing Umbraco with both the Microsoft Web Platform Installer and directly from the Umbraco installation file downloaded from the Umbraco CodePlex home.

Installing Umbraco

The text in this chapter, as well as the rest of the book, assumes that you have a PC running Windows Vista or Windows 7 and have user permissions sufficient enough to allow for administrative actions. If this is not the case, or if you are installing to a different environment (such as to a shared-hosting account) skip this section for now and refer to Chapter 14, which has troubleshooting tips. One important item to note is that Umbraco is best installed as a website root rather than as a virtual directory under a web root, so plan on running Umbraco from a web root. All current versions of Internet Information Server (IIS) support multiple web roots so running from a web root is not an issue unless you are using IIS5 on Windows XP. See Chapter 14 if this is the case.

Installing Umbraco using the Microsoft Web Platform Installer

The best way to begin your Umbraco installation is by using the Microsoft Web Platform Installer (a free installation tool developed and supported by Microsoft). Some advantages to using the Microsoft Web Platform Installer (shown in Figure 1.1) are that the tool can:

• Automatically detect and install required dependencies.
• Create a Microsoft SQL database or Microsoft SQL CE database prior to installing Umbraco.
• Create and configure new websites in IIS.

You can find the Microsoft Web Platform Installer at www.microsoft.com/web/ along with the latest versions of Umbraco and other web applications as well as any required dependencies. In addition, the Microsoft Web Platform Installer is available as an IIS extension at www.iis.net/extensions/WebPI/ and is integrated into web hosting control panels such as cPanel and DotNetPanel. Using a web host's control panel to install Umbraco in a shared hosting environment can greatly simplify the installation process.

Use the following steps to install Umbraco with the Web Platform Installer:

You're all done and Umbraco is ready for use, complete with a fully functional web site and beautiful skin! As you can see, when you compare the process to a manual installation as discussed in the next section, using the Web Platform Installer greatly simplifies the setup and configuration of the website and database requirements for Umbraco.

Installing Umbraco Manually

Although using the Microsoft Web Platform Installer to install Umbraco is strongly advised, cases may exist where a manual installation is desired. In such a case, you must manually complete the steps to create the IIS website, create the database, and set required permissions. The following are the steps to complete a manual installation of Umbraco: If you find yourself stuck on one of these steps, try installing Umbraco using the Quick Start steps first and then return to this section later.

You now have everything you need to successfully run, build, and extend Umbraco. Obviously not all Umbraco installations will fit into the preceding step-by-step instructions. The remainder of this chapter covers additional considerations for other installation scenarios and environments.

Tips for Installing Umbraco in Special Environments

One of the great strengths of Umbraco is its simple architecture, which enables it to adapt to a variety of installation and usage scenarios. Certainly the earlier quick start is a simple scenario intended for use on a single machine — most likely a web builder's desktop or laptop — but you can use this same procedure to install Umbraco on a netbook running Windows 7 or a web server running Windows 2008. This procedure is also appropriate for installing an evaluation instance, for an install used to “test” a feature or to reproduce a defect, as well as for a fresh start when building websites with Umbraco.

Debugging in a Development Environment

For web developers, especially those working with .NET user controls integrated with Umbraco, the ability to debug code while running Umbraco is important. You can easily do this debugging by installing Umbraco onto the same physical machine that has Visual Studio installed. This can be on a local development laptop, a virtual machine, or a remote development machine accessed via remote desktop. You can also debug .NET code in a running Umbraco instance on domain-joined machines with the appropriate debugging tools installed and configured, but that is beyond the scope of this book. For this scenario, check out the advanced developer sections of the Umbraco wiki (http://our.umbraco.org/wiki).

Security Settings in a Production Environment

When installing to a production environment, you must take some additional considerations into account, and not the least of these are the security and access settings for the Umbraco site and related files (see the earlier A Note on Security sidebar in the “Installing Umbraco Manually” section). In addition you will likely create a backup routine for your Umbraco instance. Including both your Umbraco database and your Umbraco files in your backup is important to have a complete snapshot. The author recommends reviewing the current backup documentation on the Umbraco wiki (http://our.umbraco.org/wiki).

Other Installation Scenarios

Of course, other scenarios exist in which you might install Umbraco, such as load balancing, cloud installation (Amazon EC2 or Microsoft Windows Azure), distributed publishing, and others. These scenarios are supported but are outside the scope of this book. For more information on them refer to the Umbraco wiki, the Umbraco forum, and Umbraco.tv for more information.

Upgrading Umbraco

The Umbraco Installation Wizard can manage patch upgrades (e.g., 4.5.1 to 4.5.2) and single major version upgrades (e.g., 4.0 to 4.5) gracefully and is the recommended approach for upgrading an installation. With all upgrades, knowing whether your installation contains any modified source or files from the original distribution is important. If so, take care to make backup copies of these files. In addition, if your installation contains a customized web.config file, or other configuration file, creating a backup of your configuration files for later use is essential.

Performing a Patch Upgrade

Typically, a patch upgrade contains no new functionality and requires no changes to configuration files. Reading the notes associated with a new Umbraco release prior to installing or upgrading an installation is good practice because any changes to configuration files will be documented in the notes.

The process to complete a patch upgrade is generally as follows:

You can always find the latest release of Umbraco at the Umbraco home on CodePlex at http://umbraco.codeplex.com/releases.

Unless specified in the release notes, you will only copy the following directories to your installation:

• /app_data
• /bin
• /install
• /umbraco
• /umbraco_client

After the files are copied, open a browser and navigate to your Umbraco instance. The Umbraco Upgrade Wizard launches and guides you through the process to complete the site upgrade.

In addition, you must remove any cache files located in the /app_data/TEMP/ folder, such as those generated by the client dependency loader, the Examine Search indexer, and the Umbraco document cache.

Performing a Version Upgrade

When upgrading between single major versions, identifying all third-party components and Umbraco version-specific features is important. Breaking changes are noted in the major version's release notes and in Umbraco-provided installation and upgrade guides. Aside from verifying that third -party components are compatible with the version to which you are upgrading, creating a backup of all modified files, dependent assemblies, ASP.NET user controls, and all configuration files is essential.

The process to complete a version upgrade is generally:

After the files are copied and the configuration files are updated, open a browser and navigate to your Umbraco instance. The Umbraco Upgrade Wizard launches and guides you through the process to complete the site upgrade.

Utilizing Umbraco Starter Kits

Umbraco comes with four starter kits to help you get up and running quickly with your Umbraco installation. These include the Simple starter kit, the Blog starter kit, the Personal starter kit, and the Business starter kit. Each of these starter kits contains a collection of document types, templates, and modules that make up a simple but complete site. In addition, you can customize each starter kit with a skin and additional modules (discussed later). You can either install Umbraco starter kits when you install Umbraco or at a later time from the Developer Packages section of the Umbraco backoffice as shown in Figure 1.22.

Installing a Starter Kit

Umbraco starter kits take a best practices approach to site structure. Although the rest of this book deals with the Umbraco building blocks — document types, templates, and such — in great detail, after Umbraco has been installed, the Umbraco starter kits give a simple example of how you should structure a site, which is especially helpful for new Umbraco users. If you didn't install a Starter Kit when you installed Umbraco, don't worry; this section details how to install a starter kit and modules to an existing Umbraco installation.

If you've already installed a starter kit, you made a good choice! With a starter kit installed you have a great starting point with some basic content, templates, document types, and a macro or two. One of the best ways to familiarize yourself with Umbraco, other than reading this book, is to dive in and inspect the structure of the document types, the markup in the templates, and the code in the XSLT macros. Although the included starter kit samples are quite simple, they also represent Umbraco best practices for creating a simple site and its structure.

If you didn't install a starter kit and have now decided you want to install one, simply access the Install Starter Kit option from the Packages tree in the Umbraco Developer section (see Figure 1.23). You can install skins from this section as well.

The following sections discuss the various starter kits in detail.

Simple Starter Kit

The Simple starter kit is the simplest and most semantically strict starter kit. It has a generic structure and is the prerequisite for many modules and other Umbraco packages. If you are new to web CMS, and Umbraco in particular, you should begin with this starter kit.

The Simple starter kit contains a home page and several subpages along with a navigation module. The Simple starter kit is intentionally missing styling and images in order to focus on the structure. A few minutes spent looking over the Homepage document type and template is time well spent understanding the Umbraco approach to defining data storage and layout.

Blog Starter Kit

The Blog starter kit contains all the elements of a blog site and demonstrates the Umbraco approach to keeping content organized in a date folder format. You can create a new blog post to see this feature in action. After you have given your blog a name, right-click the blog site's home page and select Create, then select Blog Post. Notice that Umbraco creates the folders for year, month, and day automatically.

The Blog starter kit also contains macros that list the latest blog posts on the blog site's home page, list the blog posts in the archive, and allow site visitors to submit comments related to a blog post. The kit even applies a spam filter to submitted comments so your blog site is not inundated with comment spam.

The Blog starter kit is a great example of how you can allow user-generated content, comments in this case, on your site. It's robust enough for you to install and start blogging today without any changes required, or you can use it as the basis for a blog site you customize further.

Personal Starter Kit

The Personal starter kit is a complete site for your own personal home on the web with a summary Homepage and subpages for more about you. The kit also includes a Gallery section where you can feature photos or images you provide in a web-friendly gallery format. The Personal starter kit is also a great starting place for a portfolio site as well where you might feature your own work, whether it is photography, graphics, or poetry.

Business Starter Kit

The Business starter kit is the starting point for a business presence on the web. With the Business starter kit as a beginning, a business can build a meaningful website in almost no time. The Business starter kit includes a blog section, with blog comment moderation tools, a news section, and a built-in contact form. As with all the Umbraco starter kits, you can easily add new functionality or change the default functionality to create the Umbraco site that perfectly fits your needs.

Extending the Starter Kits

The Umbraco starter kits are only a starting point. Each is licensed with the MIT open source license, which allows you to change, add, and remove any feature, code, or layout you want. When you combine the Umbraco starter kits with the knowledge you gain from this book, there are no limits to what you can accomplish.

With the addition of a skin and modules, which are discussed later, creating a complete website without writing one line of code is entirely possible. After you add in some of the advanced techniques discussed later in this book, you will have the platform for building a myriad variety of websites.

Applying and Manipulating Umbraco Skins

Umbraco skins are created by the Umbraco community members and can be installed from the Developer Packages section of the Umbraco back office. Basically, Umbraco skins enable you to change the look and feel of an Umbraco starter kit simply by applying the skin to a starter kit site. In addition, you can customize skins with user-defined text, colors, and images. Umbraco skins build on the best practices approach of Umbraco starter kits by demonstrating the best way to implement styling and layout control in your site.

When you apply a skin to an Umbraco starter kit site, the skin's styles are used in place of the existing starter kit site's styles. The skin simply provides a unique Cascading Style Sheet (CSS) file, including any images required to achieve the layout defined by the CSS. A skin can also add or change small portions of the starter kit site's HTML templates if needed. You can roll back all CSS, images, and HTML changes to the starter kit's default skin for a site because Umbraco creates a backup of the starter kit's default skin when you apply a different skin.

By default, you can only apply skins to the Umbraco starter kits as opposed to an arbitrary Umbraco site as skins depend on the starter kit's layout. Umbraco automatically determines which skins you can apply to the currently installed starter kit and presents these in the skin selector.

You can select and apply a skin (see Figure 1.24) either when you install an Umbraco starter kit or you can do so at a later time.

To access, install, and customize a skin, follow these steps:

Customizing a Skin

You can customize an Umbraco skin using only the Umbraco Skin editor with no code required. An Umbraco skin may contain dependencies. Think of these as options that enable you to customize the skin for your own site's use. You can use Umbraco skin dependencies to customize a starter kit site's text, colors, and images. In this way a single skin applied to a single starter kit can be unique from every other Umbraco site with the same starter kit and skin because of the customized text, colors, and images.

When you install a skin, the dependencies defined by the skin author can be set using the Umbraco Skin editor. After a skin has been installed it can be customized.

To customize an installed skin:

Modifying a Simple Umbraco Skin

If you're comfortable editing HTML and CSS you can modify a skin further for your own use. At its most basic, an Umbraco skin contains only CSS to achieve the desired changes to a starter kit site's styles. You simply include a reference to the skin's unique CSS file in the starter kit's MasterPage template. Don't worry about the terminology yet; this is just an example and all terms you see now are explained fully a bit later in this book. Using this simple example, you can include the following line in the starter kit's MasterPage template so that any styles defined in the referenced CSS file will automatically apply to the starter kit site:

When you modify a skin, you may need to add additional elements to a starter kit's MasterPage template in order to apply the desired layout control. To do this, the skin alters the starter kit's default MasterPage template, in this case by adding a single <div> element.

The default Runway starter kit MasterPage template contains this markup:

A skin might add a <div> element, the <div id=“menu” class=“container”>, to apply a particular style to the starter kit's navigation sections, as follows:

In this way an Umbraco skin can insert the HTML needed to achieve the desired styling without affecting the function of the starter kit site in any way.

Typically, a skin should only change the CSS and related images and script for a site. If needed, a skin may also change small snippets of HTML, such as to add an ID to an HTML element or create a new <div> for layout control. In this way, skins are kept as independent of a starter kit site's markup as possible and maintain maximum flexibility. A skin may also introduce a unique set of scripts, generally JavaScript, to add functionality related to the skin. In addition, a skin may include images used for layout and styling.

Finding and Installing Umbraco Modules

Umbraco modules are small pieces of functionality that are compatible with the Umbraco starter kits and are open-source licensed so that you may change the way the modules work if you want. When you install an Umbraco starter kit, such as the Simple starter kit, some modules are installed for you. The top navigation, contact form, and feed viewer are all examples of Umbraco modules.

Umbraco modules are simply Umbraco macros specifically designed to work seamlessly with Umbraco starter kits. The modules may have dependencies on specific starter kit markup, such as an HTML element id or a content placeholder id. In most cases, you can also use Umbraco modules with Umbraco sites that are not based on Umbraco starter kits. Most Umbraco modules are created without compiled code, which allows you to investigate the module or to alter it for your own specific use. Some modules use XSLT, which you can find in the /xslt/ folder in your Umbraco site's root. Other modules use ASP.NET, generally C#, code, which is either in the /app_code/ or /usercontrols/ folder in your Umbraco site's root.

Some Umbraco modules are installed when you install an Umbraco starter kit.

You can install Umbraco modules directly from the Umbraco Skin editor. When working with the Skin editor for an Umbraco starter kit, do the following:

Take Home Points

After reading this chapter, you should feel comfortable installing Umbraco for the first time. Besides knowing how to install Umbraco using the Web Platform Installer or manually, you should know what to do in special environments and how to upgrade Umbraco. In addition, you should understand the purpose of a Starter Kit and a skin. The following list outlines what you should be “taking home.”

• You should use the Microsoft Web Platform Installer for an error-free installation.
• You must pay close attention to your website's user permissions during manual installation.
• You should use the sample checklist provided when upgrading
• Installing a Starter Kit is a quick way to get your site installed.
• You can install a Skin to make your site beautiful.
• Skins are easy to customize for your own use.
• Modules are small features that you can easily add to a Starter Kit.