This is the first in a series of articles about Umbraco designed to help ASP.Net MVC Developers hit the ground running. more articles will make their way here in the near future.

A brief introduction ...

Umbraco is an Open Source Content Management System (CMS) used as the foundation for many well recognised sites out there today. Essentially Umbraco is a platform that is designed not to get in your way - by this I mean there is no pre-defined content schema, no templates, and you're not locked into doing things "The Umbraco Way".

Sure, there are starter kits, and lately a default installation of Umbraco includes an implementation of the TXT from n33 for Html5Up starter kit; however you can remove it easily enough or build on it - your choice.

Since version 4.11, Umbraco has been transitioning from WebForms to MVC, with version 7 introducing an entirely new user experience for editors, designers and developers alike. Based on AngularJS and Bootstrap, developers can create their own data types and dashboards; creating a highly customised user experience experience for their clients.

First look - the Umbraco Backoffice

First look - the Umbraco Backoffice

Quick Links

Installing Umbraco in Visual Studio

There exist multiple ways to get up and running with Umbraco; from downloading a zip file and extracting it, or using WebMatrix and Web Platform Installer to install it as an application; or as NuGet packages inside a Visual Studio project. At Digitalsmith, our preferred method is to create a set of ASP.Net Web Applications - one for Umbraco, and one as a code library.

For the purposes of this exercise, I've just called my project "UmbracoDemo" - we'll use this name as the prefix for our projects. First, create two empty ASP.Net Web Applications in the solution - name one UmbracoProject.UI - this will contain the full Umbraco instance - and name the other UmbracoProject.Code which will contain our controllers, models, event handlers, and extensions etc.

Now we're going to install Umbraco through NuGet. In the PackageManager Console you can install it with the following command make sure you have the UmbracoProject.UI project set as the default):

PM> Install-Package UmbracoCms

Doing so will install the Umbraco CMS backoffice along with all of it's dependencies.

For the UmbracoProject.Code we do the same thing except we want to install the UmbracoCms.Core package instead which gives us access to the Umbraco API:

PM> Install-Package UmbracoCms.Core 

First Run - setting up the Umbraco Database

Now we're ready to start setting up Umbraco - go ahead and run (or just view) the UmbracoDemo.UI project:

First Run - installing Umbraco 7 simply consists of entering your user details and clicking Install.

First Run - installing Umbraco 7 simply consists of entering your user details and clicking Install.

Fill in the your user details (your email address is automatically used as your Login Name once the database is installed) and click Install. Once the installation process is complete, you'll be automatically logged in and ready to start creating your Document Types.

Customising the install

By default, Umbraco utilises a LocalDb version of SqlServer creating a database file Umbraco.sdf in the App_Data directory in the website. It also installs the Txt starter kit offering you a starting point for your own website to build upon complete with Document Types, Razor MVC Templates, CSS, and Partial Views. You can however customise this behaviour including specifying an Sql Server database (which could also be hosted in Azure) by clicking the Customize link beside the Install button.

You can remove the default Txt Starter Kit by going to Packages -> Installed Packages in the Developer section. Select the package and you will see an Uninstall package tab with a Confirm uninstall button at the bottom of the tab.

Next Steps - defining your site design

There are a lot of good resources available on the Umbraco Community Site and we won't go into setting up document types right now; however here's an overview:

Defining the content, structure, and theme of your website is done primarily in the Settings Section.
Here you can:

  • Define your Document Types - these literally define the structure of your content and the website.
  • Create and edit the CSS and Razor Templates
  • Create and edit JavaScript files (under Scripts)
  • Create Partial Views

An example of the Umbraco Settings Section is shown below:

Site Structure - defining document types

Site Structure - defining document types

Relating Umbraco back to MVC

We've installed Umbraco and started setting up our site structure, but how does all this relate to ASP.Net MVC Developers? How do we grab the information out of Umbraco and use it to build our page content, our Partial Views, and leverage it in our Controllers?

Umbraco has a very rich API for managing Content, Members, Media and pretty much everything else accessible in the Umbraco BackOffice.

All of our code should be created in the __*.Code__ project (in this example, it's UmbracoDemo.Code) as per a standard ASP.Net MVC project with one exception - instead of placing the Views in this project, place them instead in the Views Directory of the UmbracoDemo.UI project.

Using Controllers

Now lets talk about the Controllers. Umbraco implements two main types of controllers.

The SurfaceController

Surface Controllers are Umbraco’s implementation of the standard MVC Controller. Reasonably comprehensive documentation can be found here: http://our.umbraco.org/documentation/reference/Templating/Mvc/surface-controllers

A SurfaceController exposes the following properties of interest. There are other Umbraco specific properties and extensions, but these are the most widely used:

  • Umbraco – Helper object (UmbracoHelper) which provides methods for querying and retrieving specific Content and Media nodes as IPublishedContent or its dynamic equivalent. Documentation on UmbracoHelper can be found here: http://our.umbraco.org/Documentation/Reference/Querying/UmbracoHelper/index
  • Members – Helper object (MembershipHelper) for working with Umbraco Members. It exposes methods to assist in registering and managing membership profiles but also to determine who is logged in. Documentation for MembershipHelper can be found here: http://our.umbraco.org/Documentation/Reference/Querying/MemberShipHelper/index
  • CurrentPage – A reference to the current Page or Content Node as an IPublishedContent object.
  • Services – Context object referencing singleton instances of each Core Service. The Services enable the creation and manipulation of Umbraco objects – Content, Media, Members, etc. If you want an Action to create, modify or delete content, this is where you want to go. You'll find documentation on many of the available services here: http://our.umbraco.org/search?q=Services&content=documentation

Actions on SurfaceControllers can be rendered in the normal way as follows:

@Html.Action("Login", "Membership")

The UmbracoApiController

Umbraco Api Controllers are Umbraco’s implementation of the APIController and are currently based on WebAPI version 1.

There are a few important considerations when using UmbracoApiController compared to SurfaceController – the most significant being that there is no CurrentPage property available, as an UmbracoApiController lacks the necessary page context.

Many of the other properties available on a SurfaceController are also available on an UmbracoApiController. The documentation for UmbracoApiController can be found here: http://our.umbraco.org/Documentation/Reference/WebApi/index

Routing

SurfaceControllers are routed automatically, and if you're developing a plugin, there's class attributes designed help with routing here too.

Umbraco also supports Route Hijacking - the ability to take over a standard Umbraco route to inject your own logic and models into an Umbraco page Template. This topic is beyond the scope of this article for the moment though.

UmbracoApiControllers are normally routed based on /umbraco/api – for example, a GetSearchResults action on a SearchApiController would be accessible as follows:

http://mydomain.com.au/umbraco/api/SearchApi/GetSearchResults?query=term

Models - Getting information from Umbraco onto the View

The UmbracoHelper mentioned above object allows you to query the published content of the website, returning objects as either IPublishedContent or a dynamic version of it. You can find current information about querying the published content cache using UmbracoHelper here: http://our.umbraco.org/documentation/reference/querying/UmbracoHelper/

Knowing what's available from the UmbracoHelper is essential, and the reader is encouraged to review the documentation referenced above.

IPublishedContent exposes the following properties and methods (there are more, these are the most commonly used ones):

Standard Properties:

  • Id
  • Name – the title or name given to the object.
  • Url
  • ParentId – the Id of the parent object. __Note:__ Members don't have a parent node as such. Content and Media do.
  • Properties – a collection of IPublishedPropery that exposes user-defined properties of the node.

Methods:

  • GetPropertyValue('alias') – retrieves a typed version of the value of the specified property. This is an extension method in the Umbraco.Web namespace.
  • GetPropertyValue('alias', recurse) – same as the above method, however this version allows you to retrieve the value of a parent (Ancestor) node if it doesn't exist on the current node.

There are a lot more convenience extension methods available that help do things like retrieve child or parent nodes of a particular Content Type, or return the position of the item in the tree structure of the published content.

Templating - Content and Views

Page Templates

A standard Umbraco Template is a Razor file inheriting Umbraco.Web.Mvc.UmbracoTemplatePage. The Default Model of an UmbracoTemplatePage is Umbraco.Web.Models.RenderModel.

The Model exposes the Content property, which is an IPublishedContent object representing the current page. In addition, UmbracoTemplatePage exposes the following properties (some of which are discussed under Surface Controllers above):

  • Umbraco – Helper object (UmbracoHelper) which provides methods for querying and retrieving specific Content and Media nodes as IPublishedContent or its dynamic equivalent.
  • Members – Helper object (MembershipHelper) for working with Umbraco Members. It exposes methods to assist in registering and managing membership profiles but also to determine who is logged in.
  • CurrentPage – A reference to the current Page or Content Node as a dynamic instance of the IPublishedContent object. __Note:__ this is different to the CurrentPage property on the SurfaceController.

Partial & Action Views

A Partial View may inherit from Umbraco.Web.Mvc.UmbracoViewPage which exposes most of the same properties as an UmbracoTemplatePage used by Page Templates. The exception to this is the CurrentPage property, which is not present.

It’s worth noting that SurfaceController Action Views should also inherit from the strongly typed version as follows:

Umbraco.Web.Mvc.UmbracoViewPage

Documentation on Page Templates and Partial Views can be found at http://our.umbraco.org/Documentation/Reference/Templating/Mvc/partial-views - while this was written for Umbraco 4.10+, it still largely applies to Umbraco 7.

Conclusion

We've only just scratched the surface of what's available as an ASP.Net MVC developer in Umbraco, and there are many areas left untouched or just skimmed over. Hopefully though this article gives the reader a basic understanding of what's available, and where to go for more information.

The Umbraco Community is a vibrant one, with plenty of information and a strong commitment to the ongoing success of Umbraco. One of the best things I ever did when starting out was to join up on the Community Website and start asking questions. I frequently go back to see what new packages are available, as there is a wealth of packages available to extend Umbraco's functionality and generally make life easier.

If you've found this guide helpful, or it's opened up more questions, feel free to leave a comment below, or contact me anytime: