View components are similar to controllers, with the following differences:

• View components are called from templates. Their output is inserted in the final rendered HTML
• If a view component is based on a template, only the body section of the template is rendered, and no layout template will be used
• View components don't have to use templates. They can return a string or StringBuilder object containing HTML generated by code
• Only the default action method is supported: the Run() method

Creating a view component

You create a view component by creating a class which derives from ViewComponent. You should add at least one method called Run(), which is the action method for the view component.

[View("testcomponent")]
public class TestComponent : ViewComponent
{
    public void Run()
    {
    }
}

or:

public class TestComponent : ViewComponent
{
    public string Run()
    {
        return "... some HTML ...";
    }
}

If the Run() method doesn't return a value, or it returns null, a view will be rendered. Remember that the name of the view is the name of the controller (by default), unless you specify a [View] attribute on your view component.

Because a view component behaves like a normal controller, you can create base classes, define [BeforeAction] and [AfterAction] methods, specify the view to render, etc.

Calling a view component

Calling a view component from a template can be done by using the {% %} tags. The syntax is:

{% ComponentName @Param1=... , @Param2=... , @Param3=... , ... %}

The parameters are optional, and they are inserted in virtual request data for the view component. This means that these parameters behave exactly as if they were specified in the URL for controller actions. Parameters can be specified directly in the Run() method, mapped to private members using the [Parameter] attribute or retrieved directly by using the GetData property.

Example component

An example will make things perfectly clear:

[View("testComponent")]
public class TestComponent : ViewComponent
{
    [Parameter("bold")]
    private bool _bold;
    
    public void Run(string data)
    {
        ViewData["DataReceived"] = data;
    }
}

This view component will use the testComponent.htm template for generating HTML. The ViewData[] variables that are defined in the Run() method will only be visible in the testComponent.htm template, NOT the calling template. The component expects one parameter named data.

To call this component, you can use the following syntax:

...
{% TestComponent @data="Something" %}
...
{% TestComponent @data="Something Else", @bold = true %}
...

Component name

By default, the name of the view component is the name of the class (without the namespace). You can change the name by adding the [ComponentName] attribute to the class:

[ComponentName("MyComponent")]
public class TestComponent : ViewComponent
{
    public void Run()
    {
        // ...
    }
}

Javascript in view components

You can register javascript code from view components just like you would in a normal controller. You can only insert javascript in the main template, so for that purpose, a property RootView is available in a view component. This view represents the main view (the template from which the component was called).

Ajax in view components

You can define Ajax methods in your view component classes by simple adding the [Ajax] attribute to a method. The method has to be static, because at the time the ajax method is called, the view has already been rendered, so the instance of the view component is already destroyed. Other than that, there are no restrictions.

Handling postback

View components are not created by the controller, so they don't support postback operations. The name says it all: they should by used for displaying data.
If you want to create components that can also handle postbacks, you should create a custom control, which can be instantiated from the controller.

Because of this restriction, it's not possible to bind forms in a view component.