Home

Castle Stronghold

•  
• Home
• Download
• API Doc
• Using
• Forum
• Jira/Issue tracker
• Builds

FormHelper

The FormHelper allow you to output Html Input elements using the conventions necessary to use the DataBinder on the server side. It also query the objects available on the context to show property values correctly, saving you the burden of filling inputs, selects, checkboxes and radios.

General concept

The helper is inspired on two exquisite works: the Ruby on Rails' FormHelper and the Apache Jakarta Taglibs. The idea is to generate html form elements while

• Use the same name convention used by the DataBinder on the controller side
• Collect the value from an instance in the context (if available) and present the html element with the value or selection

When using the FormHelper you specify a target through a string. The target is evaluated and if the object is available on the context and the evaluation result is used to provide the correct output. For a simple text input element, the evaluated value will be the value of the element.

Getting started

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

The goal is to generate proper elements that will be easily binded 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 to exemplify):

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

$FormHelper.TextField("name")

$FormHelper.TextField("address")

</form>

Whenever this view isis rendered, the FormHelper's TextField method will be invoked. The first thing it does is extracting 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 on the context dictionaries for the roots, in the following order:

• PropertyBag
• Flash
• Session
• Request.Params
• HttpContext.Items

If it finds the entry, it will extract the value and use it. If not, that is OK too, but no value will be presented 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>

But if you fill these elements and submits the form the values will be preserved. This happens because, as you saw, the FormHelper also inspect the Request.Params.

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 goes beyond input fields. See below the other documents on FormHelper.

Complex objects

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="Save.rails" method="post">

$FormHelper.TextField("contact.name")

$FormHelper.TextField("contact.address")

$FormHelper.TextField("contact.phone")

</form>

The FormHelper will find the contact entry on the PropertyBag, and then find the properties name and address to extract the values from and render the view accordingly:

<form action="Save.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

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 instance it should extract the value:

<form action="Save.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="Save.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>

API documentation

You may also consult the API documentation for the FormHelper.

Site map

The following is a list of the documents related to FormHelper:

Search WWW Search castleproject.org