Skip to main content
Logo
There is a newer version of Contensis. Click to find out more and download the latest version.

WebAPI ContensisForm helper

The ContensisForm helper allows developers to insert MVC-like forms using Razor views within Contensis, and POST the form results to a URL for processing. Essentially, the same behaviour a typical HTML form would give you, but within the limitations of ASP.NET WebForms.

Under the hood

As Contensis websites currently use ASP.NET WebForms, each webpage is wrapped in a HTML <form> element for view state and postback purposes. Although this approach has certain benefits; it also has a number of drawbacks; which are well documented. This is where ContensisForm helper comes in.

The helper does not render an additional <form> element to your page - that would generate a nested <form> tag and as a result give you invalid HTML (some browsers would simply ignore the inner form element). Instead, the ContensisForm helper renders out a DIV and some JavaScript which relies on jQuery. It’s the JavaScript that mimics the behaviour of a traditional form control and allows the data to be posted to a given URL.

From a development perspective, there is no need to add jQuery to each page in order to support this feature. The jQuery library is added on demand, meaning that only pages that use helper would have it added to the page.

Use the ContensisForm Helper

A typical usage of the helper would be:

You'll notice that the Html.BeginContensisForm follows the same syntax as the Html.BeginForm HTML helper from the MVC Razor libraries so it will feel familiar to MVC developers.

Form validations

The helper has also been designed to work with the jQuery Unobtrusive Validation libraries that ship with standard MVC projects. This means that MVC developers and designers should be comfortable with applying form validation to forms created using the helper.

Recent changes in ASP.NET Web Pages 2, introduced an improved validation system. With the new Validation class you can easily apply varying types of validation to your forms:

  • Validator.DateTime()

  • Validator.Decimal()

  • Validator.EqualsTo()

  • Validator.Float()

  • Validator.Integer()

  • Validator.Range()

  • Validator.Regex()

  • Validator.Required()

  • Validator.StringLength()

  • Validator.Url()

As in ASP.NET Webpages, not all validators have been designed to work client side.  The following validators will require custom client side code in order to work - you can refer to the jQuery Validation website for documentation on how to achieve this.

  • Validator.DateTime()

  • Validator.Decimal()

  • Validator.Float()

  • Validator.Integer()

  • Validator.Url()

Form validation example

The following example shows how this can be achieved.

Handling form submissions

You can handle form POST submissions in any way you choose - after all you could POST the data to any given endpoint that accepts a Http request. For the purposes of this example, we will Post the data to a WebApi Controller that is hosted by our Contensis powered website. You can read more on WebAPI 2 at the official asp.net website.

Using a WebAPI Controller

Our WebApi Controller inherits from ContensisApiController. This is to make it easier to develop ApiControllers specific to Contensis. One of the benefits is the use of overloaded CreateResponse methods, which give a simple interface for returning a specific type to the ContensisForm helper.

Within our websites App_Code folder, we have both a CS and VB folder. Inside the CS folder (where all C# files should reside), we have a simple ApiController class shown below:

Notice that the routing information supplied in the ApiController will match with the Action Name and ControllerName given in the BeginContensisForm declaration in our razor view. This effectively means that the form contained in the razor view will post its data to the ApiController above. More information on attribute based routing can be found at the MSDN blog.

Also, in this ApiController example, the return type is a simple display message type response, where we output one of the fields that was posted to the Controller. An alternative implementation may be to respond with a redirect.

Using a redirect

An example of returning a redirect can be seen below:

This example would allow you to process the results of the HTTP post, then redirect the user to another web page - this could be a confirmation page, login page or maybe a 3rd party payment engine.

Form summaries

In an earlier example, we showed a sample ApiController that simply displayed a ‘Hello World’ type message. How would we actually display this message back to the user?

As we don't actually render a Form element, the browser will not Post contents to a new URL for its response. Instead, the ContensisForm helper performs a XmlHttpRequest to your chosen URL and processes the response itself. This is why we have also supplied a ContensisFormSummary Helper

ContensisFormSummary helper

Its usage is simple; within your BeginContensisForm declaration, you simply need to add the helper for the FormSummary and the rest is taken care for you.

See this example: