11

History

I'm a Web Forms developer with some .NET MVC experience, new to Umbraco and learning as I go.

So far I've been following the Umbraco documentation and videos to get set up which means all my controllers inherit from a "Controller Base" with common functions included, which in itself inherits from SurfaceController.

Recently however, I have noticed some bloggers and external reference material referencing RenderMvcController in the base class instead of SurfaceController - now the Umbraco documentation is unclear on the real differences between the two, nor which situations you should use them in.

The Question

Is there a clear and distinct difference between the imagined usage scenarios for a Surface Controller - inheriting from Umbraco.Web.Mvc.SurfaceController, and a Custom Controller - inheriting from Umbraco.Web.Mvc.RenderMvcController?

Thanks!

tereško
  • 56,151
  • 24
  • 92
  • 147
Chris Wilson
  • 160
  • 1
  • 1
  • 8

2 Answers2

18

The documentation for the SurfaceController is here: http://our.umbraco.org/documentation/Reference/Templating/Mvc/surface-controllers

In a nutshell, the SurfaceController is used for helping to interact with views. So for example you could post a form to a surface controller. Or you could write a child action to a view with a SurfaceController

RenderMvcController is used purely for routing to published pages. So you could sub-class RenderMvcController in order to 'hijack' requests to published pages of a specific Document Type. See here http://our.umbraco.org/documentation/Reference/Templating/Mvc/custom-controllers.

Digbyswift
  • 9,945
  • 2
  • 36
  • 65
  • 1
    `SurfaceController` is also typically used to expose APIs that make use of Umbraco content. – Richard Szalay Sep 07 '14 at 10:37
  • 5
    Yes it _can_ be but shouldn't be, since there is `UmbracoApiController` for this very purpose. The two main purposes of surface controllers are form interaction and child actions. – Digbyswift Sep 08 '14 at 07:55
7

To further clarify based on Digbyswift's answer:

SurfaceController = APIs or form targets (that then redirect)

RenderMvcController = custom logic to build a model or select a view for a content item (based on Document Type and, optionally, template)

Richard Szalay
  • 78,647
  • 19
  • 169
  • 223
  • 10
    Although you are right in that it _can_ be used for APIs, I personally wouldn't recommend it. Umbraco provides the `UmbracoApiController` specifically for this purpose. This method has less overhead than using the SurfaceController. Also, Using surface controllers lumps all your API code in with MVC-specific form handling and child action code which I personally think isn't great. Separate routing can also then be defined for the API too. – Digbyswift Sep 08 '14 at 08:01
  • Good call @Digbyswift! – Richard Szalay Sep 08 '14 at 11:41