Aspbeans documentation, version 1.0
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.
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()
Public Sub New(ByVal name As String, ByVal species As String, ByVal weight As Double)
_name = name
_species = species
_weight = weight
Public Property name() As String
Set(ByVal Value As String)
_name = Value
Public Property species() As String
Set(ByVal Value As String)
_species = Value
Public Property weight() As Double
Set(ByVal Value As Double)
_weight = Value
Public Overrides Function toString() As String
Return _name & ", a " & _weight & "lb " & _species
The toString() method is nice to define, but not necessary for an object to be considered an aspbean.
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)
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" ?>
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.
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:
<field id="alive" source="text">
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 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:
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.
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”.
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.
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.
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 firstname.lastname@example.org. Thank you for using Aspbeans!