Allowing your site visitor to fill in forms and post information to your website is a key aspect of many websites. Today's tutorial is the first in a several part guide about how to implement forms within your project. In today's guide, we're going to cover a simple log-in form and all the code you will need to implement it.

Surface Controller

When you build a bog standard MVC website, you should be well aware of the MVC page controller.  In Umbraco when we deal with forms and postbacks, we need some extra functionality to integrate our forms with Umbraco and luckily, Umbraco has provided this functionality with a handy base controller called the surface controller. The surface controller is like a normal page controller, however, it has a few thrown in Umbraco based benefits, for example, a surface controller knows things like the current Umbraco page for the request.  Basically.. when you think about implementing a form on your website, you will need a surface controller to deal with the response.  Without a surface controller, none of this would be possible.  A surface controller is a bit more powerful than a normal MVC controller as it knows a lot more about Umbraco,

The View Model

Like any good architected MVC website, we will need a basic view model to pass the data from the form to the controller. This will look like this:

The Controller

The next part is creating a controller to deal with the log-in logic and return the correct views, which will look like this:

We inherit from the surface controller and implement three actions, a standard Index action that will render the log-in view, a log-out action (does what it says on the can) and a validate action. The validate action will be used to try and log the user into the website, if the credentials are successful the user will be re-directed to the homepage with a welcome message, if the credentials are invalid they will see an error message. Note the ActionName attributes above Index and Validate. Without these, you will see the following error.

Could not find a Surface controller route in the RouteTable for controller name MembershipController. This is because the surface controller is expecting certain actions to be named appropriately, so follow the syntax.

The Partial View

In my partials folder, I added a view called LoginForm.cshtml, which looks like this:

The view uses the view model as the main model. In the top half of the page, we use the IsAuthenticated to determine which snippet of HTML to display to the user.  If the user is logged in, they will see an output button that, when clicked, will call the logout action in the surface controller. If they are not logged in, they will see an input form based on the view model, that will post the form data on submissions to the MemberLogin method in the controller. The last bit of the file is used to display any error messages to the user.  Another way of doing this is by adding an error message property to the view model.

Adding The Partial

The last bit is to add a reference to the partial view from your page template; this is done using the Action helper, like so:

You can download the code from this tutorial, from #ILoveUmbraco There we have it; if you implement the code above you should now have a simple web form that will log a user into your Umbraco website. In order to do this, we have to use the inbuilt Umbraco controller, called the surface controller. We implemented a view model and three actions, a first-page load action (the index), a logout action and a validate action.