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
Comments
Shannon
Also note that when you just render a partialView instead of a child action that you don't need to have an assembly at all and therefore dont need to attribute one either.