Umbraco 5: Adding Dashboards via plugins

I'll add this post to the Umbraco 5 wiki in due course.

This blog post will describe how to add dashboards to Umbraco 5 via a plugin - before starting, consider the following useful background reading:

• http://blog.mattbrailsford.com/2011/09/30/automating-umbraco-v5-package-creation-using-msbuild/
• http://shazwazza.com/post/Umbraco-Jupiter-Plugins-Part-1.aspx

At time of writing (9th November 2011) some of the techniques used here require you to work from the latest Umbraco Jupiter source code - the example won't work with the latest alpha release.

Sample source code for the techniques described here are available at: http://umbraco5contrib.codeplex.com/ and you can get the source (mercurial) by cloning: https://hg01.codeplex.com/umbraco5contrib

The solution that this article refers to is in Source\Dashboard.HelloWorld.sln.  Please read ReadMe.txt  in the project root before building.

Obective:

To display a (Razor) view on and Umbraco 5 dashboard - using a custom controller provided by an Umbraco 5 plugin.

Plugin folder structure:

Plugins go in: App_Plugins\Packages\  for now we'll be copying from Visual Studio to this location using post build events. To package and redistribute a plugin you'll want to read Mat's article which is linked above.

In Dashboard.HelloWorld.csproj  you will need to modify the following XML to specify where you are running Umbraco 5 from.

<PropertyGroup>
    <Umbraco5Dir>C:\Users\Darren\Source\Umbraco\Source\Web Apps\Umbraco.CMS.Web.UI</Umbraco5Dir>
</PropertyGroup>

If you build the solution and browse to:

 App_Plugins\Packages\MyPackage.1.0  you should see the following child folders:

• lib (DLL files from your plugin)
• Views\Partial (Razor cshtml files from your plugin)

You'll also have a web.config at the root of your plugin folder. If you refresh the Umbraco back office you should see a Hello world view on your dashboard.

What makes this work:

The dashboard is defined in your plugin web.config - Umbraco Jupiter uses a technique known as deep config which means plugin cofig is merged with the main application configuration.

The dashboard snippet looks like this:

<umbraco.cms>
  <dashboard-groups>
    <group>
      <applications>
        <addapp="*"/>
      </applications>
      <dashboards>
        <addtab="Hello There people"type="childAction"name="Dashboard.Index"/>
      </dashboards>
    </group>
  </dashboard-groups>
</umbraco.cms>

The configuration above defines the following things:

• The Umbraco application/section to add the dashboard to (in this case * which means all)
• The tab title "Hello There people"
• The type - childAction for a controller - you can use partialView to display a Razor file directly.
• name - references the controller in the format Name.Action

How Umbraco 5 finds plugins:

In the solution open up AssemblyInfo.cs and note the inclusion of the following:

[assembly: AssemblyContainsPlugins()]

This attribute tells Umbraco to look inside this assembly for plugins.

Modifications to the controller:

Consider the controller in our project:

[Editor("960d4aaf-8fae-44da-a3ff-5a2430ee6e4a", HasChildActionDashboards = true)]
public class DashboardController : BaseEditorController
{
   public DashboardController(IBackOfficeRequestContext requestContext)
       : base(requestContext)
   {
   }

   [ChildActionOnly]
   public ActionResult Index()
   {
       return View("HelloWorld");
   }
}

The changes we've made in order for this to work on the dashboard are:

• Decorate the class with the Editor  attribute and provide a GUID
• In the Editor attribute pass in true to the HasChildActionDashboards property
• Inherit from the base class BaseEditorController
• Mark your action with the ChildActionOnly attribute