Aspbeans documentation, version 1

Aspbeans documentation, version 1.0

Summary:

Aspbeans is a lightweight framework that reduces the coupling and mundane code required to transfer data to and from object and ASP web forms. By either naming the form’s field appropriately or describing them in an xml file, you can reduce your form population/saving to one line of code.

Technical

Aspbeans extends the ASP web form’s panel class. You can use it just as you could a regular panel, except that the bean panel has the capability to save or load from an object.

The Javabean concept is used heavily here. For those unfamiliar with Javabeans, or those who want to know what I define as an aspbean, an aspbean is a class with public properties for each of its modifiable attributes (as opposed to getters and setters in Java), and a default constructor (one that takes no arguments).

An example aspbean (in VB.NET):

Public Class Pet

Private _name As String = ""

Private _species As String = ""

Private _weight As Double = 0

Public Sub New()

End Sub

Public Sub New(ByVal name As String, ByVal species As String, ByVal weight As Double)

_name = name

_species = species

_weight = weight

End Sub

Public Property name() As String

Get

Return _name

End Get

Set(ByVal Value As String)

_name = Value

End Set

End Property

Public Property species() As String

Get

Return _species

End Get

Set(ByVal Value As String)

_species = Value

End Set

End Property

Public Property weight() As Double

Get

Return _weight

End Get

Set(ByVal Value As Double)

_weight = Value

End Set

End Property

Public Overrides Function toString() As String

Return _name & ", a " & _weight & "lb " & _species

End Function

End Class

The toString() method is nice to define, but not necessary for an object to be considered an aspbean.

Object population:

There are two ways to populate an object using Aspbeans and an ASP web form. You can either name all of your fields exactly the same as they are in the object (so, for class Pet, the textbox holding the weight would have to be named “weight”), or you can use an XML file.

To populate an object from a bean panel, use beanPanel.writeTo(object)

XML

If you’re using an XML file, the file must have the same name as your page. If you had “Demo.aspx”, your XML file would need to be named “Demo.bean.xml”.

Here is an example XML file:

<?xml version="1.0" encoding="utf-8" ?>

</field>

<save>fullName</save>

</field>

<load>alive2</load>

<save>alive2</save>

</field>

</page>

An XML mapping overrides the field-name mapping, but both can be used at the same time.

XML mappings provide more flexibility, because you can save to one property and load from a different one. XML mappings are only required if you’re using a DataGrid (covered later), otherwise they’re just a way to provide more functionality.

DropDownLists

Two controls that are treated a little differently are the DropDownList and DataGrid. The DropDownList has 2 values, one is the value selected and the other is the text associated with that value. Sometimes that value comes from a database or some other source that you don’t want to query unnecessarily, so Aspbeans provides a way to write the DropDownList text to a different property. You have to define another field in the XML, and it looks like this:

<save>aliveDesc</save>

</field>

The source=”text” tells Aspbeans to look at the text of the control, instead of the value. If you only use the same-name method of mapping to a bean, only the value is saved to the bean.

DataGrids

DataGrids require an XML file. The XML file needs to describe each column in the DataGrid, regardless of its visibility, from left to right. I have a DataGrid on the demo application, and the XML for it looks like this:

<cell>species</cell>

<cell>weight</cell>

</datagrid>

DataGrids map to properties whose type implements IList. If a person (the containing bean in the Demo application) has three pets, there will be three rows on the DataGrid. Each line on the grid corresponds to a Pet object, which will be saved as an element in the IList. If you don’t want a cell to save, you can just leave the text in between blank, but it still needs to be there so that the column-counting goes correctly.

DataGrid editing is still a little tricky, and isn’t up to par yet. Eventually, there will be a lot more flexibility for them provided in the XML file, but until then it’s kind of hacked together. If you want an editable column that is always editable, you’ll can put a control inside the DataGrid column and give it an ID “value”. The value inside of the control will be written to the property mapped in the XML. For an example of this, see the page Demo.aspx in the demo.

Collection mapping

DataGrids feed to collections (ILists), and so do checkbox lists. Any property that is associated with a collection has to implement IList. There is no support for IDictionary right now, but you could have one property that is an IList and assumes the responsibility of adding things correctly to the IDictionary.

You must specify the type of the collection using .NET attributes for any collection property. The aspbeans.Type(String) property does this. So, if you had your collection of Pets, it would be:

<aspbeans.Type("aspbeansDemo.Pet")> Public Property pets() As ArrayList

You must use the fully qualified type! Do not use “String”, instead, use “System.String”.

Form population:

If you have your pages set up to save correctly to the appropriate beans, then you don’t have to do much to make the load from them. There is a different method call, but that’s about it. To populate a bean panel from an object, use beanPanel.populateFrom(object).

One feature of Aspbeans is the ability to not display null values, so if you have an integer textbox and you don’t want zero to show, you can specify that using attributes. Eventually this will be available in the XML, too. Just use the aspbeans.Null(String) attribute, and put whatever string the property should never show. For example, if I didn’t want a person who is 21 years old to have his or her age show on the textbox, I could put:

<aspbeans.Null("21")> Public Property age() As Integer

Now if the person’s age is 21, it won’t be shown.

Validation

There are currently validation capabilities in Aspbeans, but they are incomplete. There is no rollback-mechanism, so if half of the page loads and then finds an error, you’re stuck with a half populated object. I’m not going to write documentation on the validation mechanisms until they’re complete, but if you want to use them anyways, refer to the demo application for an example.

Contact

If you would like to help with the Aspbeans project, have an idea or a bug, or just need help, feel free to email me at theath@users.sourceforge.net. Thank you for using Aspbeans!

go back to home page