I've talked previously about How To Create A Sub Layout and Add It to a Page in Sitecore that explained how to create old school web forms, user controller to add functionality into your Sitecore. As Web Forms is a near-obsolete technology now, in today's guide I'm going to discuss how to add functionality to your project using MVC.
Sitecore renderings are the way developers can render a page or a part of a page in Sitecore. Sitecore has many different types of renderings but when we work with MVC, the two main renderings you will be working with are view renderings and controller renderings. A view rendering can be used for components that have no, or very close to no, logic in it.
A view rendering is like calling a partial view in vanilla MVC... basically, it doesn't have a controller! View rendering works by defining a .cshtml view file and registering it with Sitecore. A controller rendering, as the name implies, has a controller and subsequently needs a little bit more configuration and code.
In today's guide, I'm going to create a controller rendering to display some text on a page using MVC. The solution in this example is built upon How To Architect Your Sitecore Website With MVC.
To make this guide as simple to follow as possible, I'm going to use a very basic controller, view model and view that has the minimum of code. The controller will look like this:
The View Model:
The first thing we need to do is create a new controller rendering in Sitecore. Open the Sitecore Content Editor and in the navigation tree go to the Layouts -> Renderings section.
If you are using Sitecore 8 onwards, you can create a 'Controller Rendering' by hitting the imaginatively named 'Controller Rendering' button. In here you need to configure Sitecore to call your controller class. To do this you need to tell Sitecore the full namespace and class name AND the assembly name the controller can be found in.
In my example, the namespace is JonDJones.SiteCore.Mvc.Controllers, the class name is ExampleControlRenderingController and the name of the assembly is JonDJones.SiteCore.Mvc. So the full path would be JonDJones.SiteCore.Mvc.Controllers.ExampleControlRenderingController, JonDJones.SiteCore.Mvc. The next step is defining the Action in my controller Sitecore will call. In my code, I have a default 'Index' action so I'd add 'Index' into Sitecore.
Creating A Placeholder
In Sitecore to add renderings onto a page, we generally do it by defining a placeholder that we add to a layout that lets content editors pick what functionality onto the page.
In the placeholder setting, in the 'Allowed Controls' section, we need to add our new controller rendering and click 'Edit'.
In here you can add the controls that can be created within the placeholder. To move a control, select it and hit the right arrow. After you've done adding all your controls, hit the 'Ok' button.
Adding a PlaceHolder To a A Layout
So far, we've got a controller rendering and we've added it to a placeholder so it can be added to a page. The next step is to add it to a layout to use. Just in case you haven't got an existing layout, I'll create one quickly. In the content tree, go to:
' Layouts' -> 'Layouts' -> 'MVC Layout'
You can call it whatever you want, I'm going to call mine 'Home'... original right? My layout will be a .cshtml view in my views folder. The markup will look like this:
In this view, we're adding the placeholder we'll use to add our controller rendering. Back in site core we now need to add a placeholder called controlRenderingPlaceHolder which will be of the type ControlRenderingPlaceHolder.
In the content section, pick a page to add the rendering onto, in my example I'm using the homepage. In the ribbon, click on the 'Presentation' and in the Layout section click 'Details'.
In the 'Device Editor', select:
'Placeholder Settings' -> 'Add'
Select the ControlRenderingPlaceholder we created above, call it 'controlRenderingPlaceHolder' (the same name we used in the layout HTML and publish the page.
Adding The Control Rendering To The Page
On the home page, in the ribbon open 'Publish' -> 'Experience Editor'. In the experience editor:
In the experienced editor, you should see the placeholder we defined above. In the top left-hand corner of the placeholder, you should see the 'Add here' button. Click on it. In the list, you should now see the control rendering. Select it and job done! If everything has worked correctly, you should see the time on the page.
I Get An Error
If you try and add the control and you see the below error, it means something's gone wrong.
A good tip to try and troubleshoot the error is to look at the exception. In chrome if you click 'Inspect Element' -> 'Console' and add the control again, you should see an error being rendered, like so:
If you click on the link you should be able to see the exception:
We've covered a lot in this tutorial. We've covered view renderings and controller renderings. We've registered the control in Sitecore. We've added the control into a placeholder and we've added the placeholder onto a page. We've covered how a content editor can add the rendering onto a page. In development, adding renderings can throw errors. When this happens you can use chrome to find the exception.