@Shazwazza

Shannon Deminick's blog all about web development

New Examine updates and features for Umbraco

March 6, 2013 00:42

It’s been a long while since Examine got some much needed attention and I’m pleased to say it is now happening. If you didn’t know already, we’ve moved the Umbraco Examine source in to the core of Umbraco. The underlying Examine (Examine.dll) core will remain on CodePlex but all the Umbraco bits and pieces which is found in UmbracoExamine.dll are in the Umbraco core from version 6.1+. This is great news because now we can all better support the implementation of Examine for Umbraco. More good news is that even versions prior to Umbraco 6.1 will have some bugs fixed (http://issues.umbraco.org/issue/U4-1768) ! Niels Kuhnel has also jumped aboard the Examine train and is helping out a ton by adding his amazing ‘facet’ features which will probably make it into an Umbraco release around version 6.2 (maybe 6.1, but still need to do some review, etc… to make sure its 100% backwards compatible).

One other bit of cool news is that we’re adding an official Examine Management dashboard to Umbraco 6.1. In its present state it supports optimizing indexes, rebuilding indexes and searching them. I’ve created a quick video showing its features :)

Examine management dashboard for Umbraco

Using IoC with Umbraco & MVC

October 31, 2012 18:08

The question was asked on my post yesterday about the upcoming Umbraco 4.10.0 release with MVC support and whether it is possible to use IoC/Dependency Injection with our implementation. The answer is definitely yes!

One of the decisions we’ve made for the code of Umbraco is to not use IoC in the core. This is not because we don’t like IoC (in fact I absolutely love it) but more because things start to get really messy when not 100% of your developers understand it and use it properly. Since Umbraco is open source there are developers from many walks of life committing code to the core and we’d rather not force a programming pattern on them. Additionally, if some developers don’t fully grasp this pattern this leads to strange and inconsistent code and even worse if developers don’t understand this pattern then sometimes IoC can be very difficult to debug.

This ultimately means things are better for you since we won’t get in the way with whatever IoC framework you choose.

Which frameworks can i use?

Theoretically you can use whatever IoC framework that you’d like, though I haven’t tested or even tried most of them I’m assuming if they are reasonable frameworks that work with MVC then you should be fine. I’m an Autofac fan and to be honest I’ve only dabbled in other frameworks so all examples in this post and documentation are based on Autofac. Since we don’t use any IoC, it also means that we are not specifying a DependencyResolver so you are free to set this to whatever you like (I’d assume that most IoC frameworks would integrate with MVC via the DependencyResolver).

How do i do it?

I chucked up some docs on github here which I’ll basically just reiterate on this post again with some more points. Assuming that you construct your IoC container in your global.asax, the first thing you’ll have to do is to create this class and make sure it inherits from the Umbraco one (otherwise nothing will work). Then just override OnApplicationStarted and build up your container. Here’s an example (using Autofac):

/// <summary>
/// The global.asax class
/// </summary>
public class MyApplication : Umbraco.Web.UmbracoApplication
{
    protected override void OnApplicationStarted(object sender, EventArgs e)
    {
        base.OnApplicationStarted(sender, e);

        var builder = new ContainerBuilder();

        //register all controllers found in this assembly
        builder.RegisterControllers(typeof(MyApplication).Assembly);

        //add custom class to the container as Transient instance
        builder.RegisterType<MyAwesomeContext>();

        var container = builder.Build();
        DependencyResolver.SetResolver(new AutofacDependencyResolver(container));
    }
}

Notice that I’ve also registered a custom class called MyAwesomeContext in to my container, this is just to show you that IoC is working. Of course you can do whatever you like with your own container :) Here’s the class:

public class MyAwesomeContext
{
    public MyAwesomeContext()
    {
        MyId = Guid.NewGuid();
    }
    public Guid MyId { get; private set; }
}

Next we’ll whip up a custom controller to hijack all routes for any content item that is of a Document Type called ‘Home’ (there’s documentation on github about hijacking routes too):

public class HomeController : RenderMvcController
{
    private readonly MyAwesomeContext _myAwesome;

    public HomeController(MyAwesomeContext myAwesome)
    {
        _myAwesome = myAwesome;
    }

    public override ActionResult Index(Umbraco.Web.Models.RenderModel model)
    {
        //get the current template name
        var template = this.ControllerContext.RouteData.Values["action"].ToString();
        //return the view with the model as the id of the custom class
        return View(template, _myAwesome.MyId);
    }
}

In the above controller, a new instance of MyAwesomeContext will be injected into the constructor, in the Index action we’re going to return the view that matches the currently routed template and set the model of the view to the id of the custom MyAwesomeContext object (This is just an example, you’d probably do something much more useful than this).

We can also do something similar with SurfaceControllers (or any controller you like):

public class MyTestSurfaceController : SurfaceController
{
    private readonly MyAwesomeContext _myAwesome;

    public MyTestSurfaceController(MyAwesomeContext myAwesome)
    {
        _myAwesome = myAwesome;
    }

    [ChildActionOnly]
    public ActionResult HelloWorld()
    {
        return Content("Hello World! Here is my id " + _myAwesome.MyId);
    }
}

That’s it?

Yup, these are just examples of creating controllers with IoC, the actual IoC setup is super easy and should pretty much work out of the box with whatever IoC framework you choose. However, you should probably read the ‘Things to note’ in the documentation in case your IoC engine of choice does something wacky with the controller factory.

Native MVC support in Umbraco coming very soon!

October 31, 2012 00:07

Its been a while since writing a blog post! … but that’s only because I can never find the time since I’m still gallivanting around the globe :P

But this post is about something very exciting, and I’m sure most of you that are reading this already know that with the upcoming Umbraco 4.10.0 release (currently in Beta and downloadable here) we are natively supporting ASP.Net MVC! What’s more is that I’ve tried to document as much as I could on our GitHub docs. Once my pull request is completed the docs will all be available on the main site but until then you can see them on my fork here.

So where to begin? Well, I’m going to try to keep this really short and sweet because I’m hoping you can find most of the info that you’ll want in the documentation.

What is supported?

Everything that you can do in MVC you will be able to do in Umbraco’s MVC implementation. Anything from Partial Views, Child Actions, form submissions, data annotations, client validation to Surface Controllers, custom routes and hijacking Umbraco routes.  If you have used Razor macros before, we support a very similar syntax but it is not 100% the same. We support most of the dynamic querying that you use in Razor macros with the same syntax but to access the dynamic model is slightly different. What is crazy awesome super cool though is that we support a strongly typed query structure!! :) So yes, you can do strongly typed Linq queries with intellisense, no problemo!

Still using Web forms? not a problem, you can have both Web forms and MVC engines running in tandem on your Umbraco site. However, a config setting will set a default rendering engine which will determine whether Web forms master pages or MVC views are created in the back office.

What is not supported (yet)

There’s a few things in this release that we’ve had to push to 4.11.0 due to time constraints. They include: Better tooling support for the View editors in the back office, Partial View Macros and Child Action Macros. Though once you start using this MVC version you’ll quickly discover that the need for macros is pretty small. Perhaps people use macros in different ways but for the most part with the way that MVC works I would probably only use macros for rendering macro content in the WYSIWYG editor.

We support rendering any macros in MVC so you can even render your XSLT macros in your views, but issues will arise if you have User Control or Web form control macros that contain form elements. You will still be able to render these macros but any post backs will not work, and will most likely cause a YSOD. Unfortunately due to the vast differences between how Web forms and MVC work in ASP.Net this is something that we cannot support. The good news is that creating forms in MVC is super easy and makes a whole lot more sense than Web forms…. you can even have more than one <form> element on a page, who’d have thought :P

Strongly typed queries

You can find the documentation for this here but I just wanted to point out some of the differences between the strongly typed syntax and the dynamic syntax. First, in your view you have two properties:

  • @Model.Content = the strongly typed model for your Umbraco view which is of type: Umbraco.Core.Models.IPublishedContent
  • @CurrentPage = the dynamic model representing the current page, this is very very similar to the @Model property in Razor macros

An example is to get the current page’s children that are visible, here’s the syntax for both (and of course since the @CurrentPage is dynamic, you will not get intellisense):

//dynamic access
@CurrentPage.Children.Where("Visible")

//strongly typed access
@Model.Content.Children.Where(x => x.IsVisible())

There are also some queries that are just not (yet) possible in the dynamic query structure. In order to get some complex queries to work with dynamic linq, we need to code these in to the parser to create the expression tree. The parser could probably do with more TLC to support things like this but IMHO, we’re just better off using the strongly typed way instead (plus its probably a much faster execution). I’ve listed this as an example in the docs but will use it here again:

//This example gets the top level ancestor for the current node, and then gets 
//the first node found that contains "1173" in the array of comma delimited
//values found in a property called 'selectedNodes'.
//NOTE: This is one of the edge cases where this doesn't work with dynamic execution but the
//syntax has been listed here to show you that its much easier to use the strongly typed query
//instead

//dynamic access
var paramVals = new Dictionary<string, object> {{"splitTerm", new char[] {','}}, {"searchId", "1173"}};
var result = @CurrentPage.Ancestors().OrderBy("level")
.Single()
.Descendants()
.Where("selectedNodes != null && selectedNodes != String.Empty && selectedNodes.Split(splitTerm).Contains(searchId)", paramVals)
.FirstOrDefault();

//strongly typed
var result = @Model.Content.Ancestors().OrderBy(x => x.Level)
.Single()
.Descendants()
.FirstOrDefault(x => x.GetPropertyValue("selectedNodes", "").Split(',').Contains("1173"));

IMHO i much prefer the strongly typed syntax but it’s up to you to decide since we support both structures.

UmbracoHelper

Another class we’ve introduced is called the Umbraco.Web.UmbracoHelper which is accessible on your views by using the @Umbraco syntax and is also accessible on any SurfaceController. This class contains a ton of handy methods, it is basically the ‘new’ Umbraco ‘library’ class (you know that static one that has a lower case ‘l’ :P ) Of course the ‘library’ class will still be around and you can still use it in your views… but you shouldn’t! This new helper class should contain all of the methods that you need from querying content/media by ids, rendering macros and rendering field content, to stripping the html from a string. The library class was designed for use in Xslt where everything from c# wasn’t natively given to you, now with Razor views you have the entire world of c# at your fingertips. So you’ll notice things like the date formatting functions that were on ‘library’ are not on the UmbracoHelper, and that is because you can just use the regular c# way. Though, if you feel inclined that these methods should be on UmbracoHelper, another great thing is that this is not a static class so you can add as many extension methods as you like.  I’d list all of the methods out here but I said I’d keep it short, your best bet currently is to just have a look at the class in the source code, or just see what great stuff shows up in intellisense in VS.

UmbracoContext

Though we did have another UmbracoContext class, this one is the new cooler one and the old one has been marked as obsolete. This new one’s full name is Umbraco.Web.UmbracoContext and it is a singleton so you can access it by UmbracoContext.Current but normally you shouldn’t have to access it by it’s singleton because it is available in all of your views and SurfaceControllers as a property. For example, to access the UmbracoContext in your view you simply use @UmbracoContext. This class exposes some handy properties like: UmbracoUser, PageId, IsDebug, etc…

Testing

If you are interested in MVC and Umbraco, it would be really really appreciated for you to take the time to download the beta, the latest nightlies or source code and give it a shot. Hopefully the docs are enough to get you up and running and if you run into any troubles please log your issues on the tracker. If you have any question, comments, etc… about the source code we’d love to hear from you on the mail list.

Pete will be putting up an MVC getting started post on the Umbraco blog real soon, so watch this space!

Adios!

MVC in Umbraco v4

June 18, 2012 07:33

After the announcement of discontinuing Umbraco v5 development during this years Code Garden 2012 conference, the biggest question seemed to be: What will happen with ASP.Net MVC and Umbraco. We held an open space session regarding this question where we asked 2 questions: “Is an MVC implementation in Umbraco important to have for the front end?” and “Is an MVC implementation important to have for the back office?”. There were quite a few people who attended this session and I think 100% of people raised their hands in answer to the first question and only 1 person raised their hands for the second answer.  I think this result was expected since most Umbraco developers simply wish to use MVC in their own development on the front-end and want the Umbraco back office to keep working with all of the great packages already created for it.

There was a considerable amount of knowledge gained in creating v5 and of course we will incorporate much of this knowledge into v4… starting real soon! I decided to create a package for Umbraco v4 which enables a native MVC front end which was demo’d during the Code Garden package competition and is available right now!  It turns out that creating this didn’t take much time at all, in fact I created it during the 2nd day of the conference. The reason this was reasonable easy was because we had all of this already built for v5 so it was a matter of taking this knowledge and code and applying it to v4.

So if you are like many other devs and really want Umbraco to route to a native MVC front end then you can give this package a try, its called umbraMVCo. Please be warned that I have not tested this very much, but also know that its just using the tried and tested v4 api’s to do the routing so I’m assuming it will ‘just work’ … though I’m sure you guys will find some bugs I haven’t yet :) There’s also a readme file on the downloads page which explains how to install it, and what settings/servers that I know it works with.

What’s also really cool is this code completely supports Hijacking Umbraco Routes!

Download/Source

You can download the package and readme files here

https://bitbucket.org/Shandem/umbramvco/downloads

Ensure that you read the readme file, it contains some very important information including installation instructions!

The source can be found here:

https://bitbucket.org/Shandem/umbramvco/src

If you come across issues with this please log issues here: https://bitbucket.org/Shandem/umbramvco/issues . The source isn’t really complicated or anything though so you should be able to identify the reason for an issue if you come across it.

What’s next?

So will MVC be coming to v4… Yes indeed. We will also support routing to either WebForms or MVC and we’ll support this by having a flag on the document type to choose which rendering engine to use. We’ve got a few things to do in v4 regarding how routing works to do this nicely/properly but the end result will be pretty much the same as what this package enables. All of those cool MVC things that you liked in v5 like SurfaceControllers will be coming to v4 as well, we will still support Child Action and Partial View macros. Another cool thing is that we should be able to support Xslt and UserControl macros in MVC as well (though any post backs will definitely not work).

So even though the development of v5 has been discontinued, a ton of the concepts that you liked about it will in fact be ported to v4.

Hijacking Umbraco routes

March 7, 2012 06:02

DISCLAIMER!

This blog post relates to the latest source code of Umbraco v5 and will not work in Umbraco 5.0.0. Unfortunately due to my own mistakes which I take full credit for (#h5is) in fixing a last minute bug in 5.0.0 I actually broke this functionality for the release. So the following blog post relates to upcoming releases of Umbraco 5.x or if you are using the latest source code in Mercurial.

By default all of the front end routing is executed via the UmbracoController Index Action which should work fine for most people. However, in some cases people may want complete control over this execution and may  want their own Action to execute. Some reasons for this may be: to control exactly how views are rendered, custom/granular security for certain pages/templates or to be able to execute any custom code in the controller that renders the front end. The good news is that this is completely possible, in fact this was one of the first features implemented in V5 all the way back in 2010!

This process is all about convention and it's really simple. It's easiest to demonstrate with an example : let's say you have a document type called 'Home'.  You can create a custom locally declared controller in your MVC web project called 'HomeController' and ensure that it inherits from Umbraco.Cms.Web.Mvc.Controllers.UmbracoController and now all pages that are of document type 'Home' will be routed through your custom controller! Pretty easy right :-)

OK so let's see how we can extend this concept. In order for you to run some code in your controller you'll need to override the Index Action. Here’s a quick example:

public class HomeController : UmbracoController
{
public override ActionResult Index(IUmbracoRenderModel model)
{
//Do some stuff here, the return the base method
return base.Index(model);
}
}

Now you can run any code that you want inside of that Action. To further extend this, we've also allowed routing to different Actions based on the Template that is being rendered. By default only the Index Action exists which will execute for all requests of the corresponding document type. However, if the template being rendered is called 'HomePage' and you have an Action on your controller called 'HomePage' then it will execute instead of the Index Action. As an example, say we have a Home Document Type which has 2 allowed Templates: ‘HomePage’ and ‘MobileHomePage’ and we only want to do some custom stuff for when the ‘MobileHomePage’ Template is executed:

public class HomeController : UmbracoController
{
public ActionResult MobileHomePage(IUmbracoRenderModel model)
{
//Do some stuff here, the return the base Index method
return base.Index(model);
}
}


So here's how the mapping works:

  • Document Type name = controller name
  • Template name = action name, but if no action matches or is not specified then the 'Index' action will be executed.

In the near future we will allow setting a custom default controller to execute for all requests instead of the standard UmbracoController. Currently you'd have to create a controller for every document type to have a customer controller execute for all requests.

There's probably a ton of uses for hijacking an Umbraco request that we haven't thought of yet. Now that you know how to do it I'm sure plenty of new techniques will be invented.

Happy coding!  :)

Registering custom components in IoC for Umbraco 5 plugins

January 2, 2012 02:23

Sometimes you might need to add some of your own components to the IoC container in Umbraco 5 for your plugins to function. We’ve made this extremely easy to do and it only requires 2 steps:

Create a custom class that implements Umbraco.Framework.DependencyManagement.IDependencyDemandBuilder . Ensure that this class does not have any constructor parameters otherwise it will not work. There’s only one method to implement and you can use the containerBuilder parameter to add stuff to the IoC container:

void Build(IContainerBuilder containerBuilder, IBuilderContext context);


Next you need to attribute your plugin (i.e. Tree, Editor, Menu Item, Property Editor, Surface Controller, etc….) to tell it which ‘Demand Builder’ to use. Easiest to explain with an example:

[DemandsDependencies(typeof(MyCustomBuilder))]
[Tree("4883C970-2499-488E-A963-5204F6C6F840", "My Tree")]
public class MyCustomTree : TreeController

The above code will ensure that the ‘Demand Builder’ of type MyCustomBuilder will be executed when this plugin is loaded

Thats it! Now you can add anything you need to the IoC container if you require this for your plugin.

Umbraco v5 Surface Controller Forms

November 29, 2011 21:22

This post will show you how to create a form in Umbraco v5 using Surface Controllers. The information in this post assumes that you are familiar with Surface Controllers (see this previous post if not) and with creating forms in ASP.Net MVC.

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.

Create a model

The easiest way to create a form in MVC is to create a model that represents your form. This isn’t mandatory but then you’ll have to use some old school techniques like getting posted values directly from the HttpRequest object.

An example could be:

namespace MySite.Models
{
    public class MyTestModel
    {
        [Required]
        public string Name { get; set; }

        [Required]
        [Range(18,30)]
        public int Age { get; set; }        
    }
}

Create a Surface Controller

For this example we’ll assume that we’re creating a locally declared Surface Controller (not a plugin, see the previous post for full details).

Some code first and explanation after:

namespace MySite.Controllers
{   
    public class MySurfaceController : SurfaceController
    {
        [HttpPost] 
        public ActionResult HandleFormSubmit(
            [Bind(Prefix = "MyTestForm")]
            MyTestModel model)
        {
            if (!ModelState.IsValid)
            {
                return CurrentUmbracoPage();
            }            
            
            //do stuff here with the data in the model... send
            // an email, or insert into db, etc...
            
            return RedirectToUmbracoPage(
                new HiveId(
                    new Guid("00000000000000000000000000001049")));
        }
    }
}

Lets break down some parts of the above Controller code:

Namespace: Generally you’ll put your locally declared controllers in the ~/Controllers folder, the above namespace reflects this.

Class: The Surface Controller class is suffixed with the term ‘SurfaceController’. This is a required convention (as per the previous post), without that suffix, the controller will not get routed.

[Bind] attribute: In the code below you’ll see that we are creating the editor with a ‘prefix’ called ‘MyTestForm’. This ensures that each input element on the form will get its name prefixed with this value. For example:

<input type="text" name="MyTestForm.Name" />

This is a recommended practice however it is optional. If you don’t prefix your form controls then you don’t need to use the [Bind] attribute. Here’s a few reasons why this is a recommended practice:

  1. Without the prefix, If there is more than 1 form rendered on your webpage and both are using the MVC validation summary, then both validation summaries will display the errors for both forms. When there is a prefix you can tell the validation summary to only display errors for the form with the specified prefix.
  2. The MVC Html helpers will generate the html id for each element and without specifying a prefix and if you have more than 1 form rendered on your page you may end up with duplicate html element Ids.
  3. If you create a scaffolded form with a custom model object such as doing:

    @{ var someModel = new MyModel(); }
    @Html.EditorFor(x => someModel)

    then MVC will automatically prefix your input fields with ‘someModel’ . For some reason MVC does this when the model name isn’t exactly ‘Model’.

return CurrentUmbracoPage: This method is built in to the base SurfaceController class and simply returns the currently executing Umbraco page without a redirect to it which is generally what you want to do in order to display any validation errors.

return RedirectToUmbracoPage: This method is built in to the base SurfaceController class and performs a redirect to a Umbraco page given an Id which is generally what you want to do when a form submission is successful. (chances are that you wont have a page with a Guid id of 00000000000000000000000000001234…. this is just an example :)

NOTE: There is also a RedirectToCurrentUmbracoPage() method!

Rendering a form

There are a few ways to render a form:

  • Directly in your Umbraco template/view
  • Using a Partial View macro
  • Using a Child Action macro which renders a partial view

Regardless of which you use to render a form, the markup will be very similar. Similar to MVC’s @Html.BeginForm, we have an @Html.BeginUmbracoForm helper:

@{
    var formModel = new MySite.Models.MyTestModel();
}

@using(Html.BeginUmbracoForm("HandleFormSubmit", "MySurface"))
{
    @Html.ValidationSummary(prefix: "MyTestForm")
    @Html.EditorFor(x => formModel, "", "MyTestForm")
    <input type="submit"/>
}

Here’s the breakdown of the above mark-up:

Html.BeginUmbracoForm: A normal MVC form would simply use Html.BeginForm which will create an action attribute for the html form tag with a URL of your controller’s action. In Umbraco however, we want the URL to be posted to the same as the URL being rendered (post back), so the BeginUmbracoForm call handles this all for us. It will create a form tag with the URL of the currently rendered Umbraco node and add some custom hidden fields to your form containing the values of where the data will actually post to (your Surface Controller’s action). The Umbraco front-end route handler will take care of all of this for you.

The parameters passed in to BeginUmbracoForm will differ depending on if your Surface Controller is a plugin controller or a locally declared controller. In this example, its a locally declared controller so we just need to give it the action name and controller name. If its a plugin Surface Controller, you’ll need to give it the action and and the controller ID. There’s also a few overloads so that you can add additional html attributes to the rendered html form tag.

@Html.ValidationSummary: The native MVC ValidationSummary doesn’t let you target specific input tags via prefixes so we’ve created a ‘better’ one that does let you do that. In this example we’re telling the validation summary to only display errors for input values that are prefixed with “MyTestForm” which is real handy if you’re rendering a few forms on the same page and using a validation summary for each.

@Html.EditorFor: This is the native EditorFor method in MVC which lets you supply a prefix name which will be used for all of your input fields. The MVC methods for rendering individual input tags also have an overload to supply a prefix if you choose not to have it scaffold your form for you.

formModel: The above mark-up will scaffold the form for us based on the model that we created previously. This example creates an inline model object (formModel) to scaffold the form but if you had a strongly typed partial view with your model type, you could just as well use the view’s Model property.

And that’s pretty much it! Happy form making :)

Umbraco Jupiter Plugins - Part 5 - Surface Controllers

November 29, 2011 14:31

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 07:56

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 04:09

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