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:

There are 5 parts to Shannon's series on Umbraco jupiter plugins.

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:

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:

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:

Comments

Leave a comment