Saving Changes to Data
The most typical scenarios for saving changes to data is to save a record or set of records that have presumably been altered, or deleting one or more records. In general, saving changes could be the initial save of a new record, the saving of changes to an existing record, or the saving of similar changes to a set of records. In all of these cases, the save or delete action is usually initiated by a user pressing a task button.
The changed data is sent to the server to be saved using HTML forms with the POST method (as opposed to the GET method). Typically, for each server-side page used to process such changes to data, a unique HTML form is defined that specifies the arguments to be posted with the form. The following lines of HTML code show the definition of such a form:
<FORM ID='memberchange' METHOD='POST'>
<INPUT TYPE='hidden' ...>
...
<INPUT TYPE='hidden' ...>
</FORM>
The ACTION attribute is usually not specified for forms used for tasks within the Commerce Server Business Desk Framework. Rather, the association of particular forms and the pages designed to process them is accomplished through the module configuration files. For more information about how forms are associated with the pages designed to process them, see the postto topic in the Module Configuration Files section.
Normally, various edit type HTCs will be enclosed in the form and each will automatically create an INPUT element using the same name as the XML node with which the HTC is associated.
Other arguments for the form can be defined as INPUT elements with their type attributes set to "hidden". Other important attributes that need to be set are:
The id attribute, which allows access to the element through the Document Object Model (DOM).
The name attribute, which supplies a name to associate with the item of data when posting the form.
The value attribute, assuming that there is a default.
The id attribute and the name attribute can be assigned the same value.
The following line of HTML code illustrates a typical INPUT element within such a form, including a default value provided by an ASP variable:
<INPUT TYPE='hidden' ID='expdate'
NAME='expdate' VALUE='<%= DefaultExpDate%>'>
Sometime before the form is submitted, the module code may assign a (new) value to the INPUT element using the DOM. The element is located using its id attribute and the (new) value is assigned to its value attribute. Once such value changes have been made for all appropriate input elements associated with the form, the form can be submitted and the values become available to the server page processing the changes through the ASP Request object.
A hidden value in a form is often set as a result of an event in the ListSheet HTML Component (HTC). For example, when the OnRowSelect event fires, the key ID for the selection can be placed in a hidden input field so that the selection is sent to an edit page when the form is posted by the task.
Occasionally, you may need to perform some special client-side processing after the task button is clicked, but before the form is posted. Most often, this involves requesting further information from the user, such as asking what type of new record to add, or confirming a modification or delete operation. Sometimes such processing can be performed automatically, without further user interaction. In any event, different processing paths are possible, including different data being submitted with the form, different forms being submitted, or the same form being submitted to a different page for processing.
An ONTASK attribute is defined for the FORM element to support this requirement. If the ONTASK attribute is defined for a FORM element being processed by the Business Desk Framework, the Framework attempts to execute the value provided for that attribute. Most often, the value is a routine name, allowing that routine to perform the required processing.
The following line of HTML code shows the same FORM element as above, though this time it has an ONTASK attribute defined:
<FORM ID='memberchange' METHOD='POST' ONTASK='OnMemberChange'>
When an ONTASK attribute is defined, the executed routine is responsible for submitting the form once the special processing is accomplished. The form can be submitted using the submit method of the form.
The final step in changes to data being persisted to a database occurs within ASP code on the server. A form is posted to an ASP page on the server, and it generally includes various fields of data that can be accessed using the ASP Request object. Using this object, the server-side script retrieves the data posted with the form and places it into an Active Data Objects (ADO) Recordset object to be persisted.
The information in the form will include any fields that were in an EditSheet contained by the form. This includes all EditFields and fields in the EditSheets, which will be sent along with the form.
The DynamicTable and ListSheet HTCs, however, return XMLlists instead of fields. These XMLlists, retrieved through the OnChange event object property XMLlist, needs to be assigned to a hidden form field (see the shipping page for an example).