Umbraco Jump Start : Structure and Implementation

Part 1 : Umbraco Jump Start : Introduction and Configuration

This is the second article of our Umbraco jumpstart series. First part was about Configuration, This time we will be focusing on Umbraco structure and implementation. There are a lot of moving parts as far as Umbraco CMS is concerned. It’s simply awesome. You learn it, You use it you fall in love with it, that simple. We will only be covering a few of them which are necessary to get started and building your own Umbraco integrated web application. Before diving into Umbraco components, I’d like to introduce the Umbraco Routing mechanism first.

Umbraco Routing

Before explaining Umbraco routing mechanism, let’s have a glance at standard Asp.Net MVC routing. We have a routing.config file where we define our routes (there are other ways too). Most generic MVC routes are like /{Controller}/{Action}/{Id}/. Well, Umbraco doesn’t work that way. Umbraco routes are basically the relative path towards the content node (which we will discuss in detail shortly) down in hierarchy from the root node. So what you see in the browser is like http://mysite/aboutus/contactdetails/ where all of these are content nodes/pages.

Umbraco Components

We had configured our Umbraco website in previous article. Let’s dive into some details about Umbraco core components.

1. Templates

One line definition: Templates are your cshtml views. Templates are where we implement our dynamic content coming from umbraco. All the templates that you intend to use in umbraco need to be inherited from UmbracoTemplatePage Class. A dynamic object named CurrentPage is available that has all the data coming from content node in which the template has been assigned.

2. Content Nodes 

We can say content nodes are your web pages in Umbraco CMS. Basically, these are the pages in Umbraco dashboard in which you enter the dynamic data which is then populated and made available to the template for rendering. Every content node has its own Url through which you can access the web page in browser. For example, consider there is a content page about Contact Details which is under another content page About Us which is at the root level. Content Node hierarchy would be like:

  • My Site Root (Url: /)
    • About Us (/aboutus)
      • Contact Details (/aboutus/contactdetails/)

3. Document Types 

Consider a scenario where you need a web page in which you need to display a title, subtitle and some html content. Whereas another page requires testimony, some images and html content. Up till now, we know that content pages provide this data to template to render. But how does the content node knows about the fields it needs to include in itself from where we can enter the data. For Title, Subtitle, Html Content, It requires two textboxes (title and subtitle) and one richtext editor for htmlcontent to get input. This is where document type jumps in. Every content node has one document type. Which provides all these controls into the content node. Document type is the collection of all those fields that are required by the content node. For our basic page example. We need a document type that has three properties, title (textstring), subtitle(textstring) and html content (rich text editor). The content node created using this document type will have these three fields for inputing data.

4. Data Types

Data types are the types of properties used in document types. Examples are Text String, Richtext Editor, ImagePicker, Media Picker, Text Area, True/False etc. Custom types are also supported.

Note: There are tons of features Umbraco provides and hence there are lots of components in Umbraco CMS like stylesheets, macros, scripts, languages and partials etc. We are only discussing the core components that are ultimately necessary to get you started. Once you have got your wheels running, you can explore and use all these handy features as well.

Step by Step Implementation

Let’s develop our first Umbraco Page to understand the concepts and functionality with more clarity. We had setup the Umbraco website in our previous article. Let’s have some fun with it.

Step 1: Planning

Like everything else, Planning is the first step towards Umbraco development. Get yourself a clear vision what exactly you want in a website. Plan functionality, devise architecture, and list the web pages and what kind of content they are going to have. Group these pages on the basis of content similarity so that we can create generic types as much as possible. Let’s say for our practical example we need three pages. Home page, About page and a Contact us page. All of these pages need a Title, Subtitle and Html content. So first of all, we need a document type that can provide these three fields to our content nodes.

Step 2: Creating Templates

To consume the data that will be provided by content node, we need a template. Since we need three pages. A common understanding would be that we need three templates like home, about and contact. But consider the scenario where the schematics of the pages are same and only difference between them is the dynamically populated content. In that case we only need one implementation i.e. one template. So we will create one template named “General”.

  1. Create a new template under settings menu -> Templates by right clicking the menu item or simple clicking the icon.
  2. Click Create.
  3. Name the template and save. We named it "General".   
  4. If using visual studio, after creating a template (which is a cshtml view) you should go to the views folder in visual studio solution and include it to project. You may be needing to refresh the solution first for the excluded template to appear. 
  5. There is an option of creating a matching template along with the document type at the time of document type creation. Choice is yours…

Step 3: Creating Document Types

For our example, we need one document type. Let’s name it “Common”. See the screenshots to create the document type.

  1. Create a new document type under settings menu -> Document types by right clicking the menu item or clicking the icon.
  2. Hit Create and select Document Type without a template option.
  3. Enter the name and description for the Document Type.
  4. Create a new tab named Common Controls.
  5. Click Add property, Enter the name say "title" and description and click add editor.
  6. Select the required datatype for your property from Reuse tab. In our case we will use Textstring datatype.
  7. Create three properties which we need for our pages.
    1. Title(textstring)
    2. Subtitle(textstring)
    3. Html Content(Richtext editor).
  8. Navigate to permissions tab and check the Allow as Root option.
  9. Also add the datatype as a child under itself for implementing content node hierarchy (see the above screenshot).
  10. Navigate to templates tab and select allowed templates for this document type. Click on choose default template and select the template. In our case its general.
  11. Save the document type.

Step 4: Set Permissions

Before moving to content node creation there are a few permissions those are needed to be set.

  1. Under the created document type in “Templates” tab, select the allowed templates. In our case allow “General” Template in “Common” document type (We already did these steps while creating our document type).
  2. If you are going to implement the tree structure of nodes in your website, you need to allow document types hierarchy as well. In our scenario, we are going to create About and Contact content pages under Home page content node. All of these have same document type. So we have to allow “Common” document type under itself. Go to "Permissions" tab and allow the document types you want to allow under this document type.
  3. Under "Permissions" Tab there is an option named allow at root, set this for the document type which you are going to use to create root node, the master content page.

Step 5: Creating Content Nodes

All set, mission create content node is a go.

  1. Navigate to Content from Left menu, Right click on content menu item, Click create.
  2. Since we only have one document type available "Common", select that from the list.
  3. Name the page to Home, Add subtitle and a few lines in HTML Content section.
  4. Navigate to Properties Tab and select template for this content node, i.e. "General".
  5. Hit save and publish button.
  6. Go to properties tab in newly created node, You will see the generated URL for the node named as Link to document. Click it you will be navigated to the page. But what’s the problem, its empty! This is because we haven’t implemented display logic in our Template “General” yet.
  7. Similarly create About and Contact Pages under the Home Content Page.

Step 6: Implementing the Display Logic in Template (Finally some coding)

Now that we have got the content pages in place, we will be receiving dynamic content. All we need to do is to implement it in our template. How we want to display it in a template, the styling, formatting and everything is in our hands now. I am just putting a very simple code snippet in template to display dynamic data in our pages.

    <hr />

Save the template with this code. Now browse the content node again. You will see an amazingly formatted and styled page (wait, you didn't styled the page did you ;) )



Congratulations! You can now work with Umbraco. Umbraco rightly claims it the friendly CMS. We have followed very simple steps to create our own website and put some content in it dynamically. Play around with it. Find new problem statements and try to solve them. It will be a lot of fun. More you explore more you’ll learn it. The next article will the about troubleshooting and FAQ’s. Stay tuned.


comments powered by Disqus