Shazwazza

Shannon Deminick's blog all about .Net, Umbraco & Web development

Umbraco Jupiter Plugins - Part 5 - Surface Controllers

November 29, 2011 13:31 by Shannon Deminick

This is the fifth blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter). This post will explain what a Surface Controller is, what they can be used for and how to create one.

Disclaimer

This post is about developing for Umbraco v5 (Jupiter) which at the time of this post is still under development. The technical details described below may change by the time Umbraco Jupiter is released. If you have feedback on the technical implementation details, please comment below.

Related Posts:

  1. Umbraco Jupiter Plugins – Part 1
  2. Umbraco Jupiter Plugins – Part 2 – Routing
  3. Umbraco Jupiter Pluings – Part 3 – Trees
  4. Umbraco Jupiter Pluings – Part 4 – Editors

What is a Surface Controller?

A Surface Controller is an MVC controller that interacts with the front-end (or render layer) of Umbraco. An example of a Surface Controller could be a controller that has a Child Action used to display a Twitter Feed, or a controller that has an Action to accept some posted information from a form. Child Actions on Surface Controller will probably be primarily used for Child Action Macros in Umbraco v5.

Since Surface Controllers are plugins, this means that you can create a package that contains Surface Controllers to distribute whatever front-end functionality you like to Umbraco developers. Surface Controllers, just like Tree Controllers and Editor Controllers get automatically routed for you.

Creating a Surface Controller

Important convention: All Surface controller names MUST be suffixed with ‘SurfaceController’. For example, if you are creating a Surface Controller to display system a Twitter feed, you might call your controller: TwitterFeedSurfaceController. If you don’t follow this convention, you’re surface controller wont be routed.

The first step is to create a class that inherits from the base Surface Controller class:  Umbraco.Cms.Web.Surface.SurfaceController

The next step is to define some MVC Action’s to do whatever it is you’d like them to do. Here’s some examples:

  • Creating an action to partake in a Child Action Macro. To define this is very simple and follows the exact same MVC principles to creating a Child Action… just add a ChildActionOnlyAttribute to your action method:
[ChildActionOnly]
public ActionResult DisplayTwitterFeed()
  • Creating a child action to simply be used as a normal MVC child action which get rendered using @Html.Action or @Html.RenderAction
  • Create an action to handle some posted form data:
[HttpPost]
public ActionResult HandleMyFormSubmission(MyFormModel model) 
  • Maybe you’d like to track all links clicked on your page. You could use jquery to update all of your links on your page to point to your custom action URL with the real URL as a query string. Then your custom action will log the real link address and redirect the user to where they want to go.

Plugins vs Non-plugins

A Surface Controller ‘can’ be a plugin, meaning that you can create it as a plugin and distribute it as part of a package. However, if you are creating your own Umbraco website and do your development in Visual Studio like most of us, you don’t need to create a Surface Controller with a plugin definition and install it as part of a package, you can just define it locally just like a controller in a normal MVC project. If you do want to ship your Surface Controller as part of a package then you must attribute your Surface Controller with the SurfaceAttribute, and give it an Id. If you don’t do this then Umbraco will detect that its loading a Surface Controller plugin without an Id and throw an exception.

As a plugin

Standard practice for creating any kind of controller is to put your controllers in the ‘Controllers’ folder (this is not mandatory but a simple convention to follow). So If you’ve created a new project in Visual Studio, you’d create a folder called ‘Controllers’, then create your Surface Controller class with the SurfaceAttribute and an Id:

using System.Web.Mvc;
using Umbraco.Cms.Web.Context;
using Umbraco.Cms.Web.Surface;
using Umbraco.Framework;

namespace MyProject.Controllers
{
    [Surface("98625300-6DF0-41AF-A432-83BD0232815A")]
    public class TwitterFeedSurfaceController : SurfaceController
    {

    }
}

Because this Surface Controller is a plugin, you’ll need to attribute your project assembly (just like when creating Trees or Editor plugins). You can declare this in any of your classes or in the AssemblyInfo.cs file.

[assembly: AssemblyContainsPlugins]

As a locally declared Surface Controller

This is pretty much identical to the above but you don’t have to include the SurfaceAttribute or attribute your assembly. If you’ve got an Umbraco v5 website that you’re working on you should just create a ~/Controllers folder to put your controller in, just as if you were creating a normal MVC project. Then you can create your Surface Controller:

using System.Web.Mvc;
using Umbraco.Cms.Web.Context;
using Umbraco.Cms.Web.Surface;
using Umbraco.Framework;

namespace MyProject.Controllers
{
    public class TwitterFeedSurfaceController : SurfaceController
    {

    }
}

Using a Surface Controller

The usage of a Surface Controller really depends on what you’ve created your surface controller to do. Probably the 3 main ways to use them will be:

  • Create a ChildAction Macro by using the Macro UI in the back office and selecting a child action that you’ve declared on your Surface Controller, then render the macro in your template or inline in the WYSIWYG editor.
  • Directly render a child action declared on your Surface Controller by using @Html.Action or @Html.RenderAction
  • Create an Html form to post data to an action on your Surface Controller using @Html.BeginUmbracoForm (more on this in the next blog post!)

Umbraco Jupiter Plugins - Part 4 - Editors

September 27, 2011 05:56 by Shannon Deminick

This is the fourth blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter). This post will show you how to get started with building an editor. An Editor is the term used to express the editing pane on the right hand side of the back-office. Examples include: the content editor, media editor, document type editor, script editor, etc..

Related Posts:

  1. Umbraco Jupiter Plugins – Part 1
  2. Umbraco Jupiter Plugins – Part 2 – Routing
  3. Umbraco Jupiter Pluings – Part 3 – Trees

Disclaimer

This post is about developing for Umbraco v5 (Jupiter) which at the time of this post is still under development. The technical details described below may change by the time Umbraco Jupiter is released. If you have feedback on the technical implementation details, please comment below.

Defining an Editor

An Editor in Umbraco v5 is the combination of: An MVC Controller, View(s), JavaScript and CSS. The first step to creating an Editor is to create a class that inherits from the Umbraco base editor class: Umbraco.Cms.Web.Editors.StandardEditorController. 

The next step is to register this editor as an editor plugin. To do this you just need to add an attribute to your class such as:

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]

The mandatory parameter passed to this attribute is the editor plugin ID (this MUST be unique so ensure you generated a new GUID for every single one of your plugins).

The next thing you’ll need to do to ensure your editor plugin is found and loaded is to ‘advertise’ that your assembly contains a plugin. To do this, just edit your assembly’s AssemblyInfo.cs file and add the following attribute:

[assembly: AssemblyContainsPlugins]

Creating an Editor

Important convention: All Editor controller names MUST be suffixed with ‘EditorController’. For example, if you are creating an editor to display system information, you might call your Editor: SystemInfoEditorController. If you don’t follow this convention, you’re editor controller wont be routed.

When creating an Editor there are a few base classes to choose from. Generally however, you should inherit from: Umbraco.Cms.Web.Editors.StandardEditorController. The other base classes and their hierarchy are as follows:

  • Umbraco.Cms.Web.Mvc.Controllers.BackOffice.SecuredBackOfficeController
    • Umbraco.Cms.Web.Editors.BaseEditorController
      • Umbraco.Cms.Web.Editors.DashboardEditorController
        • Umbraco.Cms.Web.Editors.StandardEditorController

When inheriting from any of the base classes above, you will be required to create a constructor accepting an parameter of type: IBackOfficeRequestContext :

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]
public class MyEditorController : StandardEditorController
{
    public MyEditorController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }        
}

The StandardEditorController has an abstract method: Edit(HiveId id) that needs to be implemented (the abstract Edit Action is marked as [HttpGet])

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]
public class MyEditorController : StandardEditorController
{
    public MyEditorController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }
        
    public override ActionResult Edit(HiveId id)
    {
        return View();
    }
}

Most Editors will be displaying a view to edit data based on a HiveId which is the unique identifier type for pretty much all data in Umbraco 5. If you are writing an editor to edit data in a custom Hive provider, then this will work seamlessly for you. Even if you are creating an editor for data that you aren’t writing a custom Hive provider for, you can still use HiveId as a unique identifier since it has support for wrapping Guid, Int and String Id types. If however you decide that HiveId isn’t for you, then you can inherit from one of the other editor base classes that doesn’t have the abstract Edit method attached to it and create your own Actions with your own parameters.

The above Edit Action simply returns a view without a model to be rendered. At this point, you’ll need to know where your view should be stored which has everything to do with MVC Areas or embedding views.

MVC Areas & Jupiter Packages

In a previous post we talk about how packages in v5 are actually registered as their own MVC Area. All packages get installed to the following location: ~/App_Plugins/Packages/{YourPackageName} . If you aren’t embedding your views, then they should be stored inside of your package folder. Each plugin type has a specific view folder name that your views should be stored in:

  • Editor views & partial views:
    • ~/App_Plugins/Packages/{YourPackageName}/Editors/Views/ {EditorControllerName}/{ViewName}.cshtml
    • ~/App_Plugins/Packages/{YourPackageName}/Editors/Views/Shared/ {ViewName}.cshtml
  • Property Editor partial views:
    • ~/App_Plugins/Packages/{YourPackageName}/PropertyEditors/Views/Shared/ {ViewName}.cshtml
  • Dashboard partial views:
    • ~/App_Plugins/Packages/{YourPackageName}/Dashboards/Views/ {ViewName}.cshtml
  • Rendering (front-end) partial views:
    • ~/App_Plugins/Packages/{YourPackageName}/Views/Partial/ {ViewName}.cshtml

So with the controller created above, I would have a view in the following location:

~/App_Plugins/{MyPackageName}/Editors/Views/MyEditor/Edit.cshtml

NOTE: The package name folder will be created when installing your NuGet package and will be based on your NuGet package name and version assigned.

Embedding views

Many of the views shipped with v5 are embedded which helps to reduce the number of actual files that are shipped. This is also handy if you don’t want to give the ability for people to change what’s in your markup.

Embedding a view is really easy:

  • Create a Razor (.cshtml) view in your Package’s project
  • View the Properties for this file and choose ‘Embedded Resource’ as the ‘Build Action’

Now to use the embedded view we use the following syntax:

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]
public class MyEditorController : StandardEditorController
{
    public MyEditorController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }
        
    public override ActionResult Edit(HiveId id)
    {
        return View(EmbeddedViewPath.Create("MyProject.Editors.Views.Edit.cshtml"));
    }
}

Its important to get the correct path to your view file. In this instance, my view’s path in my project is: MyProject.Editors.Views.Edit.cshtml

Displaying your Editor

Most of the time an editor is displayed by clicking on a node in the tree or by accessing a context menu item. In a previous post about creating trees there was a method to create a tree node:

protected override UmbracoTreeResult GetTreeData(HiveEntityUri id, FormCollection queryStrings)
{
    NodeCollection.Add(
        CreateTreeNode(id, null, "My only node", string.Empty, false));
    return UmbracoTree();
}

This simply created a tree node that had no editor URL but now that we have an editor, I’ll update the code to click through to my Edit Action:

protected override UmbracoTreeResult GetTreeData(HiveId id, FormCollection queryStrings)
{
    NodeCollection.Add(
        CreateTreeNode(id, null, "My only node",
        Url.GetEditorUrl("MyEditor", id, new Guid("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")),
        false));
    return UmbracoTree();
}
GetEditorUrl is an extension method of UrlHelper which has a few overloads for generating an Editor’s Url. In this case we are passing in the Editor’s name and Id with the Id of the current node being rendered in the tree.

When the node is clicked it will now link to the Edit Action of the MyEditor Controller.

Umbraco Jupiter Plugins - Part 3 - Trees

August 20, 2011 02:09 by Shannon Deminick

This is the third blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter).  This post will show you how to get started with building a tree. A more in-depth example including rendering out child nodes, using many of the inbuilt helper/extension methods will come in a future blog, though in the meantime once you’ve read this post if you want to see more in-depth examples you can easily find them in our v5 source code.

Related Posts:

  1. Umbraco Jupiter Plugins – Part 1
  2. Umbraco Jupiter Plugins – Part 2 - Routing

Disclaimer

This post is about developing for Umbraco v5 (Jupiter) which at the time of this post is still under development. The technical details described below may change by the time Umbraco Jupiter is released. If you have feedback on the technical implementation details, please comment below.

Defining a tree

A tree in Umbraco v5 is actually an MVC Controller that returns JSON data. The first step to creating a tree is to create a class for your tree that inherits from the Umbraco base tree controller class: Umbraco.Cms.Web.Trees.TreeController

Important convention: All Tree controller names MUST be suffixed with ‘TreeController’. For example, if you are creating a tree to display system information, you might call your Tree: SystemInfoTreeController. If you don’t follow this convention, your tree controller won’t be routed.

The next step is to register this tree as a tree plugin. To do this you just need to add an attribute to your class such as:

[Tree("A18108B1-9C86-4B47-AC04-A3089FE8D3EA", "My Custom Tree")]

The two parameters passed to this attribute are:

  • The tree plugin ID (this MUST be unique so ensure you generated a new GUID for every single one of your plugins)
  • The tree title. This will be the text rendered for the root node of your tree, however, this can be overridden and you could render out any title that you wish for your root node and it could even be dynamic. Also note that we will be supporting localization for the tree title.

The next thing you’ll need to do to ensure your tree plugin is found and loaded is to ‘advertise’ that your assembly contains a tree plugin. To do this, just edit your assembly’s AssemblyInfo.cs file and add the following attribute:

//mark assembly for export as a tree plugin
[assembly: TreePluginAssembly]
[assembly: AssemblyContainsPlugins]

Creating a tree

Constructor

When inheriting from the base Umbraco.Cms.Web.Trees.TreeController, you will be required to create a constructor accepting an parameter of type: IBackOfficeRequestContext :

[Tree("A18108B1-9C86-4B47-AC04-A3089FE8D3EA", "My Custom Tree")]
public class MyTreeController : TreeController
{
    public MyTreeController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }

    //more code will go here....
    
}

The IBackOfficeRequestContext will most likely contain references to everything you’ll need to get the data for your tree. It includes references to:

  • Hive
  • Umbraco settings
  • The TextManager (localization framework)
  • All of the registered plugins in the system
  • … and a whole lot more

However, you’ll be please to know that all plugins including Trees can take part in IoC contructor injection. So, if you want more objects injected into your tree controller you can just add the parameters to your constructor and they’ll be injected so long as they exist in the IoC container.

Overriding methods/properties

There is one property and one method you need to override:

RootNodeId

This property is just a getter and returns the root node id for your tree. Many trees exist at the absolute root of the data which is called the SystemRoot. An example of a tree that exists at the system root would be trees like the: Data Type tree, Macro tree, Packages tree, tc… since they don’t have a heirarchy. Tree’s that have different start node Ids are trees like: Content, Media and Users.  Since each one of those entities share the same data structure, we separate these data structures under different start nodes from the SystemRoot.

For the most part, if you are creating a utility type tree or a custom tree that doesn’t exist under a special hierarchy, the SystemRoot is what you’ll want:

protected override HiveEntityUri RootNodeId
{
    get { return FixedHiveIds.SystemRoot; }
}

GetTreeData

This method is the method that returns the JSON tree data though to make it easy you don’t have to worry about JSON whatsoever. All you need to do is add TreeNode objects to the existing NodeCollection of the tree controller.

As a very simple example, if you wanted to render out one node in your tree you could do this:

protected override UmbracoTreeResult GetTreeData(HiveEntityUri id, FormCollection queryStrings)
{
    NodeCollection.Add(
        CreateTreeNode(id, null, "My only node", string.Empty, false));
    return UmbracoTree();
}

The CreateTreeNode is a helper method which is part of the base TreeController class that has many useful overloads. In this example, we’re giving it an id, not passing in any custom query string parameters, a title, not giving it an editor url and tagging the node as not having any children.

Registering a tree

In order to get your tree to show up in the back office, you need to register the tree in the config file: ~/App_Data/Umbraco/Config/umbraco.cms.trees.config , and here’s all you need to do to put it in the ‘settings’ app (as an example):

<add application="settings" 
     controllerType="MyProject.MyTreeController, MyProject" />

NOTE: At CodeGarden we discussed that you can ship your plugin inside a package and have your own config file deployed which Umbraco will recognize so that you don’t have to edit the already existing file…. This is still true! But we’ll write another blog post about that Smile

More in depth example?

As I mentioned at the start of this post I’ll write another one detailing our many extension and helper methods when rendering out trees, how to add menu items to your nodes, customize your icons, change the editor for particular nodes, etc… In the meantime though, please have a look at the v5 source code, the trees all exist in the project: Umbraco.Cms.Web.Trees

Partial View macros in Umbraco v5

August 17, 2011 16:00 by Shannon Deminick

Disclaimer

This post is about developing for Umbraco v5 (Jupiter) which at the time of this post is still under development. The technical details described below may change by the time Umbraco Jupiter is released. If you have feedback on the technical implementation details, please comment below.

Macro Types

In Umbraco v5, there are currently 3 types of Macros:

  • Xslt
  • Partial View
  • Surface Action

The Xslt macro will remain very similar to the v4 Xslt macro, but the 2 other types are brand new. This post will cover the new Partial View Macro.

A Partial View in MVC is sort of synonymous with a User Control in WebForms. Its simply just a Razor view as a cshtml file. If you like Umbraco v4’s Razor macros, then you’ll be pleased to know that Razor is absolutely native to v5 and the Partial View Macro will be one of your best tools for working with v5.

Creating a Partial View macro

The first thing you’ll have to do is create the partial view, which you will need to save in the ~/Views/Umbraco/Partial folder. Next, a partial view macro needs to inherit from a custom view type, so the declaration at the top of your view will need to be:

@inherits PartialViewMacro

Then, just like in v4, you’ll need to create a new macro in the Developer section of the Umbraco back office. The Macro Property interface looks very similar in v5:

image

You’ll notice its slightly simplified as compared to v4. The 2nd drop down list dynamically changes based on the Macro Type drop down list value.

Once you’ve saved the macro, that’s it, your Macro is now created!

Using a Partial View macro

The razor syntax for rendering a macro in v5 is:

@Html.UmbracoMacro("blah")

As noted before, a Partial View Macro inherits from the view type: PartialViewMacro . This view object contains a Model property of type: Umbraco.Cms.Model.PartialViewMacroModel which has a couple of properties you can use to render data to the page:

public Content CurrentNode { get; }
public dynamic MacroParameters { get; }

The CurrentNode property is very similar to v4’s currentPage parameter in Xslt. It will allow you to traverse the tree and render any content you like. Here’s one way that you could list the child names from the current node:

<h2>Names of child nodes</h2>
@foreach (var child in Model.CurrentNode.ChildContent().AsDynamic())
{
    <p>
        Child node name: <b>@child.Name</b>
    </p>
}

Dynamic parameters

As you can see above, there’s a MacroParameters property on the PartialViewMacroModel which is a dynamic property just like MVC’s ViewBag. Passing data into the MacroParameters property can be done in your Macro declaration like so:

@Html.UmbracoMacro("blah", new { IsCool = true, MyParameterName = new MyObject() })

This means that you can pass any type of object that you’d like into your macro with any parameter name. Then to use the parameters that you’ve passed in, you can reference them directly by name inside your macro:

<ul>
    <li>@Model.MacroParameters.IsCool</li>
    <li>@Model.MacroParameters.MyParameterName.ToString()</li>
</ul>

Macro parameters via the Macro Editor

A cool new feature in v5 is the new Macro parameter editor. It can now pre-populate all macro parameters found in Xslt, Partial Views and Surface controllers. Better still, is that the parameter editor has been completely rebuilt with Knockout JS so you can add/remove as many parameters as you like at once and then finally post your changes back when hitting save.

image

Oh, and another great feature in v5 is that the editors for macro parameters are actually just v5 Property Editors that are attributed as Macro Parameter Editors.

Strongly typed parameters

You may be wondering how the Macro Editor populates parameters from a Partial View Macro since we’ve seen that Partial View Macro model only supports dynamic (non stongly typed) properties… The answer is in Razor. Razor views allow you to define public properties, methods, etc… inside of the Razor markup. So if we want to have strongly typed parameters for our Partial View Macros which can be set based on Macro parameters in the rich text editor, all we have to do is declare them like:

@inherits PartialViewMacro

@functions {

    public bool IsCool { get; set; }
    
}

Now, the Partial View has a discoverable property which our Macro Editor will be able to see and automatically populate the parameter list. This property will also be set with any value that is selected in the Macro Parameter Editor when inserting one into the rich text box. Another thing to note is that if you are simply injecting parameter values using the Html.Macro helper, then this property will be set so long as a dynamic property of the same name exists in the macro’s MacroParameter model properties.

Umbraco Jupiter Plugins - Part 2 - Routing

May 11, 2011 08:26 by Shannon Deminick

This is the second blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter).

Related Posts:

  1. Umbraco Jupiter Plugins – Part 1

Disclaimer

This post is about developing for Umbraco v5 (Jupiter) which at the time of this post is still under development. The technical details described below may change by the time Umbraco Jupiter is released. If you have feedback on the technical implementation details, please comment below.

Routing & URLs

As mentioned in the previous post Umbraco Jupiter will consist of many types of plugins, and of those plugins many of them exist as MVC Controllers.  Each controller has an Action which a URL is routed to, this means that each Controller plugin in Jupiter requires it’s own unique URLs. The good news is that you as a package developer need not worry about managing these URLs and routes, Jupiter will conveniently do all of this for you.

Packages & Areas

My previous post mentioned that a ‘Package’ in Jupiter is a collection of ‘Plugins’ and as it turns out, Plugins can’t really function unless they are part of a Package. In it’s simplest form, a Package in v5 is a folder which contains Plugins that exists in the ~/Plugins/Packages sub folder. The folder name of the package becomes very important because it is used in setting up the routes to  create the unique URLs which map to the MVC Controller plugins. Package developers should be aware that they should name their folder to something that is reasonably unique so it doesn’t overlap with other Package folder names. During package installation, Jupiter will check for uniqueness in Package folder names to ensure there is no overlap (there will be an entirely separate post on how to create deployment packages and how to install them).

Here’s a quick example: If I have a Package that contains a Tree plugin called TestTree (which is in fact an MVC Controller) and I’ve called my Package folder ‘Shazwazza’, which exists at ~/Plugins/Packages/Shazwazza then the URL to return the JSON for the tree is: http://localhost/Umbraco/Shazwazza/Trees/TestTree/Index 

Similarly, if I have a Editor plugin called TestEditor with an action called Edit, then a URL to render the Edit Action is:

http://localhost/Umbraco/Shazwazza/Editors/TestEditor/Edit

If you’ve worked with MVC, you’ll probably know what an MVC Area is. The way that Jupiter creates the routes for Packages/Plugins is by creating an MVC Area for each Package. This is how it deals with the probability that different Package developers may create MVC Controllers with the same name. MVC routes are generally based just on a Controller name and an Action name which wouldn’t really work for us because there’s bound to be overlap amongst Package developers, so by creating an Area for each Package the route becomes unique to a combination of Controller name, Action name and Area name.  MVC also determines where to look for Views based on Area name which solves another issue of multiple Packages installed with the same View names.

Whats next?

In the coming blog posts I’ll talk about

  • how plugins are installed and loaded
  • how and where the Views are stored that the plugins reference
  • how to create all of the different types of plugins

Code Garden 2011

I’ll be doing a talk on Plugins for Umbraco Jupiter at Code Garden 2011 this year which will go in to a lot more detail than these blog posts. If you are attending Code Garden already, then hopefully this series will give you a head start on Umbraco v5. If you haven’t got your tickets to Code Garden yet, what are you waiting for?! We have so much information to share with you :)

Umbraco Jupiter Plugins - Part 1

April 29, 2011 09:55 by Shannon Deminick

This is the first blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter)

Disclaimer

This post is about developing for Umbraco v5 (Jupiter) which at the time of this post is still under development. The technical details described below may change by the time Umbraco Jupiter is released. If you have feedback on the technical implementation details, please comment below.

What is a plugin

Since Umbraco Jupiter has been built from the ground up, we first need to define some v5 terminology:

  • Plugin = A single functional component that extends Umbraco such as a Tree, an Editor, a Menu Item, etc…
  • Package = A group of Plugins installed into Umbraco via the ~/Plugins/Packages/[Package Name] folder

The Umbraco v5 back-office has been architected to run entirely on Plugins, in fact the core trees, editors, etc… that are shipped with Umbraco are Plugins in v5.

Types of plugins

The list of Plugin types will most likely increase from the time of this blog post to when Jupiter is launched but as it stands now here are the types of Plugins supported in v5:

  • Property Editors
    • This term is new to v5. In v4.x there was no differentiation between a Data Type and it’s underlying ‘Data Type’ editor. In v5 we’ve made a clear distinction between a ‘Data Type’ (as seen in the Data Type tree and used as properties for Document Types) and the underlying editor and pre-value editor that it exposes.  An example of a Property Editor would be uComponents’ Multi-Node Tree Picker. An example of a Data Type would be when an Umbraco administrator creates a new Data Type node in the Data Type tree and assigns the Multi-Node Tree Picker as it’s Property Editor.
    • So uComponents Team, this is where you need to focus your efforts for version 5!
  • Menu Items
    • Context menu items such as Create, Publish, Audit Trail, etc… are all plugins.
    • See this post in regards to creating menu items in v5, though there have been some new features added since that article was created which I’ll detail in coming posts in this series.
  • Editors
    • Editor plugins are all of the interactions performed in the right hand editor panel and in modal dialogs in the back-office.
    • For example, the Content Editor core plugin in v5 manages the rendering for all views such as editing content, sorting, copying, and moving nodes, and nearly all of the other views that the context menu actions render.
    • Editors are comprised mostly of MVC Controllers, Views, JavaScript & CSS.
  • Trees
    • All trees are plugins, for example, the Content tree, Media tree, Document Type tree are all different plugins.
    • Trees are actually MVC controllers.
    • Tree nodes use Menu Items to render Editors
  •  Presentation Addins (Yet to be officially named)
    • Another type of plugin are Controllers that are installed via packages that interact with the presentation layer, an example of this might be the Controller Action that accepts the post values from a Contour form.

Whats next?

In the coming blog posts I’ll talk about

  • how plugins are installed and loaded
  • how the Umbraco routing system works with all of these controllers
  • how and where the Views are stored that the plugins reference
  • how to create all of the different types of plugins

Code Garden 2011

I’ll be doing a talk on Plugins for Umbraco Jupiter at Code Garden 2011 this year which will go in to a lot more detail than these blog posts. If you are attending Code Garden already, then hopefully this series will give you a head start on Umbraco v5. If you haven’t got your tickets to Code Garden yet, what are you waiting for?! We have so much information to share with you :)

Ultra fast media performance in Umbraco

April 25, 2011 00:24 by Shannon Deminick

There’s a few different ways to query Umbraco for media: using the new Media(int) API , using the umbraco.library.GetMedia(int, false) API or querying for media with Examine. I suppose there’s quite a few people out there that don’t use Examine yet and therefore don’t know that all of the media information is actually stored there too! The problem with the first 2 methods listed above is that they make database queries, the 2nd method is slightly better because it has built in caching, but the Examine method is by far the fastest and most efficient.

The following table shows you the different caveats that each option has:

new Media(int)

library.GetMedia(int,false)

Examine

Makes DB calls

yes

yes

no

Caches result

no

yes

no

Real time data

yes

yes

no

You might note that Examine doesn’t cache the result whereas the GetMedia call does, but don’t let this fool you because the Examine searcher that returns the result will be nearly as fast as ‘In cache’ data but won’t require the additional memory that the GetMedia cache does. The other thing to note is that Examine doesn’t have real time data. This means that if an administrator creates/saves a new media item it won’t show up in the Examine index instantaneously, instead it may take up to a minute to be ingested into the index. Lastly, its obvious that the new Media(int) API isn’t a very good way of accessing Umbraco media because it makes a few database calls per media item and also doesn’t cache the result.

Examine would be the ideal way to access your media if it was real time, so instead, we’ll combine the efforts of Examine and library.GetMedia(int,false) APIs. First will check if Examine has the data, and if not, revert to the GetMedia API. This method will do this for us and return a new object called MediaValues which simply contains a Name and Values property:

First here’s the usage of the new API below:

var media = MediaHelper.GetUmbracoMedia(1234); var mediaFile = media["umbracoFile"];

That’s a pretty easy way to access media. Now, here’s the code to make it work:

public static MediaValues GetUmbracoMedia(int id) { //first check in Examine as this is WAY faster var criteria = ExamineManager.Instance .SearchProviderCollection["InternalSearcher"] .CreateSearchCriteria("media"); var filter = criteria.Id(id); var results = ExamineManager .Instance.SearchProviderCollection["InternalSearcher"] .Search(filter.Compile()); if (results.Any()) { return new MediaValues(results.First()); } var media = umbraco.library.GetMedia(id, false); if (media != null && media.Current != null) { media.MoveNext(); return new MediaValues(media.Current); } return null; }

 

The MediaValues class definition:

public class MediaValues { public MediaValues(XPathNavigator xpath) { if (xpath == null) throw new ArgumentNullException("xpath"); Name = xpath.GetAttribute("nodeName", ""); Values = new Dictionary<string, string>(); var result = xpath.SelectChildren(XPathNodeType.Element); while(result.MoveNext()) { if (result.Current != null && !result.Current.HasAttributes) { Values.Add(result.Current.Name, result.Current.Value); } } } public MediaValues(SearchResult result) { if (result == null) throw new ArgumentNullException("result"); Name = result.Fields["nodeName"]; Values = result.Fields; } public string Name { get; private set; } public IDictionary<string, string> Values { get; private set; } }

That’s it! Now you have the benefits of Examine’s ultra fast data access and real-time data in case it hasn’t made it into Examine’s index yet.

HtmlHelper Table methods

April 22, 2011 09:29 by Shannon Deminick

I was hoping that these were built already but couldn’t see any descent results with a quick Google search so figured I’d just write my own… these are now part of the Umbraco v5 codebase. Here’s 2 HtmlHelper methods that allow you to very quickly create an Html table output based on an IEnumerable data structure. Luckily for us, Phil Haack showed us what Templated Razor Delegates are which makes stuff like this very elegant.

There are 2 types of tables: a table that expands vertically (you set a maximum number of columns), or a table that expands horizontally (you set a maximum amount of rows). So I’ve created 2 HtmlHelper extensions for this:

Html.TableHorizontal Html.TableVertical

Say you have a partial view with a declaration of something like:

@model IEnumerable<MyDataObject>

To render a table is just one call and you can customize exactly how each cell is rendered and styled using Razor delegates, in the following example the MyDataObject class contains 3 properties: Name, Enabled and Icon and each cell is going to render a check box with a CSS image as it’s label and there will be a maximum of 8 columns:

@Html.TableVertical(Model, 8, @<text> @Html.CheckBox(@item.Name, @item.Enabled) <label for="@Html.Id(@item.Name)" class="@item.Icon"> <span>@item.Name</span> </label> </text>)

Nice! that’s it, far too easy. One thing to note is the @<text> </text> syntax as this is special Razor parser syntax that declares a Razor delegate without having to render additional html structures. Generally Razor delegates will require some Html tags such as this: @<div> </div> but if you don’t require surrounding Html structures, you can use the special @<text> </text> tags.

Lastly here’s all the HtmlHelper code… I’ve created these extensions as HtmlHelper extensions only for consistency but as you’ll be able to see, the HtmlHelper is never actually used and these extensions could simply be extensions of IEnumerable<T>.

/// <summary> /// Creates an Html table based on the collection /// which has a maximum numer of rows (expands horizontally) /// </summary> public static HelperResult TableHorizontal<T>(this HtmlHelper html, IEnumerable<T> collection, int maxRows, Func<T, HelperResult> template) where T : class { return new HelperResult(writer => { var items = collection.ToArray(); var itemCount = items.Count(); var maxCols = Convert.ToInt32(Math.Ceiling(items.Count() / Convert.ToDecimal(maxRows))); //construct a grid first var grid = new T[maxCols, maxRows]; var current = 0; for (var x = 0; x < maxCols; x++) for (var y = 0; y < maxRows; y++) if (current < itemCount) grid[x, y] = items[current++]; WriteTable(grid, writer, maxRows, maxCols, template); }); } /// <summary> /// Creates an Html table based on the collection /// which has a maximum number of cols (expands vertically) /// </summary> public static HelperResult TableVertical<T>(this HtmlHelper html, IEnumerable<T> collection, int maxCols, Func<T, HelperResult> template) where T : class { return new HelperResult(writer => { var items = collection.ToArray(); var itemCount = items.Count(); var maxRows = Convert.ToInt32(Math.Ceiling(items.Count() / Convert.ToDecimal(maxCols))); //construct a grid first var grid = new T[maxCols, maxRows]; var current = 0; for (var y = 0; y < maxRows; y++) for (var x = 0; x < maxCols; x++) if (current < itemCount) grid[x, y] = items[current++]; WriteTable(grid, writer, maxRows, maxCols, template); }); } /// <summary> /// Writes the table markup to the writer based on the item /// input and the pre-determined grid of items /// </summary> private static void WriteTable<T>(T[,] grid, TextWriter writer, int maxRows, int maxCols, Func<T, HelperResult> template) where T : class { //create a table based on the grid writer.Write("<table>"); for (var y = 0; y < maxRows; y++) { writer.Write("<tr>"); for (var x = 0; x < maxCols; x++) { writer.Write("<td>"); var item = grid[x, y]; if (item != null) { //if there's an item at that grid location, call its template template(item).WriteTo(writer); } writer.Write("</td>"); } writer.Write("</tr>"); } writer.Write("</table>"); }

Searching Umbraco using Razor and Examine

March 15, 2011 20:51 by Shannon Deminick
This post was imported from FARMCode.org which has been discontinued. These posts now exist here as an archive. They may contain broken links and images.
Since Razor is really just c# it’s super simple to run a search in Umbraco using Razor and Examine.  In MVC the actual searching should be left up to the controller to give the search results to your view, but in Umbraco 4.6 + , Razor is used as macros which actually ‘do stuff’. Here’s how incredibly simple it is to do a search:
@using Examine; @* Get the search term from query string *@ @{var searchTerm = Request.QueryString["search"];} <ul class="search-results"> @foreach (var result in ExamineManager.Instance.Search(searchTerm, true)) { <li> <span>@result.Score</span> <a href="@umbraco.library.NiceUrl(result.Id)"> @result.Fields["nodeName"] </a> </li> } </ul>

That’s it! Pretty darn easy.

And for all you sceptics who think there’s too much configuration involved to setup Examine, configuring Examine requires 3 lines of code. Yes its true, 3 lines, that’s it. Here’s the bare minimum setup:

1. Create an indexer under the ExamineIndexProviders section:

<add name="MyIndexer" type="UmbracoExamine.UmbracoContentIndexer, UmbracoExamine"/>

2. Create a searcher under the ExamineSearchProviders section:

<add name="MySearcher" type="UmbracoExamine.UmbracoExamineSearcher, UmbracoExamine"/>

3. Create an index set under the ExamineLuceneIndexSets config section:

<IndexSet SetName="MyIndexSet" IndexPath="~/App_Data/TEMP/MyIndex" />

This will index all of your data in Umbraco and allow you to search against all of it. If you want to search on specific subsets, you can use the FluentAPI to search and of course if you want to modify your index, there’s much more you can do with the config if you like.

With Examine the sky is the limit, you can have an incredibly simple index and search mechanism up to an incredibly complex index with event handlers, etc… and a very complex search with fuzzy logic, proximity searches, etc…  And no matter what flavour you choose it is guaranteed to be VERY fast and doesn’t matter how much data you’re searching against.

I also STRONGLY advise you to use the latest release on CodePlex: http://examine.codeplex.com/releases/view/50781 . There will also be version 1.1 coming out very soon.

Enjoy!

Auto Sort package for Umbraco released

March 10, 2011 08:33 by Shannon Deminick
This post was imported from FARMCode.org which has been discontinued. These posts now exist here as an archive. They may contain broken links and images.
After sorting 150 nodes manually in the Umbraco backend I thought to myself that it can’t be too hard to write some kind of automatic sorting dialog. First I thought about adding some options to the existing sort dialog, which would swirl the child nodes in the list around to the editors content, yet that seemed like too much effort to just sort the nodes, the editor would still have the option to do some manual ordering using the built-in Umbraco sort after the automatic sort. The next idea was to add another option to the context menu, then ideally open up a sub menu so you could just go ‘Auto sort –> descending’ and it would go off. Apart from the fact that it would be quite a bit of work to get that sub menu working (I recently read somewhere that it’s probably coming in version 5 Smile, looking forward already) it had a couple of additional downfalls: the sort might be triggered by accident and it would be quite difficult to get additional options in there, e.g. the field you want to sort by. That pretty much left the option to give Auto Sort it’s very own popup window.

The options I ended up with in the end are the following:

  • The field to sort the nodes by. Currently supported are
    • node name
    • id
    • creation date
    • note type alias and
    • custom fields (you have to provide the alias of your custom property);
    additionally for content nodes there are also
    • update date
    • release date
    • expiry date and
    • creator name
    to choose from. (default: node name)
  • Sort either ascending or descending (default: ascending)
  • Include grand children in the sort or not. Including grand children will sort ALL children and grand children by the field you have selected recursively. (default: exclude grand children)
  • Include all unpublished nodes in the sort, or choose to exclude them. (default: include)
  • If you exclude unpublished nodes from the sort you will need to provide the location of the unpublished nodes, either at the top of the list or at the bottom (default: top)

Once the first sort using node name was working it was a nearly a breeze to make the additional options work as well. Some issues occurred with regards to the differences between content and media nodes, but nothing that a couple of if-else statements couldn’t handle. Here are some screen shots:

 

 

The trickier bit was then to add support for multiple languages. The respective keys had to be added to the specific language xml files in /umbraco/config/lang. The Package Actions Contrib package by Richard Soeteman (essential for each Umbraco package builder) contains the fantastic AddLanguageFileKey action by Chris Houston, which would have done the deed yet would also have been a bit cumbersome since I had to add like 20 keys for each language, and also I wanted to add my own area in the language files. So I extended the custom package action to take a list of key-value-pairs and the name for a new are to create the section in the specified language file [note to self: send the code to Richard Soeteman so he can add it to the contrib package]. At the time of writing there are only 2 languages missing thanks to the community, which is absolutely awesome, I’ll include them shortly in the package. Credit goes to the following translators:

  • kows for the Dutch version
  • Patrik Wibron for the Swedish version
  • Mike for the French version
  • Morten Balle for the Dansk version
  • ricardo for Italiano and Spanish (double high five!)
  • Korean version anyone?
  • Norwegian maybe?

I hope you enjoy the package and that it makes your life even easier than developing web sites with Umbraco already is. Skål!