MonoRail

The model in the MVC pattern is the domain-specific representation of the information on which the application operates. Domain logic adds meaning to raw data (e.g., calculating if today is the user's birthday, or the totals, taxes, and shipping charges for shopping cart items). Many applications use a persistent storage mechanism (such as a database) to store data. MVC does not specifically mention the data access layer because it is understood to be underneath or encapsulated by the Model.

The view renders the model into a form suitable for interaction, typically a user interface element. Multiple views can exist for a single model for different purposes.

The controller is responsible for processing and responding to events, typically user actions, and may invoke changes on the model.

Create an ASP.Net Web Application project in Visual Studio 2005. Name the new project GettingStartedSample then click the OK button.

To make the new project into a MonoRail application you will need to add references to the MonoRail assemblies. For the purposes of our sample application the assemblies listed below will be required.

The next step is to create the following folders on the project. Again, this is just a convention we encourage you to follow - you may come up with a more suitable convention for your projects after you get used to the framework so this is no way mandatory.

To configure the application additional information needs to be added to the web.config file; you must register the MonoRail configuration handler, the MonoRail configuration section, an HTTP handler and an HTTP module. Each of these will be discussed further below.

First, add the MonoRail configuration handler:

<configuration>
	<configSections>
		<section 
			name="monorail" 
			type="Castle.MonoRail.Framework.Configuration.MonoRailSectionHandler, Castle.MonoRail.Framework" />
	</configSections>
	
	...

Next add the <monorail> configuration section.

	...
	
	<monorail>
		<controllers>
			<assembly>GettingStartedSample</assembly>
		</controllers>
		
		<viewEngines viewPathRoot="Views">
			<add type="Castle.MonoRail.Framework.Views.NVelocity.NVelocityViewEngine, Castle.MonoRail.Framework.Views.NVelocity" />
		</viewEngines>
	</monorail>
	
	...

This is the section that will contain all the configuration that controls setting up and customizing the behavior of MonoRail itself. The elements included for our sample above are the <controllers> node that defines the list of assemblies that contain the controllers for the application and the <viewEngines> node the specifies the view engine that will handle rendering the view templates in the application. There are more configuration options available in the Configuration chapter, however the elements above are sufficient for this sample.

It should be noted at this point that we have chosen the NVelocity view engine for rendering the views in our application. NVelocity is a very simple template engine that supports conditional statements, assignments, array creation, and iteration over collections that provides all the functionality you will generally need during the rendering of a view. You can learn more about NVelocity (and how we have improved it) on its page .

Next we will add a couple of HTTP Handlers under the <httpHandlers> node in the <system.web> section of the web.config .

...
	
	<system.web>
		<httpHandlers>
		
			<add 
				verb="*" 
				path="*.castle" 
				type="Castle.MonoRail.Framework.MonoRailHttpHandlerFactory, Castle.MonoRail.Framework" />
			
			<add 
				verb="*" 
				path="*.vm" 
				type="System.Web.HttpForbiddenHandler"/>
				
		</httpHandlers>
		
		...
-

The first HTTP Handler is responsible for routing incoming requests to MonoRail based on their extension. The example above indicates that incoming requests ending in .castle should be handled by MonoRail. If you prefer another extension such as .rails you can simply change the value of the path attribute to your preferred value.

The second handler is present as a security consideration. It is important to to be aware that if a file in a web folder is accessed from the outside world its contents will normally be sent directly to the calling browser. To prevent the source for your view files from being visible to the outside world an HttpForbiddenHandler needs to be configured for the file extension of any files you don't want want to be directly accessible. In this case, because we chose to use the NVelocity view engine and our view templates use the .vm extension this is the extension we have associated with the HttpForbiddenHandler .

Finally you need to register the MonoRail HTTP module that handles incoming requests into the <httpModules> node, which is also found in the <system.web> section.

		...
		
		<httpModules>
			<add 
				name="monorail" 
				type="Castle.MonoRail.Framework.EngineContextModule, Castle.MonoRail.Framework" />
		</httpModules>
	</system.web>
	
</configuration>

That's it - the configuration is now complete. Next we will start exploring controllers, actions and views.

First, add references to the assemblies required for ActiveRecord Scaffolding support:

Next, create the controller that will provide the CRUD functions for the Supplier class:

namespace GettingStartedSample.Controllers
{
	using System;
	using Castle.MonoRail.Framework;
	using GettingStartedSample.Models;

	[Scaffolding(typeof(Supplier))]
	public class SupplierController : Controller
	{
	}
}

You may notice that the controller does not contain any code at all. This is because the addition of the ScaffoldingAttribute decoration on the controller class tells MonoRail that this is a Scaffolding controller so all the additional functionality is automatically provided.

If you use Scaffolding for your CRUD functionality that is it - all the features have automatically been added. If you visit the url /supplier/list.castle you will see that the list page is automatically provided along with all the navigation features and links to add, remove and modify supplier data in the database.

The supplier list

Adding a supplier

First, lets look at creating the the List action on the controller. This action will present a list of the Product data from the database.

public void List()
{
	PropertyBag["products"] = Product.FindAll();
}

The call to the static FindAll method on the Product in the code above gets all the Product items from the database which are then made available to the view by passing them to the PropertyBag . The FindAll method, amongst others, is exposed by the ActiveRecordBase class that we used as the base class for our Product .

Next, build the view to go with the List action by creating the list.vm file with the following content in the /views/product folder.

<h3>Product list</h3>

<p>
<a href="new.castle">Create new Product</a>
</p>

<table width="100%" border="1" cellpadding="2" cellspacing="0">
<tr>
	<th>Id</th>
	<th>Name</th>
	<th>Supplier</th>
	<th>&nbsp;</th>
</tr>
#foreach($product in $products)
<tr>
	<td align="center">$product.Id</td>
	<td align="center">$product.Name</td>
	<td align="center">$product.Supplier.Name</td>
	<td align="center">
		<a href="edit.castle?id=${product.Id}">Edit</a> | 
		<a href="delete.castle?id=${product.Id}">Delete</a>
	</td>
</tr>
#end
</table>

At this stage you can see the results of the List action and view by visiting the /product/list.castle url in your browser.

To create a new product we will use two actions; one that will present the form on which the user can provide the information about the new product and another that will store the provided data into the database. First, create the New action that will present the user with the form.

public void New()
{
	PropertyBag["suppliers"] = Supplier.FindAll();
}

This action, apart from displaying the form to the user provides all the existing suppliers available to the view so it can populate a select element to choose a supplier from.

Now add the view associated with the New action by creating the new.vm file in the /views/product folder and populate it with the following content:

<h3>New Product</h3>

#if($Flash.error)
<p style="color: red; font-weight: bold;">
	$Flash.error
</p>
#end

<form action="create.castle" method="post">

	<p>
	Name: $FormHelper.TextField("product.name")
	</p>

	<p>
	Price: $FormHelper.TextFieldFormat("product.price", "000.00")
	</p>

	<p>
	Supplier: $FormHelper.Select("product.supplier.id", $suppliers, "%{value='Id', text='Name'}")
	</p>

	<hr/>

	<p>
	<input type="submit" value="Create" />
	</p>

</form>

Finally, add the Create action to handle the data submitted from the form by the user.

public void Create([DataBind("product")] Product prod)
{
	try
	{
		prod.Create();
	
		RedirectToAction("list");
	}
	catch(Exception ex)
	{
		Flash["error"] = ex.Message;
		Flash["product"] = prod;
		
		RedirectToAction("new");
	}
}

This method is using data binding to bind the form data into the prod parameter which then uses the Create method from the ActiveRecordBase base class of the Product class. The Create method will add the Product into the database. Once the Product has been created this action will redirect the user back to the List action created earlier.

You can now test your work by accessing the New action using the /product/new.castle url.

Building the update functionality is very similar to the process used when building the create feature. Again there will be two actions; one that presents a form for editing a Product and another for saving the changes after the form has been submitted.

First, create the two actions for edit and update:

public void Edit(int id)
{
	PropertyBag["product"] = Product.FindById(id);
	PropertyBag["suppliers"] = Supplier.FindAll();
}

public void Update([DataBind("product")] Product prod)
{
	try
	{
		prod.Update();
	
		RedirectToAction("list");
	}
	catch(Exception ex)
	{
		Flash["error"] = ex.Message;
		Flash["product"] = prod;
		
		RedirectToAction("edit", "id=" + prod.Id);
	}
}

The Edit action will present the form to the user and provide all the relevant data to the form. The Update action will handle saving the changes submitted by the user and redirecting the ser back to the List action.

We can also overload the Edit action method. This overload will be used specifically when an error is caught by the Update action. In the catch handler the action redirects the user back to the edit page so they can correct any errors. Also of note is the FlashBinder which allows you to bind data to parameters from the Flash rather than from Request or Post data.

public void Edit(int id, [FlashBinder] Product product)
{
	PropertyBag["suppliers"] = Supplier.FindAll();
}

Next, we'll create the edit view. The edit.vm template is very similar to the new.vm template created in the last section; it will be responsible for displaying the form for editing the product.

<h3>Edit Product</h3>

#if($Flash.error)
<p style="color: red; font-weight: bold;">
	$Flash.error
</p>
#end

<form action="update.castle" method="post">

$FormHelper.HiddenField("product.id")

	<p>
	Name: $FormHelper.TextField("product.name")
	</p>

	<p>
	Price: $FormHelper.TextFieldFormat("product.price", "000.00")
	</p>

	<p>
	Supplier: $FormHelper.Select("product.supplier.id", $suppliers, "%{value='Id', text='Name'}")
	</p>

	<hr/>

	<p>
	<input type="submit" value="Update" />
	</p>

</form>

In the code above we've used the FormHelper which is clever enough to populate the fields and select the correct item on the form's select element.

The last in our CRUD series, the delete step is the easiest one; simply add the Delete action to the controller with the following code.

public void Delete(int id)
{
	Product product = Product.FindById(id);
	
	product.Delete();
	
	RedirectToAction("list");
}

This action will be called when the user clicks the delete link on the list page. It gets the if of the product using automatic data-binding, finds the product, deletes it and redirects back to the list page.

Some view engines implementation allow you to use assemblies resources to store views, beside the file system. This is a good approach to reuse controllers among projects.

To bind DateTime fields you can pass a single value or multiple values. Each of them will be a part of the DateTime struct. For example, using a single value:

<form action="SaveValues.rails" method="post">
	<input type="text" name="dob" value="1/1/2000"/> 
</form>

Using multiple values:

<form action="SaveValues.rails" method="post">
	<input type="text" name="dobday" value="16" />
	<input type="text" name="dobmonth" value="7"/> 
	<input type="text" name="dobyear" value="1979" />
	<input type="text"name="dobhour" value="4" /> 
	<input type="text" name="dobminute" value="0" /> 
	<input type="text" name="dobsecond" value="0" />
</form>

Regardless of the form approach, the controller action parameter will be the same:

using Castle.MonoRail.Framework;

public class UserController : SmartDispatcherController 
{ 
	public void SaveValues(DateTime dob) 
	{ 
		... 
	} 
}

Nullables data types are also supported. They will only be populated if the values are present on the form and in non-empty fields.

Arrays are also supported on the controller side. You can use two naming approaches on the form elements to make it work.

The first approach is to repeat the element name. For example:

<form action="SaveValues.rails" method="post">
	<input type="text" name="name" value="1" />
	<input type="text" name="name" value="2" />
	<input type="text" name="name" value="3" />
	<input type="text" name="name" value="4" />
	<input type="text" name="name" value="5" />
</form>

The second approach is to use the indexed value notation. The index value is meaningless to MonoRail, but it must be unique per element name. For example:

<form action="SaveValues.rails" method="post">
	<input type="text" name="name[0]" value="1" />
	<input type="text" name="name[1]" value="2" />
	<input type="text" name="name[2]" value="3" />
	<input type="text" name="name[3]" value="4" />
	<input type="text" name="name[4]" value="5" />
</form>

On the controller side, the parameter will be the same independently of the approach in use. All you need to do is to use an array type:

using Castle.MonoRail.Framework;

public class UserController : SmartDispatcherController 
{ 
	public void SaveValues(string[] name) 
	{
		 ... 
	} 
}

If instead of working with flat values you want to populate an object, this is also possible using the DataBindAttribute .

The DataBindAttribute used the Castle.Component.Binder to instantiate and populate the target type. Simple values, nested objects and arrays are supported. As with simple binding, a name convention must be used on the form elements, so the binder can do its work.

First of all you must use a prefix which is required to avoid name clashing. It is as giving the form elements a name space. The form below uses product as a prefix:

<form method="post" action="create.rails">
	<input type="text" name="product.id" />
	<input type="text" name="product.name" />
	<input type="checkbox" name="product.inStock" id="" value="true" /> 
</form>

On the controller action you must specify the prefix as the argument to the DataBindAttribute :

using Castle.MonoRail.Framework;

public class ProductController : SmartDispatcherController 
{ 
	public void Create([DataBind("product")] Product prod) 
	{
	} 
}

The binding of values happens with writable properties only. Fields are never used. The Product class used on the example above would be:

public class Product 
{ 
	private int id; 
	private String name; 
	private bool inStock;

	public int Id 
	{ 
		get { return id; } 
		set { id = value;}
	}

	public string Name 
	{ 
		get { return name; } 
		set { name = value; } 
	}

	public bool InStock 
	{ 
		get { return inStock; } 
		set { inStock = value; } 
	} 
}

Nested objects are supported with no deep limit. Suppose the Product class above included a SupplierInfo :

public class Product 
{ 
	private SupplierInfo supplierInfo;

	// others fields omitted

	public SupplierInfo SupplierInfo 
	{ 
		get { return supplierInfo; } 
		set { supplierInfo = value; } 
	}

	// others properties omitted 
}

The declaration of SupplierInfo follow. Note that it uses different types, including an enumerator.

public enum WeightUnit 
{ 
	Kilos, 
	Pounds 
}

public class SupplierInfo 
{ 
	private String brand;
	private float weight; 
	private WeightUnit weightUnit;
	private int warrantyInMonths;

	public string Brand 
	{ 
		get { return brand; } 
		set { brand = value; } 
	}

	public float Weight 
	{
		get { return weight; } 
		set { weight = value; } 
	}

	public WeightUnit WeightUnit 
	{ 
		get { return weightUnit; } 
		set { weightUnit = value; } 
	}

	public int WarrantyInMonths 
	{ 
		get { return warrantyInMonths; } 
		set { warrantyInMonths = value; } 
	} 
}

When adding elements on the form, all you have to care is to include the property name. For the case above it would be:

<form method="post" action="create.rails">
	<input type="text" name="product.id" />
	<input type="text" name="product.name" />
	<input type="checkbox" name="product.inStock" id="" value="true" />

	<input type="text" name="product.supplierinfo.brand" /> 
	<input type="text" name="product.supplierinfo.Weight" />

	<select name="product.supplierinfo.WeightUnit">
		<option value="Kilos">In Kg</option>
		<option value="Pounds">In Pounds</option> 
	</select>

	<input type="text" name="product.supplierinfo.WarrantyInMonths" />

</form>

The rule is prefixname.propertyname1.propertyname2... . The binder is not case sensitive.

There are two situations for array support. First, suppose instead of populating a single Product you would want to populate a sequence of them. This demands two changes in the example we have seen so far.

First the form elements must use the indexed notation discussed earlier:

<form method="post" action="create.rails">
	<input type="text" name="product[0].id" />
	<input type="text" name="product[0].name" />
	<input type="checkbox" name="product[0].inStock" id="" value="true" />

	<input type="text" name="product[1].id" />
	<input type="text" name="product[1].name" />
	<input type="checkbox" name="product[1].inStock" id="" value="true" /> 
</form>

Second, on the controller you must declare the parameter as an array of Product s:

using Castle.MonoRail.Framework;

public class ProductController : SmartDispatcherController 
{ 
	public void Create([DataBind("product")] Product[] prods) 
	{
	} 
}

The rule is prefixname[uniqueindex].propertyname1.propertyname2... . The index must be a number, and the same number identifies the same instance.

Another situation is when one or more properties of the binding target are arrays. This case is also supported and not different from what we have seen.

Being practical, suppose the Product class in the example above included a Category array.

public class Product 
{ 
	private Category[] categories;

	// others fields omitted

	public Category[] Categories 
	{ 
		get { return categories; } 
		set { categories = value; } 
	}

	// others properties omitted 
}

It could also be an array of simple values like String s or int s and the solution would be the same. The declaration of the Category follows:

public class Category 
{
	private String name;

	public string Name 
	{ 
		get { return name; } 
		set { name = value; } 
	} 
}

One more time the solution lies on the element names on the form. The property name must be used in the indexed notation:

<form method="post" action="create.rails">
	<input type="text" name="product.id" />
	<input type="text" name="product.name" />
	<input type="checkbox" name="product.inStock" id="" value="true" />

	<input type="checkbox" name="product.categories[0].name" value="Kitchen"/> 
	<input type="checkbox" name="product.categories[1].name" value="Bedroom"/> 
	<input type="checkbox" name="product.categories[2].name" value="Living-room" /> 
</form>

The rule is this case would be prefixname.propertyname1[uniqueindex].propertyname2... .

Generic Lists are supported and the behavior is the same of the arrays, expect the property declaration of course.

public class Product 
{ 
	private List<Category> categories;

	// others fields omitted

	public List<Category> Categories 
	{ 
		get { return categories; } 
		set { categories = value; } 
	}

	// others properties omitted 
}

By default the binder will use the Params collection as source of information to bind data. You can define that it should use the QueryString or Form post data instead. To do that use the From property exposed by the DataBindAttribute .

This is a recommend practice for performance and to prevent people from easily override form parameters. For example:

using Castle.MonoRail.Framework;

public class ProductController : SmartDispatcherController 
{ 
	public void Create([DataBind("product", From=ParamStore.Form)] Product product) 
	{ 
		... 
	} 
}

As the DataBindAttribute usually act on domain model classes, you might not want that all properties be "bindable". Suppose you are binding an User class. Sensitive properties might allow overriding the password, roles, access levels or audit information. For these cases you can use Allow and Exclude properties of DataBindAttribute .

The values for these properties are a comma separated list of property names, including the prefix. For example:

public class AccountController : SmartDispatcherController 
{ 
	public void CreateAccount([DataBind("account", Allow="account.Name, account.Email, account.Password")] Account account) 
	{ 
		... 
	} 
}

This indicates that you only want to allow the Name , Email and Password properties to bound with the values from the request. All other properties will be ignored.

The Exclude property is the inverse. It prevents the properties indicated from being used, and allow all others.

There is no depth limit. You should be able to allow or exclude properties in any level of the object graph. For example:

public class AccountController : SmartDispatcherController 
{ 
	public void CreateAccount([DataBind("account", Allow="account.Name, account.Address, account.Address.Street")] Account account) 
	{ 
		... 
	} 
}

Binding errors might ocur, like invalid dates or problems in data conversion. When using simple binding, an exception will be thrown. When using the DataBindAttribute , however, no exception will be thrown.

To access the error information, use the GetDataBindErrors method:

public class AccountController : SmartDispatcherController 
{ 
	public void CreateAccount([DataBind("account")] Account account)
	{ 
		ErrorList errors = GetDataBindErrors(account);
		... 
	} 
}

The ErrorList implements the ICollection so you can enumerate the problems. You can also check if some specific property could not be converted. For example:

public class AccountController : SmartDispatcherController 
{
	public void CreateAccount([DataBind("account")] Account account) 
	{ 
		ErrorList errors = GetDataBindErrors(account);

		if (errors.Contains("DateOfBirth")) 
		{ 
			Flash["error"]= errors["DateOfBirth"].ToString(); // Or Exception
			RedirectToAction("New", Params); 
		}

		... 
	} 
}

You do not need to always use parameters to have an object bound. The methods BindObject and BindObjectInstance , exposed by the SmartDispatcherController , allow you to have the same functionality. The benefit is that not under every case you want to perform the bindings. For example:

public class AccountController : SmartDispatcherController 
{ 
	public void CreateAccount(bool acceptedConditions) 
	{ 
		if(acceptedConditions) 
		{ 
			Account account = (Account)BindObject(ParamStore.Form, typeof(Account),"account");
			... 
		}

		... 
	} 
}

The following types are natively supported by the DataBinder component:

The FormHelper was created to act together with the binder. It is able to create form elements with the right names and to obtain the existing value (if possible) saving you from populating the elements manually.

For more on the FormHelper visit the Helpers documentation pages.

Suppose you have a list of about 200 items to display. Using MonoRail it is easy to create a pagination for that items, such that only 20 at a time are displayed:

public class HomeController : SmartDispatcherController
{
	public void Index()
	{
            PropertyBag["items"] =
                PaginationHelper.CreatePagination<MyEntity>(
                    this, // controller
                    MyEntity.FindAll(new Order("Index", true)), // list
                    10 // number of items per page
                );
	}
}

items is an instance of IPaginatedPage . It can be used like a list in NVelocity templates. Additionally, it has properties to determine the current status of the pagination. These properties can be used to create pagination links, which is described in the PaginationHelper documentation.

However, building pagination links is a repeating task that should be automated. This is what the DiggStylePaginationComponent does.

<table>
	<tr>
		<th>Name</th>
		<th>Index</th>
	</tr>
#foreach($row in $items)
	<tr>
		<td>$row.Name</td>
		<td>$row.Index</td>
	</tr>
#end
	<tr>
    	<td colspan="2">
#component(DiggStylePagination with "page=$items")
		</td>
	</tr>
</table>

This creates a production ready pagination line as shown in the picture below:

When creating a non-english application, the labels « prev and next » don't make any sense. This can be changed by using a DiggStylePagination blockcomponent and sections to customize the link text:

...data same as above...
<tr>
    <td colspan="2">
#blockcomponent(DiggStylePagination with "page=$items")
    #prev
        &laquo;
    #end
    #next
        &raquo;
    #end
#end
    </td>
</tr>

You can see the results below. Pay attention to encircled links.

The problem is that if there are less items than the specified page size, the pagination is still displayed.

This can be suppressed by specifiying the parameter RenderIfOnlyOnePage .

...data same as above...
<tr>
    <td colspan="2">
#component(DiggStylePagination with "page=$items" "renderifonlyonepage=false")
    </td>
</tr>

This removes the pagination itself from the page, but the surrounding table cell is still rendered. In this example this is visible by a thicker bottom border, but depending on the stylesheet this might lead to more ugly effects.

To prevent this, it is possible to render the surrounding HTML by using the sections startblock and endblock . That way the HTML is only rendered when the pagination is needed.

...data same as above...
#blockcomponent(DiggStylePagination with "page=$items" "renderifonlyonepage=false")
#startblock
<tr>
    <td colspan="2">
#end
#endblock
    </td>
</tr>
#end
#end

Rectangular, button-like links are perhaps not your preferred style of displaying the pagination. When you need to change the way links are displayed, you must do so by using CSS classes.

DiggStylePaginationComponent emits the style within the HTML links, so you need to both specify CSS classes and force the component to use these classes.

...data same as above...
<tr>
    <td colspan="2">
#component(DiggStylePagination with "page=$items" "useinlinestyle=false")
    </td>
</tr>

This results in the following HTML rendered:

<div class="pagination">
	<span class="disabled">&laquo; prev</span>
	<span class="current">1</span>
	<a href="/home/index6.rails?page=2">2</a>
	<a href="/home/index6.rails?page=3">3</a>
	<a href="/home/index6.rails?page=4">4</a>
	<a href="/home/index6.rails?page=5">5</a>
	<a href="/home/index6.rails?page=6">6</a>
	&#8230;<a href="/home/index6.rails?page=19">19</a>
	<a href="/home/index6.rails?page=20">20</a>
	<a href="/home/index6.rails?page=2">next &raquo;</a>
</div>

This allows you to customize the output using the following CSS classes:

Additionnally, you must specify CSS commands for .pagination a if you want to customize the links themselves.

Here is a comprehensive example that shows all four options:

<style type="text/css" media="screen">
    .pagination {
        /* Complete box */
        background-color: yellow;
        font-size: large;
    }
    
    .pagination a {
        /* links */
        color: red;
    }
    
    .disabled {
        /* disabled "buttons" */
        color: purple;
    }
    
    .current {
        /* current page */
        color: blue;
    }
</style>

This one renders like shown below:

If you have a look at the pictures above, you might have noticed that not all pages are linked. By default, only the two pages before and after the current page are linked directly to save space. It is possible to customize the number of links to be displayed on each side of the current page before the ellipsis with the parameter adjacents .

However, the algorithm used doesn't work well with large numbers, so you should use one of the following values:

So far, we have only changed how the links are displayed. This is good enough for simple pages, but if you provide means of searching or filtering the data, you must come up with a possibility to save the parameters for fetching data of the different pages.

Though it is not directly visible to the programmer, any time a different page is displayed, there is a roundtrip to the server using the original controller action. This means that for paging search results, you must pass the search parameters to the controller along with the pagination links.

This can be done using different techniques:

<table>
	<tr>
		<th>Name</th>
		<th>Index</th>
	</tr>
#foreach($row in $items)
	<tr>
		<td>$row.Name</td>
		<td>$row.Index</td>
	</tr>
#end
	<tr>
		<td colspan="2">
#set ($url="index8.rails?desc=$desc")
#component(DiggStylePagination with "page=$items" "url=$url")
## The statement below won't work!
##component(DiggStylePagination with "page=$items" "url='index8.rails?desc=$desc'")
		</td>
	</tr>
</table>
<a href="index8.rails">Ascending list</a> &mdash; 
<a href="index8.rails?desc=true">Descending list</a>

...data same as above...
<tr>
    <td colspan="2">
#component(DiggStylePagination with "page=$items" "paginatefunction=foo")
    </td>
</tr>
<script type="text/javascript">
    function foo(page)
    {
        var a = new AjaxMagicObject();
        a.page = page;
        a.fetchAndDisplayData();
    }
</script>

Building Links the #link

If all else fails, you can provide a block for creating the links. Just be warned, this should really be used only if all else fails; because there is no automation, you need to create all the HTML by yourself.

To build your links, you get the following variables as parameters:

• $pageIndex contains the page number of the link to render.

• $url contains the url to the controller action. If it wasn't specified via the url-parameter discussed above, it is simple an URL to the current page.

• $text contains the text that would have been rendered by the default render functions. This is either a number, prev, next or a custom text specified using #prev or #next .

To get a working pagination, you must not forget to pass a parameter named page to the controller action.

Using #link has the caveat, that it is not called for

• rendering the current page

• rendering ellipsis

• rendering disabled links

The following examples renders all links as buttons. The (imperfect) result is shown below.

<tr>
    <td colspan="2">
#blockcomponent(DiggStylePagination with "page=$items")
#link
<button type="button" onclick="location.href='$url?page=$pageIndex';">$text</button>
#end
#end
    </td>
</tr>

Use the name of the component followed by a dictionary string. For more information on dictionary expressions see [[MonoRail:NVelocity]]

#component(MyFirstComponent "%{firstParam='some value',anotherParam='other value'}")

You can then access the parameters from the component code:

public class MyFirstComponent: ViewComponent
{
	public override void Render()
	{
		object param1 = Context.ComponentParameters["firstParam"];
		object param2 = Context.ComponentParameters["anotherParam"];

		...
	}
}

In this case you need to use the keyword with followed by a sequence of key/value pairs:

#component(ComponentName with "name=john" "address=some address")

You're free to use interpolation as well

#component(ComponentName with "name=${customer.name}")

You can gain access to the component parameters using the Context.ComponentParameters too.

Every data type is supported. However literal values will be automatically converted to text. If you want to specify a different type, create a varible on NVelocity or use some structure data available on the view.

The parameter value below will be converted to string

#component(ComponentName with "age=1")

The parameter value below will remain an Int32

#set($age = 27)
#component(ComponentName with "age=${age}")

The view snippet:

#blockcomponent(SecurityComponent with "role=admin")
  this will only be rendered if the current user is in the specified role
#end

The component code:

using Castle.MonoRail.Framework;

namespace WebApp
{
	public class SecurityComponent : ViewComponent
	{
		bool shouldRender;
	
		public override void Initialize()
		{
			String role = ComponentParameter["role"] as String;
			shouldRender = RailsContext.User.IsInRole( role );
 		}

		public override void Render()
		{
			if (shouldRender) Context.RenderBody();
 		}
	}
}

First of all you must reference the following assemblies. Copy them to the bin folder if you are not using Visual Studio.

The Boo.* files are required for the language support. The anrControl.Markdown.dll is required for support Markdown formatting.

Edit your web.config file to include the following line (in the monoRail config section, of course):

<viewEngine 
	viewPathRoot="Views" 
	customEngine="Castle.MonoRail.Views.Brail.BooViewEngine, Castle.MonoRail.Views.Brail" />

And that is it, you are now capable of using Boo scripts to write views in MonoRail! Now that you can use it, let's see what you can do with it.

Before we get to how to use it, I must send huge thanks to the Boo Community, for being so helpful.

If your view directory is in the web directory, it's wise to not allow the files to be read through http. So under the system.web/httpHandlers configuration you should add the following:

<add verb="*" path="*.brail" type="System.Web.HttpForbiddenHandler"/>
<add verb="*" path="*.brailjs" type="System.Web.HttpForbiddenHandler"/>

First, Brail scripts are not normal Boo programs, they ''require'' that you would have at least one statement at the global namespace, which is what MonoRail will end up calling when your view is invoked. Assuming that you've already have a controller, and that you've setup your environment correctly, you can simply do this:

Hello, World!

Brail will take this script, compile it and send its output to your browser. The nice thing about it is that if you would change it to say:

Hi, World!

You will instantly get a the updated view, this is highly important to development scenario.

You can also use parameters that the controller has put in the Property Bag or Flash, like this:

Hi, ${User}!

If you are wondering how does it work behind the scenes: the script is loaded and compiled. There is some magic there that sends anything not wrapped in <% %> directly to the user (which will also expand ${arg} expression to their values). The compiled code is cached, so you pay the compilation cost only once.

<html>	
	<head>		
		<title>${title}</title>
	</head>	
	<body>	    
	     <p>The following items are in the list:</p>  
	     <ul><%for element in list:	output "<li>${element}</li>"%></ul>
	     <p>I hope that you would like Brail</p>	
	</body>
</html>

The output of this program (assuming list is (1,2,3) and title is "Demo" ) would be:

<html>   
	<head>        
		<title>Demo</title>   
	</head>    
	<body>        
     <p>The following items are in the list:</p> 
     <ul><li>1</li><li>2</li><li>3</li></ul>
	</body>
</html>

And the rendered HTML will look like this:

----
The following items are in the list:	
* 1
* 2
* 3
-----

Consider the following this code:

<%
for user in users:
	output "<p>${user.Name} - ${user.Email}</p>"
end
%>

Looks simple, right? The problem is that Brail doesn't really know what user is, so it uses reflection to get the values of the Name and Email properties. This is, of course, quite expensive in performance terms. What is the solution? You need to tell Brail to add a reference to the assembly where User is defined. You can do that by adding this line to your web.config file (see the full configuration section below for more details).

<Brail>
     <reference assembly="assembly.with.user.object" />
</Brail>

And then, in your view code, you write:

<%
import My.Models
%>
<!-- lots of html code ->
<%
for user as User in users:
	output "<p>${user.Name} - ${user.Email}</p>"
end
%>

You can also use this out side of loops, in order to get strong typing (and the assoicated performance benefits):

<%
import My.Models
%>
<!-- lots of html code ->
<%
# define a parameter called user of type User
user as User = GetParameter("user")
# now it uses strong typing, instead of reflection
output "<p>${user.Name} - ${user.Email}</p>"
%>

With this simple change, you've completely eliminated the use of reflection and probably increased by a fair margin your application performance. However, because it significantly increases the complexity of developing the views, it is not really the recommended approach. If you run into a situation where the cost of reflection in the views is a significant one, there are other options, which involve improving dynamic dispatch inside of Brail, bringing you the benefits without the cost. This is not implemented currently, because so far we have not run into a situation where this was a problem that warranted the additional complexity.

As you can imagine, it can get tiresome to specify the default imports all over the place, Brail supports automatic imports from the configuration. All you need to do is specify the following in the web.config file:

<Brail>
     	<import namespace="My.Models"/>
</Brail>

And it will be added for you by Brail.

MonoRail receives a request, calls the appropriate controller and then calls to the view engine with the current context, the controller and the view that needs to be displayed. Brail then takes over and does the following:

A few things about changes in the views: Brail currently allows instantaneous replacement of views, layout and common scripts by watching over the Views directory and recompiling the file when necessary, since this is a developer only feature, I'm not worrying too much about efficiency / memory. I'm just invalidating the cache entry or recompiles the common scripts. Be aware that making a change to the Common Scripts would invalidate all the compiled views & layouts in memory and they would all have to be compiled again. This is done since you can't replace an assembly reference in memory.

The interesting stuff is most happening when Brail is compiling a script. For reference, Brail usually will try to compile all the scripts in a directory (but does not recurse to the child directories) in one go, since this is more efficient in regard to speed / memory issues. Occasionally it will compile a script by itself, usually when it has been changed after its directory has been compiled or if the default configuration has been changed. There isn't much difference between compiling a single file and compiling a bunch of them, so I'm just going to ignore that right now and concentrate on compiling a single script. Brail's scripts are actually a Boo file that is being transformed by custom steps that plug into the Boo compiler.

Here is what happens when Brail needs to compile a script:

Creating an instance of BooCompiler, and telling if to compile to memory or to file (configuration option).

When Brail receive a request for a view it looks it up as describe above (from cache/compiled, etc). A new instance of the view is created and its Run() method is called. All the output from the script is sent to the user (directly or via the layout wrapping it.)

The BrailBase class has several useful method and properties:

You can check the source here: https://svn.castleproject.org/svn/castle/trunk/MonoRail/Castle.MonoRail.Views.Brail/BrailBase.cs for the full details

Using the FormHelper is easy and in a few minutes you will understand how it works. Just remember that it requires that the controller and the view work together.

The goal is to generate proper Html elements that can be easily databound on the controller side. The most trivial case is binding single values. For example, you can have a view like the following (using NVelocity View Engine):

<form action="Index.rails" method="post">
$FormHelper.TextField("name")
$FormHelper.TextField("address")
</form>

Whenever this view is rendered, the FormHelper 's TextField method will be invoked. The first thing it does is extract the root target. In the case above the targets are not chained, so the roots will be name and address .

After that it will search in the context dictionaries for the roots, in the following order:

If it finds the entry, it will extract the value and use it. If it doesn't find the entry, no value will be set on the html element.

Suppose the action using the view above (the form definition) is the following:

public void Index()
{
}

For this case, the html output will be:

<form action="Index.rails" method="post">
	<input type="text" id="name" name="name" value="" />
	<input type="text" id="address" name="address" value="" />
</form>

Note the "value" property of both input elements is blank.

However, if the action was:

public void Index()
{
    PropertyBag.Add("name", "hammett");
    PropertyBag.Add("address", "pereira leite, 44");
}

Then the FormHelper would have the values filled:

<form action="Index.rails" method="post">
	<input type="text" id="name" name="name" value="hammett" />
	<input type="text" id="address" name="address" value="pereira leite, 44" />
</form>

The support for autmatically populating Html elements goes beyond input fields. See below for more information on the FormHelper .

Consider a different action code now:

public void Index()
{
    PropertyBag.Add("contact", new Contact("john", "some address", "phone number") );
}

A view for this

<form action="Index.rails" method="post">
	$FormHelper.TextField("contact.name")
	$FormHelper.TextField("contact.address")
	$FormHelper.TextField("contact.phone")
</form>

The FormHelper will find the contact entry in the PropertyBag , and then find the properties name , address and phone . It will extract the values from the item in the PropertyBag and render the view accordingly:

<form action="Index.rails" method="post">
	<input type="text" id="contact_name" name="contact.name" value="john" />
	<input type="text" id="contact_address" name="contact.address" value="some address" />
	<input type="text" id="contact_phone" name="contact.phone" value="phone number" />
</form>

Arrays are also supported. Suppose you have the following action code:

public void Index()
{
	PropertyBag.Add("list", new string[] 
	{
		"value 1", "value 2"
	} );

    PropertyBag.Add("contacts", new Contact[] 
	{ 
		new Contact("john", "address 1", "phone number 1"),
		new Contact("mary", "address 2", "phone number 2")
	} );
}

In this case you have to use the indexed name convention as the target so FormHelper can know from which index it should extract the value:

<form action="Index.rails" method="post">

$FormHelper.TextField("list[0]")
$FormHelper.TextField("list[1]")

$FormHelper.TextField("contacts[0].name")
$FormHelper.TextField("contacts[0].address")
$FormHelper.TextField("contacts[0].phone")

$FormHelper.TextField("contacts[1].name")
$FormHelper.TextField("contacts[1].address")
$FormHelper.TextField("contacts[1].phone")

</form>

The FormHelper will use the index value to find the correct entry. It will generate something like the following:

<form action="Index.rails" method="post">

<input type="text" id="list_0_" name="list[0]" value="value 1" />
<input type="text" id="list_1_" name="list[1]" value="value 2" />

<input type="text" id="contact_0_name" name="contact[0].name" value="john" />
<input type="text" id="contact_0_address" name="contact[0].address" value="address 1" />
<input type="text" id="contact_0_phone" name="contact[0].phone" value="phone number 1" />

<input type="text" id="contact_1_name" name="contact[1].name" value="mary" />
<input type="text" id="contact_1_address" name="contact[1].address" value="address 2" />
<input type="text" id="contact_1_phone" name="contact[1].phone" value="phone number 2" />

</form>

FormHelper supports a broad range of scenarios when dealing with sets. Sets are used when Select and CheckboxList are generated. It is adamant that you know how it works when dealing with sets.

For Select and CheckboxList generation, the common target is considered the initial selection set . The value supplied as the data source is treated as the complete set. The initial selection must be a subset of the data source set.

This is very obvious and works nicely when both sets are composed of primites and both sets have same types. But not every application has this scenario to work with.

The FormHelper makes a few verifications which help it to decide on an approach based on the sets available. See the image below.

If the types are not primitive types, it is up to the programmer to inform the property the element has that identifies the instance, using the value parameter. The programmer can also specify the text parameter which is used to identify the property that returns a descriptive text about the element instance.

The sourceProperty parameter is used to identity the property that should be used on the html element. This is only helpful when the types are different and the identification property on the data source element is different from the identification property on the initial selection elements.

The suffix parameter is used to override the suffix used on the generate element names. FormHelper will always try to use the value specified for the value parameter which is right for almost all situations, but one: when you are dealing with different types on the sets but the initial set is null and the FormHelper won't be able to identify that. So if you have different types and you know in advance that the initial set can be empty or null, specify the suffix parameter.

FormHelper is able to generate single and multi-value selects. Make sure you have read the How FormHelper works with sets document.

public void Index()
{
	// data source
	PropertyBag["primenumbers"] = new int[] { 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47 };
	
	// initial selection
	PropertyBag["oneprime"] = 3;
}

$FormHelper.Select("oneprime", $primenumbers) 

public void Index()
{
	// data source
	IList authors = new Author[] 
	{ 
		new Author(1, "hammett"), 
		new Author(2, "john doe"), 
		new Author(3, "someone else")
	};
	PropertyBag["authors"] = authors;
	
	// initial selection
	Blog blog = new Blog();
	blog.Author = new Author(1, "hammett");
	PropertyBag["blog"] = blog;
}

$FormHelper.Select("blog.author.id", $authors, "%{value='id', text='Name', firstoption='Please select'}")

public void Index()
{
	// data source
	PropertyBag["primenumbers"] = new int[] { 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47 };
	
	// initial selection
	PropertyBag["multipleprimes"] = new int[] { 3, 5, 7 };
}

$FormHelper.Select("multipleprimes", $primenumbers, "%{multiple='true', style='width: 110px; height: 90px;'}")  

FormHelper allows you to generate a list of checkboxes associated with a data source. It is also able to pre-check the checkboxes based on the initial selection set. Make sure you have read the How FormHelper works with sets document.

Listing checkboxes requires a state object. To create it you invoke CreateCheckboxList which returns a CheckboxList instance. A CheckboxList is enumerable and exposes an Item and a LabelFor method. You must enumerate the elements and while doing it invoke Item which returns the checkbox element. LabelFor adds a label-tag to the caption that allows the user to click the caption as well as the checkbox itself.

Consider the following action code:

public void Index()
{
	// data source
	PropertyBag["primenumbers"] = new int[] { 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47 };
	
	// initial selection
	PropertyBag["selectedPrimes"] = new int[] { 11, 19, 29 };
}

The code on the view to use it would be:

<p>
#set($items = $FormHelper.CreateCheckboxList("selectedPrimes", $primenumbers))

#foreach($elem in $items)
  $items.Item() $items.LabelFor($elem) <br/>
#end
</p>

With complex objects you must care to specify the value parameter so the FormHelper can generate proper html elements.

Consider the following action code:

public void Index()
{
	// data source
	Category[] categories = new Category[] 
	{ 
		new Category(1, "Music"), 
		new Category(2, "Humor"), 
		new Category(3, "Politics")  
	};
	PropertyBag["categories"] = categories;
	
	// initial selection
	Blog blog = new Blog();
	blog.Categories = new Category[] { new Category(2, "Humor") };
	PropertyBag["blog"] = blog;
}

The Category class above has an Id property and Name property. So here is how the view would use it:

<p>
#set($items = $FormHelper.CreateCheckboxList("blog.categories", $categories, "%{value='Id'}"))

#foreach($elem in $items)
  $items.Item()  $elem.Name   <br/>
#end
</p>

The For method generates a URL from the specified parameters. For example:

$UrlHelper.For("%{action='Save'}")

This generates a complete URL for a controller and and action. With no controller specified, the controller from the current context is used. The action was defined in the parameter list as "Save".

All of the UrlHelper methods accept a set of parameters to control the building of the URL. The list of possible parameters are defined below.

Use the Link method to generate a complete HTML link.

$UrlHelper.Link("Edit Trainer", "%{action='Edit', 'querystring='id=$trainer.id'}")

The above produces a link that would look like this (assuming the current controller is called "Trainer":

<a href="/virtualdir/Trainer/Edit.castle?id=45">Edit Trainer</a>

In the example above, the extension ".castle" is pulled from the current Monorail configuration.

You may also add a second set of parameters used to add atributes to the generated anchor:

$UrlHelper.Link("Edit Trainer", "%{action='Edit', 'querystring='id=$trainer.id'}", "%{target='_new'}")

Produces:

<a href="/virtualdir/Trainer/Edit.castle?id=45" target="_new">Edit Trainer</a>

The $UrlHelper.ButtonLink method works the same way as the $UrlHelper.Link method, except an HTML button is generated with some javascript to handle the onclick event to navigate to the URL.

The more you know about the prototype library, the better. We recommend the Developer Notes for prototype.js although it is a little outdated.

The prototype library has two main classes to perform remote requests:

The following parameters can be used on both Ajax.Request and Ajax.Updater :

When you specify the parameter update or success or failure , the AjaxHelper will generate an Ajax.Updater call. The following parameters applies to it:

Callbacks can also be used. The prototype will invoke the specified javascript functions during different steps in the remote invocation.

You can also specify that a function must be executed before, after or define it as a condition to the Ajax request be issue.

Note that the OnSuccess and OnFailure callbacks will include a parameter called request which is the original XmlHttpRequest object. Your callback function will need to have a parameter called request to operate properly.

The best and easiest way to use the AjaxHelper is to check the API documentation to identify the method you want. Check its signature. Most of them will have an IDictionary parameter. This is an approach to make the ajax usage on views more self-documented.

The method API documentation should highlight required parameters or special meanings that a parameter might have. Note that the common parameters discussed above applies to most of the methods on AjaxHelper.

The following snippets shows the AjaxHelper in action.

$AjaxHelper.LinkToRemote("Show server time", "showtime.rails", "%{update='maindiv', OnSuccess='showSuccessMessage(request)'}") 

The Behaviour javascript library allow you to use CSS selectors to bind object's events to javascript functions.

The AjaxHelper exposes a few methods related to Behaviour.

If you change your document object model dynamically you can reapply the rules defined within Behavior. In this case use ReApply which renders a script block invoking Behavior.apply() .

Behavior binds itself to the window.onload event. In the case you want to use it as well, invoke AddLoadEvent(String loadFunctionName) .

var myrules = {
	'b.someclass' : function(element){
		element.onclick = function(){
			alert(this.innerHTML);
		}
	},
	'#someid u' : function(element){
		element.onmouseover = function(){
			this.innerHTML = "BLAH!";
		}
	}
};

$AjaxHelper.StartBehaviourRegister()
$AjaxHelper.Register("b.someclass", "onclick", "functionName")
$AjaxHelper.Register("#someid u", "onmouseover", "function(){ this.innerHTML = 'BLAH!'; }")
$AjaxHelper.EndBehaviourRegister()

MonoRail includes the ability to generate a proxy object in javascript to invoke actions on controllers. For example, suppose you have the following controller:

using Castle.MonoRail.Framework;

public class AdminController : SmartDispatcherController
{
	public void Index()
	{
	}

	[AjaxAction]
	public void DisableUser(int userId)
	{
		// Do something important here
		RenderText("Done");
	}

	[AjaxAction]
	public void ChangeUserPassword(int userId, String newPassword)
	{
		// Do something important here
		RenderText("Done");
	}
}

The methods you want to generate proxies for need to be marked with the attribute AjaxActionAttribute .

On the view side, you can use the following methods to generate a javascript block that uses AjaxRequest class to invoke the actions.

In the view for the Index action of AdminController we can generate a proxy:

$AjaxHelper.GetJavascriptFunctions()
$AjaxHelper.GenerateJSProxy("myproxy")

The GenerateJSProxy call will generate a js block that uses Ajax.Request to make a remote invocation:

<script type="text/javascript" src="/MonoRail/Files/AjaxScripts.rails"></script>
<script type="text/javascript">var myproxy =
{ 

	DisableUser:
	function(userId, callback)
	{
		var r=new Ajax.Request('/admin/DisableUser.rails',
		{
			parameters: '_=x26userid=' + userId,
			asynchronous: !!callback,
			onComplete: callback
		});
		if(!callback) return r.transport.responseText;
	}
,
	ChangeUserPassword:
	function(userId, newPassword, callback)
	{
		var r=new Ajax.Request('/admin/ChangeUserPassword.rails',
		{
			parameters: '_=&userId=' + userId + '&newPassword=' + newPassword,
			asynchronous: !!callback,
			onComplete: callback
		});
		if(!callback) return r.transport.responseText;
	}
}
</script>

As you see it supports synchronous and asynchronous calls. If you specify a callback function it will be asynch, otherwise synchronous. The use of the remote method becomes natural js code:

<input type="button" onclick="javascript:myproxy.DisableUser($('userid'));" />

You may also consult the API documentation for the AjaxHelper .

The LinkToFunction and ButtonToFunction methods allow the generation of Html elements that once clicked invoke a javascript function. It is very simple and has nothing to do with remote invocations.

You may also consult the API documentation for the AjaxHelper .

The LinkToRemote and ButtonToRemote generates html elements that once clicked invokes a remote action (usually a controller's action).

The following overloads are supported:

The BuildFormRemoteTag generates a form element that instead of sending the content in the normal way, it uses Ajax to send the data.

The following overloads are supported:

The observers can be associated with form elements or with the whole form. An ajax invocation is sent when a change is detected.

The following overloads are supported:

You may also consult the API documentation for the AjaxHelper .

The PeriodicallyCallRemote makes remote invocations with a specified frequency.

The AutoComplete enables a google style search where partial searches are emitted as you type.

It is higly advisable to carefully read the script.aculo.us documentation for the AutoCompleter to know about the possible completionOptions.

AjaxHelper offers the following methods for providing AutoCompletion:

FormHelper also offers a combination of a input field with databinding behaviour and Ajax Autocomplete behaviour.

This field is created analogous to InputTextWithAutoCompletion , but instead of an inputName, the target object's property path is specified (i.e. user.Role ).

#set ($ajaxOpt = "%{parameters='{user:\'$user.Id\'}', paramName='\'search\''}")
#set ($inputOpt = "%{class='txt'}")
<p>Enter your favorite programming frameworks:</p>

<form action="$UrlHelper.For("%{action='EnterDataResults'}")" method="post">
	<input type="hidden" name="user" value="$user.Id" />
	<table class="blind">
		<tr>
			<td>IoC-Framework</td>
			<td>$FormHelper.TextFieldAutoComplete("preference.ioc", UrlHelper.For("%{action='LookupIoc'}"), inputOpt, ajaxOpt)</td>
		</tr>
		<tr>
			<td>OR/M-Framework</td>
			<td>$FormHelper.TextFieldAutoComplete("preference.orm", Url.ForHelper("%{action='LookupOrm'}"), inputOpt, ajaxOpt)</td>
		</tr>
		<tr>
			<td></td>
			<td><input type="submit" value="Save Data" /></td>
		</tr>
	</table>	
</form>

public void LookupIoc([ARFetch("user")]User user, string search)
{
	// perform search and put results into PropertyBag
}

<ul>
#foreach ($ioc in $frameworks)
	<li>$ioc.Name</li>
#end
</ul>

Suppose you have a set with 400 items:

public class MyController : SmartDispatcherController
{
	public void List()
	{
		PropertyBag["items"] = ObtainMyLargeCollection();
	}

	private IList ObtainMyLargeCollection()
	{
		...
	}
}

With the PaginationHelper you can return a sliced representation of the collection:

public class MyController : SmartDispatcherController
{
    public void List()
    {
        PropertyBag["items"] = PaginationHelper.CreatePagination( ObtainMyLargeCollection(), 10 );
    }

    private IList ObtainMyLargeCollection()
    {
        ...
    }
}

The help will look for a page on Request.Params to define its starting index. The CreatePagination method returns a IPaginatedPage object which exposes several properties so you can build a nice pagination box:

This a snippet that renders the items and the pagination box:

#foreach($row in $items)
  <tr>
    <td>$row.Name</td>
    <td>$row.Email</td>
  </tr>
#end</table>

<div class="pagination">
<table width="100%" border="0">
  <tr>
  <td>Showing $items.FirstItem - $items.LastItem of $items.TotalItems</td>
  <td align="right">
#if($items.HasFirst) $PaginationHelper.CreatePageLink( 1, "first" ) #end
#if(!$items.HasFirst) first #end
#if($items.HasPrevious) | $PaginationHelper.CreatePageLink( $items.PreviousIndex, "prev" ) #end
#if(!$items.HasPrevious) | prev #end
#if($items.HasNext) | $PaginationHelper.CreatePageLink( $items.NextIndex, "next" ) #end
#if(!$items.HasNext) | next #end
#if($items.HasLast) | $PaginationHelper.CreatePageLink( $items.LastIndex, "last" ) #end
#if(!$items.HasLast) | last #end
  </td>
  </tr>
</table>
</div>

This will result in something like the following

The PaginationHelper has a cached version of its functionality. That allows the data source to be loaded and reused for a limited period of time. The cachekey must be carefully defined with the application semantics in mind. A bad cachekey might allow the data source to be shared by request from different users and with different data source search criterias (when the data source is the result of a search)

Suppose you have a form with many search criterias:

Your view will look something similar to this, and make sure to POST rather than GET:

<form id="search" method="post" action="$siteRoot/Cars/Search.aspx"
	<input id="make" type="text" size="14" name="make" /><br />
	<input id="model" type="text" size="14" name="model" /><br />
	<input id="year" type="text" size="14" name="year" /><br />
	<input type="Submit" class="button" value="Search!" />
</form>

The pagination helper exposes a delegate that you will need to grab your search results. Pass it your method that handles the actual searching. Here is an example controller:

public class CarController : SmartDispatcherController
{
	private String make, model, year;
	
	public IList PerformSearch()
	{
		// Do your actual search
		
		return Car.FindByMakeModelYear(make, model, year);
	}
	
	public void Search(String make, String model, String year)
	{
		// create the pagination
		
		PropertyBag["Cars"] = PaginationHelper.CreateCachedPagination(
			"carssearchkey" + this.make + this.model + this.year, 
			5, new 	DataObtentionDelegate(PerformSearch));
	}
}

Our resulting view, it is important that we expose our criteria to the view so the next/first/last/prev links can be correctly constructed and work properly:

<table cellpadding="4">
	<tr>
		<th>Make</th>
		<th>Model</th>
		<th>Year</th>
	</tr>
#foreach($Car in $Cars)
	<tr>
		<td>$!Car.Make</td>
		<td>$!Car.Model</td>
		<td>$!Car.Year</td>
	</tr>
#end
</table>
<div class="pagination" id="pagination">
<table width="90%" border="0">
	<tr>
		<td>Showing $Cars.FirstItem - $Cars.LastItem of $Cars.TotalItems</td>
		<td align="right">
		#if($Cars.HasFirst) 
			$PaginationHelper.CreatePageLink( 1, "first",null, "%{make=$make, model=$model,year=$year}" ) 
		#else
			first
		#end
		#if($Cars.HasPrevious) 
			| $PaginationHelper.CreatePageLink( $Cars.PreviousIndex, "prev",null, "%{make=$make,model=$model,year=$year}" ) 
		#else
			| prev 
		#end
		#if($Cars.HasNext) 
			| $PaginationHelper.CreatePageLink( $Cars.NextIndex, "next",null, "%{make=$make,model=$model,year=$year}" ) 
		#else
			| next
		#end
		#if($Cars.HasLast) 
			| $PaginationHelper.CreatePageLink( $Cars.LastIndex, "last",null, "%{make=$make,model=$model,year=$year}" ) 
		#else
			| last
		#end
		</td>
	</tr>
</table>
</div> <!-- end pagination -->

And how it looks:

What we are about to discuss only works if you are using ARSmartDispatcherController instead of SmartDispatcherController . The ARSmartDispatcherController offers a CustomBindObject method that is ActiveRecord-aware.

So imagine that you are creating a CRUD page for a Customer object. Creation is really simple, and the DataBindAttribute attribute is enough:

public class CustomerController : ARSmartDispatcherController 
{
    public void Index()
    {
    }

    public void New()
    { 
    }

    public void Create([DataBind("customer")] Customer customer)
    { 
        try
        {
            customer.Create();

            RedirectToAction("index");
        }
        catch(Exception ex)
        {
            Flash["error"] = ex.Message;

            RedirectToAction("new", Request.Form);
        }
    }
}

Now editing is trick. You must load the Customer , and populate the changes with the form data. Enters ARDataBindAttribute :

public class CustomerController : ARSmartDispatcherController 
{
    ...

    public void Edit(int id)
    { 
        PropertyBag.Add("customer", Customer.Find(id));
    }

    public void Update([ARDataBind("customer", AutoLoad=AutoLoadBehavior.Always)] Customer customer)
    { 
        try
        {
            customer.Update();

            RedirectToAction("index");
        }
        catch(Exception ex)
        {
            Flash["error"] = ex.Message;

            RedirectToAction("edit", Request.Form);
        }
    }
}

The ARDataBindAttribute extends the DataBindAttribute so the Exclude and Allow properties are still there.

However, as you can see, we used AutoLoad=AutoLoadBehavior.Always . This tells the binder to collect the primary key value for the customer and load it, then populate the object. So all you have to do next is to invoke Save or Update method.

The ARFetchAttribute is a simpler version of ARDataBinder . It is in charge of loading the instance from the database and nothing more.

public class CustomerController : ARSmartDispatcherController 
{
    ...

    public void SetPassword([ARFetch("customer.id")] Customer customer, String newPassword)
    { 
        try
        {
            customer.Password = newPassword;
            customer.Save();

            RedirectToAction("index");
        }
        catch(Exception ex)
        {
            Flash["error"] = ex.Message;

            RedirectToAction("changepassword", Request.Form);
        }
    }
}

The optional parameter passed to ARFetch tells it which form field has the primary key value. If you don't specify it, it will use the parameter name (for the example above it would be customer )

You can also specify Required=true which will force it to throw an exception if the record is not found:

public class CustomerController : ARSmartDispatcherController 
{
    ...

    public void SetPassword([ARFetch("customer.id", Required=true)] Customer customer, String newPassword)
    { 
        ...
    }
}

And Create=true , which will create a new object if the primary key form field is empty:

public class CustomerController : ARSmartDispatcherController 
{
    ...

    public void CreateOrModifyCustomer([ARFetch("customer.id", Create=true)] Customer customer, String name, ...)
    { 
        customer.Name = name;
        customer.Save();
    }
}

The combination of databinding and ActiveRecord opens the possibility for an error that is most often hit by unexperienced users, especially when using the recommended Session Per Request configuration for ActiveRecord. Consider the code from above:

public void Update([ARDataBind("customer", AutoLoad=AutoLoadBehavior.Always)] Customer customer)
{ 
    try
    {
        customer.Update();

        RedirectToAction("index");
    }
    catch(Exception ex)
    {
        Flash["error"] = ex.Message;

        RedirectToAction("edit", Request.Form);
    }
}	

Now, what happens if there is an exception? The exception is caught as intended and the error message added to the Flash container. But actually, you will get an ASP.NET errorpage nonetheless. The reason for this behaviour is simple once you know how the request is processed in the controller:

So, now that the problem is known, how can it be handled? There are plenty possible solutions for this, depending on the user's needs: