Getting Started with Umbraco: Part 1

Umbraco can be installed very quickly and easily. Even better, it comes with many features straight out of the box. For example, it's possible to build an entire site without delving into the code yourself, simply by using pre-built templates and the back-end CMS. But for us developers who like to get our hands dirty, websites can also be coded completely from scratch. In this series, we'll be creating an entire site ourselves from scratch, because where's the fun in having it all done for you, right?!

Things We Will Need:

IDE: We'll also need a .Net IDE, ideally we can use Visual Studio, but Microsoft's Visual Web Developer (VWD) Express, which is free, is just as good for our needs here. This application can be installed, along with the necessary dependencies using the Web Platform Installer (WPI), found at: http://www.microsoft.com/express/Web/

SQL Server: Once SQL Server 2008 has been installed, we'll need to grab the Database and Management Tools; these are found on the Express Downloads page at http://www.microsoft.com/express/Downloads/ (make sure the SQL Server 2008 R2 Express tab is selected and choose the correct type for your operating system (32 or 64 bit). When installing SQL Server, ensure that mixed-mode or SQL authentication is selected and enter a password to access the server. The default user name is sa, this is required when installing Umbraco. Note that Umbraco is compatible with a range of different database solutions; we're using MS SQL here because it is likely (but not guaranteed) to be the database type in use on a professional .Net hosting service and so should make migration of the database and content from local development to live server easier.

Step 1 - Setting Up The Site And Installing Umbraco

Open up VWD and click the New Web Site option from the side-bar at the left of the start page. Choose Visual C# from the Installed Templates section in the left column of the New Site dialog, ASP.NET Empty Site from the central column, and choose an install location somewhere on your machine. I created a new folder called .netsites and then created another new folder within this called umbracosite. Once the site has been created and opened in the main VWD window, make sure you change the Virtual Path option in the Properties pane from /umbracosite to / (this is the root of the site).

We'll also need a database which will contain all of the Umbraco information needed to make the back-end work, as well as all of the content that we create once the site is built. There are a number of data sources we could use, but as the WPI will automatically install SQL Server Express, we may as well use that. Create a new database using the SQL Server Management Studio and call it something like umbracodb or similar. Make sure you can connect to the server using SQL authentication with the username sa and the password you entered during installation.

Next, open up the Umbraco zip file, then open the build directory and copy all of the folders and files into the folder for the site we just created. Make sure you replace the web.config file when asked to do so. Once this is done, switch to the Solution Explorer tab in the Solution Explorer pane at the right and hit the refresh icon. All of the folders and files we just added to the folder will be listed. Expand the install folder, right-click the default.aspx file and choose View in Browser. This will launch the Umbraco installer in your default web browser. Click the giant Let's Get Started button to make a start.

The first screen is the license screen; have a read though it (it's just a few lines!) and then hit the Accept and Continue button at the bottom. The next screen will ask if you have a blank database installed, choose Yes and then select Microsoft SQL Server from the drop-down list box. On the next screen enter the name of the SQL server (probably Desktop), the name of the database you created, the username (sa) and the password you use to access SQL Server. Click the button. The tables used by Umbraco will be created in the database.

On the next screen choose a password to access the Umbraco back-end. The default username of admin is fine for local development, and additional admins can be created when the site goes live. Click the button.

On the next screen you can choose the type of site you are creating, which will give you a kit tailored to that type of site. For us techies, we probably want more control than these starter kits will give us, so hit the No Thanks button at the end and confirm the dialog. That's it, we're done! Click on the large Set up your new website button and we should be prompted to log in to the Umbraco back-end using the username and password we specified during install. Once we do this, we should see the back-end of the CMS:

The left-hand panel at the top is the node tree; this is where all of the nodes (the different pages and content items) that make up the site are displayed in the default view. This will change depending on which section we are in. The different sections are accessed via the bottom panel at the left. In the right hand area we will see the different tabs, properties and content items for each node in the default content section. Again, this right hand area will change depending on what we have selected in the node tree.

Step 2 - Defining Document Types

The first stage in creating an Umbraco site (after installation of course) is defining your document types.

These are very important and are difficult to modify later on, so it is worth spending some time planning the document types you need and how they are going to fit together. But what are document types? Quite simply, they specify the different types of documents that your site will be made up of and the hierarchy of these documents, i.e. how they nest.

Document types define the visible pages of your site, for example, your site is likely to be made of a range of different types of page, such as the home page, content pages, news pages, and probably others. But they also define what editable content regions or fields the administrators for the site have in the back-end CMS.

So for example, the home page may have an introductory text area, a banner image, and a content slider or hero-panel explaining what service(s) the site provides, or the products made by the company, etc. Of course, the page is likely to have lots of other elements on it as well, such as header, a navigation menu and a footer; but I'm talking about content items, the editable content stored and managed by the CMS.

Each of these different areas of the page will map to different regions in the back-end, so the introductory text on the home page would map to a rich text editor in the back-end and the banner image to a media picker. The different panels in the content slider could even map to a specialised document type that does not relate specifically to a whole page.

Let's create some document types now as this will give you a much clearer picture of this extremely important concept. First click the Settings link in the Sections panel (bottom-left), the right-click Document Types and select Create:

In the dialog that appears choose Base Page as the name and then click the Create button. A new node for our document type will be created in the main left-hand node tree, and the property sheet for the Document Type will be displayed in the main panel at the right:

As you can see from the above screenshot a matching Template has also been created and has been added to the Allowed templates section in the right hand panel. The Default template for this Document Type has also been set to Base Page. We'll look at templates in more detail shortly but for now just know that they map to .Net masterpages.

There are a series of properties that we can complete if appropriate. We can nest Document Types so it can be useful to set some general properties that any child document types will inherit. Switch to the Generic Properties tab and select the item that says Click here to add a new property to expand the item. In the Name text field enter the text Domain Name (the Alias will be populated automatically), and in the Type select box choose Textstring:

To add the new property click the save icon (the disk) at the top of the panel. Now any Document Types that are derived from Base Page will inherit the Domain Name property (although it will not be editable). Add one more property to the Generic Properties tab; the name is

Umbraco Hide In Navigation

(but change the alias manually to umbracoNavHide) and the Type should be True/false. The purpose of this will become clear when we start writing our XSLT in part 3 of this series, so I won't go in to any detail here.

It is also common practice to add things like meta keywords and a meta description here (although we'll forgo that in this example). Now we can create some additional Document Types, one for the home page, one for content pages and one for news pages. We can also create a Document Type for our carousel/hero panels.

To create the home page document type right click on the Base Page Document Type and choose create, add Home Page as the name of the new Document Type. This new Document Type will be nested within the Base Page document in the node tree, but for it to derive from the Base Page properly we need to select the Base Page Document Type in the left menu, switch to the Structure tab and tick the Home Page check box. Click the save icon to confirm the change. Now the Document Types will nest properly.

As a matter of course I normally set a new Icon and Thumbnail for the home page. This can be done on the Info tab. I have chosen Setting Domain for the Icon and docWithImage for the Thumbnail. These aren't critical, but they are considered a nice touch and will give the home page a little house icon in the content part of the CMS.

We'll need some more properties for this Document Type, but as these are to do with the content on the page we'll create a new tab for them. Make sure Home Page is selected in the node tree and then switch to the Tabs tab. In the New Tab field enter Content and click the New tab button, and once the tab is listed click the save icon.

We'll also need some properties for our home page, remember, our home page will feature some introductory text, a banner image and a hero panel carousel; we'll deal with the carousel separately, but we still need to define the introductory text and banner image. Select the Generic properties tab and create a new property for the introductory text:

Once this property has been added, create a new property for the banner image:

Both of our properties have been added to the new Content tab, and both are set to mandatory, so when we begin creating pages, both of these properties will need to be set in order to publish the home page. Don't worry if none of this is crystal clear at the moment, it will all come together as the site is built.

We still need Document Types for our content pages, news pages, and hero panels. Right click the Base Page Document Type once more and choose Create. Call the new Document Type Content, and make sure it is set as an allowed child node type in the structure tab of the Base Page document type. Choose a new icon and thumbnail for this Document Type (I have set both to doc), create a content tab and set a mandatory property on the Content tab called Page Copy, which should be of the type Richtext editor. We can also add a property on this Document Type for the page title. This property can go on the Generic properties tab and should be a simple Textstring. It does not need to be mandatory.

Next create a Document Type called News List; it should be nested under Base Page (remember to set it as an allowed child node of the Base Page Document Type by ticking the box on the structure tab) and just needs one generic property – a Page Title. The News List page on the visible forward-facing site will be built from a series of news items so does not need to have any content added to it. But we also need to create a Document Type for the news items.

Right click the News List document type and choose Create. Add News Item as the name and once it has been created, go to the Structure tab of the News List Document Type and set News Item as an allowed child node. The News Item Document Type will need to have a Content tab added, and will need the following properties: Names, Type, Date, Date picker, Headline, Textsrting, News Text, Richtext editor, Story Image, Media picker.

All except the Story Image should be mandatory and all should go on the Content tab.

Finally, we can create the Document Type for our hero panels. This Document Type will differ from those we have created so far because it won't have a matching template (masterpage). Right-click on Base Page and create a new Document Type called Hero Panel, making sure the Create Matching Template checkbox is un-ticked. This document type will need a Content tab and a single property called Panel Content of type Richtext editor.

For the XSLT macros that we'll create later on to work correctly all pages of the site will need to be nested under the Home Page in the Content section of Umbraco. To set this up, all we need to is select the Home Page document type, go to the Structure tab and tick the box for the Content, Hero Panel, and News List pages, then click the save icon. That's it, our Document Type work here is done!

There are other things we can do; for example, we can go back and give our Document Types and properties descriptions to make the CMS more user-friendly for the client that will eventually use it to maintain and administer their site. There are also many different icons and thumbnails to choose for the different types of nodes we might create. At this point, our back-end should appear like this:

Step 3 - Templates

Templates are masterpages and each time we've created a Document Type (except for the Hero Panel) we've created a matching template. Expand the Templates folder in the node tree (if the templates are not listed just right click the Templates folder and choose Reload nodes) to see all of the templates that have been created. Just like Document Types, templates (and therefore masterpages) can also be nested, which is another powerful feature that we can take advantage of. To nest the templates we need to select each template and choose which template they should be nested under.

Working backwards from the order we created the Document Types in choose the News Item template in the node tree. It will populate the right hand pane of the CMS and list some information about the template and the code (which will be practically empty at this point with just a little ASPX code at the top. In the Master template select box choose Base Page.

Although the News Item document type is a child of the News List document type, the template does not necessarily need to be nested under the News List template, but it does need to be nested under the Base Page template in order to pick up the site-wide header, footer and main navigation that we'll add. Save the change by clicking the disk icon.

The Content, Home Page and News List templates should all be nested under the Base Page template by choosing Base Page from the select box in each template. Once you have done this right click the Base Page template and choose Reload nodes. All four templates will then be shown as children of the Base Page:

We're now at the stage where we can begin coding; we'll make a start on this by adding the code for each template in the next part of this series.

Summary

In part one of this series we looked at what Umbraco is and what it can be used for, and walked through the super simple installation process to get a local site setup for development. We saw that Document Types are the key to the structure of both the forward-facing web site and the content section of the back-end CMS.

Document types are a simple but powerful construct that are used to define the different types of document that make up the site, as well as the relationships between them, and the properties available for new content nodes (pages) of the site. Their power and some of the things we have configured, such as properties will become more apparent as the site is built and we begin to add content pages.

We also saw that templates in Umbraco map directly to .Net masterpages and that for maximum code-reuse we can nest them as we did with the document types. We'll add the ASPX and HTML code that will make up the masterpages in the next part of this series.