Table of Contents
List of Examples
When Active Server Pages was first released it ushered in a new era of web development, allowing developers to take HTML,mix it with a stripped down version of visual basic/javascript/perl and create dynamic content, and web applications. The decision to base things on visual basic allowed them to take advantage of the COM infrastructure that they had been refining for the last year or two and to create a powerful platform on which to build web applications.
Versioning and remote deployment difficulties within COM, the short sightedness that the Windows server products had suffered during their infancy in the server market led to some real problems when trying to deploy/maintain and upgrade web applications. Other tools could be bought off the shelf and used to manage these servers but these products also made public servers even more susceptible to attack by crackers.
Many developers found the best way to deal with all of these problems was simply to wholly embrace the scripting portion of ASP for their development needs. COM components carrying the core business logic were left behind as the difficulties of turnovers, maintenance, etc began to manifest themselves.
This worked well for most applications, as is evident in the number of ASP-based web-applications that can be found online today. However, one of the core difficulties with ASP/VBScript is that it is a typeless language. As more and more database applications were put onto intranets, the validation of the data became more important, there were lots of rules for validating any piece of data that the user may have entered, and the rules could be different for different users, or different times of day. This led to nasty nests of if-then/select statements that quickly became unmanageable.
Something else was needed.
In the summer of 1999 we started to work on a tool that would allow us to solve this problem, allowing for quick and fastvalidation, quick coding, and allow the reuse of validation rules. Over the course of the next 2 years we refined these concepts into what is now known as ASPForms.
Table of Contents
This user guide is written for active web developers, and assumes a working knowledge about how ASP applications work. Before getting started you should understand the basics of these core technologies :
The canonical source for this is RFC 2616 - Hypertext Transfer Protocol (HTTP/1.1)
Table of Contents
We're going to take the ASPForms component and construct a sample application that should be able to get you through the basicsof using this component. Once we're done you will have a basic understanding of elements, rulesets, rules, errors, and adapters. We are not going to go through approaches for determining if you have a page post or how to structure your ASP sites/pages, it is assumed that you are familiar with the various strategies involved in asp development.
The ASPForm class is the base class and there must be at least one instance of this created in order to utilize ASPForms.Below is an example of VBScript code that will create an instance of an ASPForm and assign the handle to a variable
The ASPForm class is not very useful by itself, and an example showing the utility of the component at this point would be rather pointless so we are going to add a few elements and then return to the details of the ASPForm class. We'll create a few elements that we can use for the next few examples.
Example 2.2. Adding Elements To An ASPForm Object
'create an ASPForms object
set hASPForm = Server.CreateObject("ASPForms.ASPFormV1")
'create a name element in the form
hASPForm.Elements.CreateElement "name", true
'create an address1 element in the form
hASPForm.Elements.CreateElement "address1", true
'create an address2 element in the form
hASPForm.Elements.CreateElement "address2", false
'create a city element in the form
hASPForm.Elements.CreateElement "city", true
'create a state element in the form
hASPForm.Elements.CreateElement "state", true
'create a zipcode element in the form
hASPForm.Elements.CreateElement "zipcode", true
'store the form's state and configuration into the session
hASPForm.StoreStateInSession "addressInfo"
Below is a page that creates an HTML form. This will be what is presented to the user for them to fill in, once they click submit the information they entered will be picked up by our ASPFormsV1 object.
Example 2.3. An ASP page with a basic HTML form
<html> <head> <title>A Sample Form</title> </head> <body> <form id="form1" action="sample.asp" method="post"> <input type="hidden" name="pagepost" size="25" value="1"> <input type="text" name="name" size="25"> <br> <input type="text" name="address1" size="25"> <br> <input type="text" name="address2" size="25"> <br> <input type="text" name="city" size="25"> <br> <input type="text" name="state" size="25"> <br> <input type="text" name="zipcode" size="25"> <br> <input name="cmd" type="submit" value="Save"> <input name="cmd" type="submit" value="Cancel"> </form> </body> </html>
We are going to load the information from the previous form into our object, to do so we need to create an instance of our object load the element configuration from the session, then retrieve the data returned from the browser with the LoadFromRequest method.
Example 2.4. Retrieving Data From The Request Object
'create an ASPForms object
set hASPForm = Server.CreateObject("ASPForms.ASPFormV1")
'load the previous state of the table from the session
hASPForm.LoadFromSession "addressInfo"
'create a name element in the form
hASPForm.LoadFromRequest
The LoadFromRequest method iterates through the list of elements that are defined by the form then attempts to find an named item in the request that matches the element name. if a match is found then the corresponding value is placed into the element value otherwise it is left blank.
It is often helpful to be able to view the current state of your application without having to write a lot of messy code. for that reason we have created a few helper functions that allow you to easily see what is going on within any ASPFormV1 object.
Example 2.5. Dumping the configuration and current state
'continuing from the previous example.. 'dump the current configuration of the aspform hASPForm.dumpConfig 'dump the current state of the aspform hASPForm.dumpState
The LoadFromRequest method iterates through the list of elements that are defined by the form then attempts to find an named item in the request that matches the element name. if a match is found then the corresponding value is placed into the element value otherwise it is left blank.
Loading post data, or grabbing information from a session isn't terribly useful by itself, in fact it would be easier to write code by hand to load this information every time. All data that is posted via a web interface should be validated for length, type, format, among others, with the ability to turn off javascript in the newer browsing clients, validation at the client is not enough, it must be done on the server as well.
ASPForms has a sophisticated mechanism for managing the validation of data. For now, we will cover the basic set of the components features, and in a later chapter we will cover some more advanced features of the system. Below we will construct a ruleset for the form, adding rules to validate all of the elements in our form.
Example 2.6. Configuring a validation ruleset
'create an ASPForms object
set hASPForm = Server.CreateObject("ASPForms.ASPFormV1")
'*** add some elements to the form ***
'create a name element in the form
hASPForm.Elements.CreateElement "name", true
'create an address1 element in the form
hASPForm.Elements.CreateElement "address1", true
'create an address2 element in the form
hASPForm.Elements.CreateElement "address2", false
'create a city element in the form
hASPForm.Elements.CreateElement "city", true
'create a state element in the form
hASPForm.Elements.CreateElement "state", true
'create a zipcode element in the form
hASPForm.Elements.CreateElement "zipcode", true
'store the form's state and configuration into the session
hASPForm.StoreStateInSession "addressInfo"
'*** create a ruleset and some rules for validation ***
'create a new ruleset for the form
hASPForm.Rulesets.CreateRuleset("master")
'add a maximum length rule for the name element
hASPForm.Rulesets("master").CreateRule "name_maxlength", "name", ASPFORMS_MAXLength, "The Name is Too Long", 15
'add a rule to only allow the characters A-Z, a-z, 0-9 and spaces in address1
hASPForms.Rulesets("master").CreateRule "address2_allowablechars", "address1", ASPFORMS_RegularExpression, "Only A-Z, a-z, and 0-9", "^[A-Za-z0-9 ]+"
Looking at the CreateRule Method used above you will notice that there are several arguments passed in, the function breaks down like this :
Example 2.7. The CreateRule Method
'the create rule method ASPFormV1.Rulesets([rulesetname]).CreateRule [rulename], [elementname], [ruletype], [error_string], [param1] [rulesetname] - name of the ruleset that this rule should apply to [rulename] - name for this rule, ever rule in a ruleset must have a unique name [elementname] - name of the element that this rule applies to [ruletype] - there are several ruletypes that are available within aspforms we will cover these in a bit [error_string] - the string that should appear as the description of an error object if the rule conditions are not met [param1] - a parameter that has a different meaning for different ruletypes ( see api documentation for details )
We've created elements, created a ruleset with some rules, and have captured a request from an html form. Our next step is to take a look at a few ways that we can perform validation on the elements, and also see how errors and validity are indicated within the component.
Many times when validating information from a form you simply want to determine whether all of the information is valid or not, this is easily accomplished with the Validate method of the ASPFormV1 class. In our example, we simply would call validate, if you have multiple rulesets configured ( something that won't be talking about in this example ), then you can either specify a ruleset or specify nothing and have all rulesets validate against the data. The example below shows how we would validate our example, note that validate returns whether the data is valid, this information is also stored in the IsValid property of the class.
There are times where you might want to validate a single element instead of your entire element set. To facilitate this two different methods were created, one allows you to specify the element name to validate from the ASPFormV1's validate method, the other is using a validate method that we created for the element class, this method has an optional argument to allow you to specify a ruleset name ( multiple rulesets are not being utilized in this example, so we will just leave it blank ). Below is an example of how we might validate the name element.
As seen above the IsValid property is available in both the ASPForm class and the Element class. IsValid returns false until it is validated, that way you don't have to worry about forgetting to validate your elements and the thing returning true, that would be bad.
The IsDirty flag is another property that should be mentioned at this time, the IsDirty flag simply indicates whether the value of an element has changed since the last the element was validated, it works like you would expect, simply returning a boolean value.
When the validate method is called on ASPForm class it resets the errors collection before it begins to validate the elements. The errors will remain in the error collection until validate is called again, this allows the error collection to be referenced by the programmer, for things such as notifying the user which elements are invalid.
When an error is identified, details are pulled out and placed into the error object before it is added to the errors collection. The details of the error describe all essential information for discerning how/why an error occurred. They are as follows :
A description of the error that is contained in the rule, the ruleset name of the rule
The name of the element that is the source of the error
The name of the rule that generated the error
The name of the ruleset that contains the rule that generated the error
The Errors class is a standard custom collection, so it is relatively easy to iterate through the errors and see what's going on, the code below shows an example of this.
Example 2.10. Iterating through the errors collection
For i = 1 To hASPForm.Errors.Count
response.write "Element : " & hASPForm.Errors(i).Element & "<br>"
response.write "Description : " & hASPForm.Errors(i).Description & "<br>"
response.write "Rule : " & hASPForm.Errors(i).Rule & "<br>"
response.write "<hr>"
Next
We've included a helper method to simply dump all of the errors that exist to the object context. Below is an example usage :
An adapter is a tool used for mapping ASPForm Elements to a datasource. At this time there is only one adapter in the ASPForms component, however the design allows for seamless implementation of new types of adapters as they become available.
Example 2.12. Using CreateAdapter
'create a new ADO adapter named 'sample'
Set adaptADO = hASPForm.CreateAdapter("sample", ASPFORMS_ADO)
'set the tablename where the data
adaptADO.TableName = "sqlTableName"
NOTE: while it passes back a handle to the adapter, the adapter still exists within the adapters collection
The adapter contains a collection of adapterMappings that define the details of how an element maps to a the datasource. We use the CreateMapping method of an adapter to create mappings for that adapter, an example is below :
Example 2.13. Creating An AdapterMapping
'add mappings to the adapter
hASPForms.Adapters("sample").CreateMapping "mapName", "name", "name", ASPFORMS_String
The details of the CreateMapping method are shown below
Example 2.14. The CreateMapping method
'the create rule method
ASPFormV1.Adapters("sample").CreateMapping [mappingName], [appliesTo], [fieldName], [field_type]
[mappingName] - name of the adapterMapping being created
[appliesTo] - name of the element that this mapping refers to
[fieldName] - name of the field in the database that the element should be mapped to
[field_type] - the datatype of the field in the database
Once you have created an adapter and some adaptermappings for the adapter, you can use the adapter to interact with your datasource. The ADO Adapter currently generates SELECT, INSERT, and UPDATE SQL statements.
Example 2.15. Using The ADO Adapter
'get a adapter from our form object
set hAdapter = hASPForm.Adapters("sample")
'get an insert statement
sSQL = hAdapter.getInsertSQL
'get an update statement
sSQL = hAdapter.getUpdateSQL
'get a select statement
sSQL = hAdapter.getSelectSQL
NOTE : this does not generate any criteria for you application, you simply concatenate this to the returned string
We've now been over the basic objects, and features of the ASPForms component, this should be enough for many users of this component. Please refer to the api documentation for more detailed information about the product, and feel free to contact us at support 'at' myndkryme dot com if you have any questions.
Table of Contents
Table of Contents
Table of Contents
Table of Contents