Questions tagged [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.

To create a surface controller for use in a plug-in you create a class within a project with a reference to System.Web.Mvc and Umbraco.CMS.Web, with the following setup:

•Inherits from SurfaceController

•Named with a suffix of "SurfaceController"

•Has a class attribute of Surface with a unique GUID

•Contains one or more action methods that return either PartialViewResult or ContentResult and are marked with the [ChildActionOnly] attribute

•The project AssemblyInfo.cs file must contain [assembly: AssemblyContainsPlugins] Otherwise you use standard MVC concepts such as view models and tightly or loosely bound views, either standalone or embedded. You deploy to your package folder as detailed in the previous post.

Using the Surface Controller

There are a couple of ways to make use of the surface controller once it has been built and deployed to the Umbraco application.

One is the standard MVC way - after all this is just a controller action returning a partial view or content result. So you can use @Html.Action. As it's a plug-in, which is created as it's own area, you need to specify the area the controller and action is found within, as follows:

@Html.Action("ActionName","ControllerName", new {area = "PackageName"})

Unfortunately as of writing, this doesn't seem to work. An error of "No route in the route table matches the supplied values." results. Hopefully will sort this out or determine if it's a bug to be fixed shortly.

In any case the better way is really to create a Child Action Macro. This is done via the Developer section and once created the deployed package, controller and action should be selectable from the list. You can then render the macro, e.g. in a template with:

@Umbraco.RenderMacro("artistList")