Stonebroom.SaveForm Documentation

Stonebroom.SaveForm Documentation

The SaveForm component makes it extremely simple to persist values in the <FORM> section of a Web page, using just a few lines of ASP code. The component saves all the values into the user's Session, and can quickly and easily retrieve them and put them back into the HTML controls when they reload that page. It can also save the values as a text file on the server's disk, in a database anywhere on the network, or send them as an email message. To do all this, the SaveForm component provides three methods:

PersistRequest which saves all the values from the form
RetrieveRequest which retrieves the values from a text file or database
GetSavedValue which is used to insert the saved values into HTML controls

This page also describes how the values are stored and how the email messages are created.

The SaveForm component is inserted into the page, and the methods used, in the same way as the standard components supplied with Active Server pages. The following code demonstrates the various uses of the PersistRequest method using VBScript:

<%
Set objSF = Server.CreateObject("Stonebroom.SaveForm")

'Persist the values in the Session
intResult = objSF.PersistRequest()

'Persist the values in the Session and
'to a text file on the servers disk
intResult = objSF.PersistRequest(True)

'Persist the values in the Session and
'to a database defined by a connection string
strConnect = "SERVER=yourserver;DSN=yourdsn"
intResult = objSF.PersistRequest(True, strConnect)

'Persist the values in the Session and
'send as an email message via SMTP Server
strAddressTo = "recipient@somewhere.com"
strAddressFrom = "me@mycompany.com"
intResult = objSF.PersistRequest(True, , strAddressTo, strAddressFrom)

'Persist the values in the Session and
'display details debugging information
intResult = objSF.PersistRequest(, , , , True)

%>

Alternatively, in JScript:

<%
objSF = Server.CreateObject('Stonebroom.SaveForm');

// Persist the values in the Session
var intResult = objSF.PersistRequest();

// Persist the values in the Session and
// to a text file on the servers disk
intResult = objSF.PersistRequest(true);

// Persist the values in the Session and
// to a database defined by a connection string
strConnect = 'SERVER=yourserver;DSN=yourdsn';
var intResult = objSF.PersistRequest(true, strConnect);

// Persist the values in the Session and
// send as an email message via SMTP Server
strAddressTo = 'recipient@somewhere.com';
strAddressFrom = 'me@mycompany.com';
var intResult = objSF.PersistRequest(true, , strAddressTo, strAddressFrom);

// Persist the values in the Session and
// display details debugging information
var intResult = objSF.PersistRequest(, , , , true);

%>

Important Note: When using the PersistRequest and RetrieveRequest methods, the component MUST be placed before any HTML code in your pages, i.e. before the opening <HTML> tag. This is because it generates cookies that must be sent to the browser or client within the HTML headers of the page. Also note that evaluation versions of the component generate a return message in the page, and will themselves create the opening <HTML> and <BODY> tags. You should omit these from your pages when using the evaluation version.

If you are using Internet Information Server version 4 with the Run in separate memory space (isolated process) option on the Virtual Directory page of the Properties dialog set, where you have pages that use the SaveForm component, you may get an error when attempting to retrieve the values array from the session. In this case, remove the Virtual Application and try again.

The PersistRequest Method

This method saves all the values in the ASP Request.Form collection into the user's Session object, and relates the values to the referring page (the page that contained the form) using a re-coded version of that page's URL. If there is no referring page, it uses the URL of the current page instead. This allows an ASP page to contain both the form and the form-handling code, and post the form contents to itself. This method can also save the values as a text file, in a database, or send them as an email message.

The syntax of the PersistRequest method is:

NumberOfValues = PersistRequest([StorePermanent], [ConnectionString], [EmailToAddress], [EmailFromAddress], [DebugMode], [CustomUserID])

Parameter	Description
StorePermanent	Optional. Boolean. If True, the values from the request will also be persisted to a text file, a database table, or sent as an email message depending on the combination of parameters. See the examples at the top of this page for more details. See the end of this page for information on the structure of the database, the location of the text files, and the use of email messages. The default is False, which just persists the values in the user's Session object.
ConnectionString	Optional. String. The connection details for the data source from which the data will be extracted. This can be the name of an existing DSN available on the server, or it can include specific details of the connection. For example: DRIVER={SQLServer};SERVER=sunspot;DATABASE=pubs;UID=username;PW=secret
EmailToAddress	Optional. String. A valid email address to be used as the recipient or 'To' field of the email message containing the values from the request. A value for the EmailFromAddress parameter must also be provided if a value for this parameter is specified.
EmailFromAddress	Optional. String. A valid email address to be used as the 'From' and 'Reply To' fields of the email message. Must be provided if a value for the EmailToAddress parameter is specified.
DebugMode	Optional. Boolean. If True, the method will write information into the page about the values stored, the location, or an extended error message. The default is False.
CustomUserID	Optional. String. If you wish to store values against your own custom user identifiers, and be able to extract them later for each specific user based on that identifier, specify the identifier for this parameter. It is stored in the table with that entry, and can be used in the RetrieveRequest method to retrieve those specific values. Added in version 1.2x.

The RetrieveRequest Method

The values persisted into the user's Session object are lost when the user closes the browser, or doesn't load another page from the site within 20 minutes. To persist the values between sessions, they must be written to a text file or a database using the PersistRequest method (see above). The RetrieveRequest method is then used to retrieve the values for a page from the text file or database and put them back into the user's Session ready to be used in the GetSavedValue method. The RetrieveRequest method uses the URL of the referring page (the page that opened this one) to locate the values. If there is no referring page, it uses the URL of the current page instead. This allows an ASP page to contain both the form and the value-retrieval code if required.

The syntax of the RetrieveRequest method is:

NumberOfValues = RetrieveRequest([ConnectionString], [UserIDString], [PageURL], [DebugMode], [UseReferrerURL], [CustomUserID])

Parameter	Description
ConnectionString	Optional. String. The connection details for the data source from which the data will be extracted. This can be the name of an existing DSN available on the server, or it can include specific details of the connection. For example: DRIVER={SQLServer};SERVER=sunspot;DATABASE=pubs;UID=username;PW=secret
UserIDString	Optional. String. Each user is allocated an ID when their values are persisted permanently, and this is stored in a cookie on their browser for up to six months. When they return, the component automatically uses this ID to locate the stored values. If the cookie has been deleted or has expired, you can prompt them for their ID and use it directly in this parameter. You can also use this parameter if you want to extract values for any particular user on demand. See the stored values section for more details.
PageURL	Optional. String. The component stores values under a key that is the page URL re-coded to remove non-legal characters. When users return to this page again, the component uses the page URL to automatically locate the stored values. You can use this parameter if you want to directly extract values for any particular page on demand. See the stored values section for more details.
DebugMode	Optional. Boolean. If True, the method will write information into the page about the values stored, the location, or an extended error message. The default is False.
UseRefererURL	Optional. Boolean. The default for this parameter if omitted is True, meaning that the method will use the 'coded' URL of the referring page as the lookup key for the set of values to retrieve. If set to False, the method will use the 'coded' URL of the current page instead. If you are retrieving values for use in this page from the user's session or a permanent store as the page loads, set this parameter to False. If you are opening another ASP page in response to a button or hyperlink, and retrieving the values there, set this to True or omit it altogether. Added in version 1.2x
CustomUserID	Optional. String. If you store a set of user values by specifying a custom user identifier in the PersistRequest method, you can extract this set of values by specifying the custom identifier for this parameter. It can be used with or without a value for the pageURL parameter. Added in version 1.2x.

The GetSavedValue Method

This is used to retrieve individual control values from the set of values stored in the user's Session object. At the start of a new session you can use the RetrieveRequest method first to retrieve the set of values for this page from a text file or database, and insert them into the current Session object.

The syntax of the GetSavedValue method is:

ControlValue = GetSavedValue(ControlName, [MatchValue], [ReturnOnMatch], [DebugMode])

Parameter	Description
ControlName	Required. String. The name of the HTML control that the value is required for, or the name of the control that originally held the value (you can insert the stored value of one control into a different one if required). Usually, this will be the value of the NAME attribute in the HTML. If the control is part of a collection (or an array) of controls with the same name, you must include the index number in parentheses unless they are RADIO or 'option' buttons. See the controls section for more details.
MatchValue	Optional. String. For 'Boolean' or List Box controls, the value required to set them is an attribute such as CHECKED or SELECTED, rather than a normal text string value. If a value is provided for this parameter, it is compared to the saved value of the control. If they match, the method returns the special value required for this attribute (instead of the actual value text string). If they don't match, the method returns an empty string. The attribute value returned by default is "CHECKED" unless a different string is provided in the ReturnOnMatch parameter.
ReturnOnMatch	Optional. String. Used in conjunction with the MatchValue parameter, the string provided for this parameter is returned when the stored value of the control is the same as the MatchValue. For a List Box control, you should use "SELECTED" for this parameter.
DebugMode	Optional. Boolean. If True, the string return value of the method will include full details of any error that occurs rather than an empty string. The default is False.

How and Where Values are Stored and Used

When a page containing a FORM section POSTs values to an ASP page containing the SaveForm component, the PersistRequest method always stores all the values in the Request.Form collection (i.e. the values of all the named controls on the form) in the user's Session object. The original FORM page can then use the GetSavedValue method for each control in turn to automatically retrieve the last value entered into that control.

Using GetSavedValue with HTML Controls.

To retrieve the values for individual controls, you use the GetSavedValue method in different ways. For text-based controls except list boxes, for example the INPUT TYPE="TEXT" or the TEXTAREA controls:

<INPUT TYPE="TEXT" NAME="mytext" VALUE="<% = GetSavedValue("mytext") %>>
<TEXTAREA NAME="myarea"><% = GetSavedValue("myarea") %></TEXTAREA>

Where there are several such controls with the same NAME, you specify the index of the control as well:

<INPUT TYPE="TEXT" NAME="mytext" VALUE="<% = GetSavedValue("mytext(2)") %>>

For 'Boolean' check box controls, for example the INPUT TYPE="CHECKBOX" control, you can compare the MatchValue to "on":

<INPUT TYPE="CHECKBOX" NAME="mycheck" <% = objSaveForm.GetSavedValue("mycheck", "on") %>>

For Option Group controls, for example the INPUT TYPE="RADIO" control, you compare the saved value to the VALUE of the control, as the group sends the value of the selected one to the server:

<INPUT TYPE="RADIO" NAME="Gender" VALUE="Male"
  <% = objSaveForm.GetSavedValue("Gender", "Male") %>> Male
<INPUT TYPE="RADIO" NAME="Gender" VALUE="Female"
  <% = objSaveForm.GetSavedValue("Gender", "Female") %>> Female

For List Box and Drop-down List controls, for example the SELECT control, you use the MatchValue and ReturnOnMatch parameters to get the SELECTED attribute into the correct <OPTION> element:

<SELECT NAME="mylist">
 <OPTION>
 <OPTION <% = objSaveForm.GetSavedValue("mylist", "abc", "SELECTED") %>>abc
 <OPTION <% = objSaveForm.GetSavedValue("mylist", "def", "SELECTED") %>>def
 <OPTION <% = objSaveForm.GetSavedValue("mylist", "ghi", "SELECTED") %>>ghi
</SELECT>

Persisting Values to a Text File.

SaveForm persists values as text files within a directory named STNBSaveForm which is created in the WWWRoot (or 'root') folder of your default Web site. You can create this folder manually if required after installing SaveForm. You must give this folder Write or Full Control permissions for the account that will access it through the Web server, probably IUSR_machinename or IWAM_machinename depending on whether you created a Virtual Application to hold the ASP pages that use the component.

Within this folder the component creates a subfolder that has the user ID (a 17 character numeric string) as its name. You can use these folder names to identify user IDs for use with the optional parameter of the RetrieveRequest method if required. Within the user's folder the component creates a subfolder for each page that they access (if it persists values to a text file). These subfolders are named with the 'coded' URL of the page.

Persisting Values to a Database.

When values are persisted to a database, they are stored as a string of name/value pairs separated by carriage returns under a key that is made up of the user ID and the 'coded' page URL. The database name is provided in the connection string or System DSN (depending on how you specify the connection string) and can be any database you wish. However, the table must be named PersistedValues, and have the SQL Server or equivalent format:

Field Name	DataType	Field Size
kUserID	numeric	18,0
kPageID	varchar	255
sCustomID	varchar	255
sValues	text	16

NOTE: The sCustomID field was added in version 1.2x of SaveForm. In this version, you must also remove the primary key status from all fields. You can index the fields using a 'repeated values' (non-unique) index as required, depending on whether you persist values between sessions using the standard kUserID or the custom user ID sCustomID (or both). It is usually worth indexing the kPageID field with a Repeated Values (non-unique) index.

Sending Values in an Email Message.

SaveForm can assemble the values submitted from a FORM as a text message and send it to as a suitable mail server a standard email message. This facility requires the Microsoft^® SMTP Service to be running on the server. The SMTP Service is an optional component of Internet Information Server version 4.0 and above, and is available in the NT4 Option Pack and as part of Windows NT5/2000. As well as installing the SMTP Service, you should be sure to install the CDONTS (Collaborative Data Objects) components if they are listed as a separate option. The SMTP Service can be configured to send mail directly to your ISP over a dial-up connection if you do not have your own mail server.

Note: If your server is also running Microsoft^® Exchange Server or another mail server service, you will not be able to run the IIS SMTP Service as well on the same server.