Session and Event Data Objects

There is the built-in user authentication form handler and there can be search forms that only do lookups. Mostly however, forms gather and store data submitted by users. To effect this, the form handler first populates a data object (hdbObject) with the submitted values. Then the data object is commited, usually to a repository but in some cases a user file. Each step of this process involves an executive command. There is a command to create the data object, a command to extract each value from the form to set the data object members, and finally a command to INSERT or UPDATE the data object.

The hdbObject can be vested with a user session in which case it will persist for the session duration unless explicitly deleted beforehand. Or it can be vested with the HTTP event in which case it will last only for the duration of the event - essentially the runtime of the form handler. Not surprisingly, the former are termed user session objects while the latter are termed event objects.

Event objects are not the general case and can only be used in input-only forms where email or SMS verification is not required. For example, a 'Contact-Us' form that allows anyone to submit a comment or enquiry. Such forms can be protected by a Google recaptcha and if a user session does exist, U-class percent entities can be used to pre-populate many of the contact detail fields. The submission however, will draw only from the event.

Session objects are the norm and are necessary in forms that edit existing data objects. Session objects are also prefered where email/SMS verification is used to input only forms. In such verifications, there are two form submissions, the first giving the data and the second the code. The data that is available via E-class percent entities in the first HTTP event must be stored as it is not available in the second HTTP event - unless it is embedded as hidden values in the code confirmation form, which is not considered best practice. If the verification is successful, the data will end up in a repository. Depending on policy, the data can be placed in a repository even without verification. Either way a session object is the best place to store the data in the meantime.

Data Object Initialization

An event object is created by an EXEC_OBJ_TEMP command (an <xobjTemp> tag). The object is populated by a series of one or more EXEC_OBJ_SETMBR commands (<xobjSetMbr> tags), and is commited by an EXEC_OBJ_COMMIT command (an <xobjCommit> tag). All these commands must lay within the form handler <procdata> section. Once execution is complete, the event object is automatically deleted regardless of outcome.

By contrast, a session object is created by an EXEC_OBJ_START command (an <xobjStart> tag), which can be in the <procdata> block of either a form handler or a page. Session objects are operated on by the same EXEC_OBJ_SETMBR and EXEC_OBJ_COMMIT commands. However as objects persist for the user session duration unless explicity deleted, they can be referred to by commands spanning multiple form handlers. It is by this means that creation and editing of large data objects can be split across multiple forms.

Data Operation Commands

EXEC_OBJ_TEMP <xobjTemp> Create a HTTP event duration object (non cookie forms only). Note that <xobjTemp> has attributes to specify an object reference key and set the pre-defined data class. The command can only be used in form-handlers and can only be followed by one or more EXEC_OBJ_SETMBR commands and then an EXEC_OBJ_COMMIT command (<xobjCommit>).
EXEC_OBJ_START <xobjStart> Create a session object (if it does not already exist) and ensure it is attached to the user session. This command can be used in both form handler and page <procdata> blocks. As with <xobjTemp>, this must specify an object reference key and a pre-defined data class.
EXEC_OBJ_FETCH <xobjFetch> Fetch into the named session object, a data object from a repository. The <xobjFetch> attributes must sname the object and repository, which must have been previously declared. The command cannot appear in a form-handler, only a page.
EXEC_OBJ_IMPORT <xobjImport> Import data into the named user session object from a JSON file. The command must supply the object key and specify the full pathname of the data file. Like the EXEC_OBJ_FETCH command, it also cannot appear in a form-handler, only a page.
EXEC_OBJ_EXPORT <xobjExport> Export the named user session object to a JSON file. The command must supply the object reference key and the full pathname of the data file and may only appear in form handlers.
EXEC_OBJ_SETMBR <xobjSetMbr> Set a member value within the named session object. This command must supply the object reference key, the applicable class (the object host class or a sub-class of it), the member name and define the source of the value.
EXEC_OBJ_COMMIT<xobjCommit>Commit the named user session object to a repository. This must supply the object reference key and name the repository.
EXEC_OBJ_CLOSE<xobjClose>Closes the named user session object. This only needs to supply the object reference key.