The WSS Forms Object Model

Besides being able to just use the WSS Forms Renderer technology from HTML pages where you include special markup, you can also use WSS Forms from ASP pages because WSS Forms provides an object model that you can program against. Using ASP pages offers greater control over the way the forms are validated and rendered. For example, you might want to validate the data in the form on the server, and if an error occurs, you can display a message and point the user to the error. Using just the WSS Forms Renderer does not allow you to do this, but using WSS Forms in ASP pages does. Figure 20-9 depicts the object model for WSS Forms.

Figure 20-9: The WSS Forms object model

The main object in the object model is the Form object. The ProgID that you use to create this object in your ASP pages is WSS.Form . Table 20-11 lists the properties of the WSS Form object.

Table 20-11: Properties of the WSS Form Object

Property	Description
CodePage	The codepage for the form.
DataURL	Returns the URL to the item if it exists in Exchange.
Elements	Returns the Elements collection, which contains all the HTML elements on the page that are identified with a name or id attribute.
Errors	Returns the Errors collection, which contains all the errors that occur when you attempt to set values in the Fields collection.
Fields	Returns the ADO Fields collection for the item.
HasErrors	A Boolean that specifies whether there are any errors on the form. These errors can be application generated, such as when error strings are set on data in the item, or they can be generated by WSS Forms.
IsNew	A Boolean that returns true if the item is a new item.
LCID	Returns the locale identifier for the form.

Table 20-12 lists the methods of the WSS Form object.

Table 20-12: Methods of the WSS Form Object

Method	Description
Render	Renders the form, including any data-bound fields or views. You should call this method after all the work in your ASP is done because any ASP code after this method is ignored. You can use the WSS Form object model to perform any processing of items after your ASP code. This method can take two optional parameters. The first, bCallResponseEnd , is a Boolean that specifies whether to call the ASP Response object's End method. The default value is True . The other optional parameter, bReturnError , specifies whether any error information should be returned.
Update	Updates the Fields collection for the form. You can pass two optional parameters. The first is a string called bstrURL , which can be the URL to the item that you want updated. You will usually pass a blank string. The second parameter is a Boolean called bOverwrite , which specifies whether the existing data can be overwritten.

FormElements Collection and FormElement Object

When you use the Elements collection on the WSS Form object, you get back a FormElements collection. This collection contains all of the HTML elements in your form. You can use this collection to change the attributes of the element or the value of the element or to mark the element as having an error. The collection does not really have any special methods and properties, so we will jump right to the FormElement object. The FormElements collection has the standard Count and Item methods. For the Item method, you can pass either the numeric index or a string for which the object model will try to find a matching HTML element with an id or name attribute that matches that string.

The FormElement object allows you to query or modify HTML elements in your form. Table 20-13 lists the properties of the FormElement object.

Table 20-13: Properties of the FormElement Object

Property	Description
Attributes	Returns the FormAttributes collection.
EndTag	Returns a Boolean that is true if the element has a matching end tag.
ErrorString	A string that can specify any HTML you want to place after the element. You usually use this to display error strings if your validation script finds an error in the form. You'll see this property used in an upcoming example.
InnerText	A string that can specify any HTML you want between the opening and closing tag of the element.
TagMarkup	Returns a string that is the entire opening tag of the element. For example, a hyperlink might return the following: <A href="mylink.asp" style="color:blue">
TagName	Returns the HTML element tag name (such as DIV ).
Value	Returns the value from the Fields collection that is bound to the element.
Visible	A Boolean that controls whether the element is visible when the form is rendered.

FormAttributes Collection

The FormAttributes collection is part of the FormElement object. This is a collection of HTML attributes for the element. For example, an attribute for an <A> HTML element can be id , name , href or style . Using this collection, you can browse, add, or delete attributes on the HTML elements in your form. Table 20-14 lists the properties and methods of this collection.

Table 20-14: Properties and Methods of the FormAttributes Collection

Property	Description
Count	Returns the number of attributes.
Item	Retrieves an attribute by name or index number.
Method	Description
Add	Adds a new attribute. You must pass a string that is the name of the new attribute. You can then pass two optional parameters. The first specifies whether the attribute has a name only. The second specifies the value of the new attribute.
Delete	Deletes an attribute from the collection. You must pass the index of the attribute.

FormAttribute Object

From the FormAttributes collection you can get a FormAttribute object. This object is a single attribute on your HTML element. Table 20-15 lists the properties of this object.

Table 20-15: Properties of the FormAttribute Object

Property	Description
Name	Specifies the name of the attribute.
Value	Specifies the value of the attribute.
NameOnly	A Boolean that returns false if the attribute has a value.

FormErrors Collection

The FormErrors collection contains any errors after the form was submitted to the server. You can check this collection before calling the Update method as well to see if any errors are lingering in the form. Table 20-16 lists the properties of this collection.

Table 20-16: Properties of the FormErrors Collection

Name	Description
Count	Returns the number of Error objects in the collection.
Item	Retrieves a FormError using its index.

FormError Object

The FormError object allows you to programmatically access the properties and values for an error. Table 20-17 lists the properties of this object.

Table 20-17: Properties of the FormError Object

Property	Description
Description	Returns a description of the error.
File	Returns the source file where the error occurred.
Line	Returns the line number where the error occurred.
Name	Returns the name of the error.
Number	Returns the number of the error.
Source	Returns the actual source code that caused the error.
Value	Returns the value of the error.

Putting It All Together

Now that you've seen all the objects, methods, and properties of WSS Forms, let's look at a sample that puts everything together. The following sample uses the object model to hide fields when the item is new and to set fields when the item is posted. If a certain field is not filled in ”in this case, the subject ”when the user attempts to post an item, an error will be displayed in red next to the field, telling the user to fill in the field. This example just shows you how to get started with WSS Forms.

 <HTML> <%          Set oForm = Server.CreateObject("WSS.Form")          If (Request.ServerVariables("REQUEST_METHOD") = "POST") Then         If (oForm.IsNew) Then             If oForm.Elements("urn:schemas:httpmail:subject").Value="" Then                 oForm.Elements( _                     "urn:schemas:httpmail:subject" _                     ).ErrorString = "<DIV style=color:red " _                                   & "id=subjecterror><B> You must enter " _                                   & "a value for the subject!</B></DIV>"             End If             If oForm.HasErrors = True Then                 oForm.Elements("ItemInfo").Visible = False             End If                  oForm.Fields("Status").Value = "NotApproved"             oForm.Update()         End If     End If          If (Request.ServerVariables("REQUEST_METHOD") = "GET") Then         If (oForm.IsNew) Then             oForm.Elements("ItemInfo").Visible = False         End If     End If          oForm.Render() %>      <HEAD>     <title>Sample Page</title> </HEAD> <BODY>     <form class="form"  method="POST" actionspec="%DataURL%"           name="theform1" name="theform1">              <span id="ItemInfo">             Created: <span class="field" name="DAV:creationdate"></span>             <br>             Last Modified:             <span class="field" name="DAV:getlastmodified"></span>             <br>     </span>     <p>     Subject:     <input type="text" class="field" name="urn:schemas:httpmail:subject"            size="20">     <p>     Status:     <select class="field" name="Status" >         <option value="NotApproved" selected>Not Approved         <option value="Approved">Approved         <option value="InProgress">In Progress         <option value="Completed">Completed     </select>     <br>     Description:     <br>     <textarea class=""field"  name="Description" rows="4" cols="30"               rows="1" cols="20" form="theform1">     </textarea>     <p>     <input type="submit" size="20" form="theform1">     <input type="hidden"            name="http://schemas.microsoft.com/exchange/nosave/hintforurl"            value="urn:schemas:httpmail:subject">     <input type="hidden" name="DAV:contentclass" value="SampleItem"> </form>      </BODY> </HTML> 

Remember that if you want to use ASP or ASP .NET as your rendering engine to modify your ExecuteURL in your form registration, do not use /exchweb/bin/exwform.dll ”instead, point to your ASP or ASP .NET file.