Desktop Forms

Desktop form support is configured the same way as desktop delivery. The same HTTP server and clients are used. Unlike desktop delivery, which will store documents for when the user logs in, it is critical that the user be connected when the form is to be presented.

The form is launched with the dtform() code block function. The user specified is notified that a form is ready to be presented, and he or she can accept or cancel the form. If the user neither accepts nor cancels the request within a specified amount of time, the request times out.

Data is sent to the form, and returned from the form, using a URL-encoded data string. There are several functions provided to manage this string.

The form itself is an HTML document, stored anywhere in the browser interface directories, such as under web/en-us/forms. The form must an action= attribute of the UnForm CGI script name, and have the following fields defined:

In addition, any standard HTML form widgets can be used, including text boxes, text areas, radio buttons, checkboxes, and selection lists. A submit button must be provided, and an optional Cancel button can be used, which must set the value of the "cancel" field to 1 when submitting the form.

An example form, "emailform.html", is found in the web/en-us/forms directory, and a sample rule file samples/dtform.rul is provided using this form.

Note that the required fields and form location are different in version 9 from previous releases, so you must update existing forms to follow the new specification.

To provide default values for form fields, specify the named value(s) in the data string argument of the dtform command, and include ~name~ tags in the HTML document. For example an input field for a To address might look like this:

If the data string supplied to the dtform function contains to=someone@somewhere.com, then that email address will be presented as the default value when the form is displayed.

The formname$ value is the name of the html form file, which can be a full path or a name found in the standard browser interface search paths.

The title$ value is what is shown to the user when notified that the form needs to be displayed.

The userid$ and/or ip$ arguments are used to identify which user should receive the document. The preferred method is to specify a userid$ value. If no user ID is specified, then an IP address can be used. Only a browser logged in as the specified user, and/or connected from that IP address will be notified of the delivery and will be able to access it. The IP address reported in uf.clientip$ is typically the IP address of the computer that submitted the UnForm job, though in some circumstances it will be the address of a server computer rather than a user computer.

A suffix can be appended to the ip$ value. This suffix must match the value used in an ips=uniqueid query string in the browser monitor launch. For example: uf.clientip$+clientenv("SESSIONNAME").

The datastr$ is a URL-encoded string with form field values defined as name=value pairs as in normal web programming. It must be a string variable in order to receive form values back, which can then be decoded using the urlgetfld() function. If the string contains values when dtform is executed, those values are used in the form, wherever a ~name~ tag is found. To create the string with URL-encoded name=value pairs, use the urlsetfld() function.

Any non-0 responses are logged in the server log file. Rule sets that use the dtdel() function should query and react to non-0 responses as appropriate.

The timeout value is the number of seconds the user has to respond to the form request. Once the user accepts the form, they may take as long as needed to complete the form. However, the job will be halted waiting for the form submission, so users must understand that forms they accept should be submitted as soon as possible. If the user doesn’t accept the form within the specified number of seconds, a timeout response will be provided. The default timeout value is 30 seconds.

If a timeout of -1 is specified, then the form request step is skipped, and the form is displayed automatically. If no monitor is running or the user does not respond to the form, the job will be hung, so do not use this option unless you know the monitor is active and the user is available. This step might be used as an immediate follow up to a previous form that the user did respond to.

If an unexpected error occurs, it will be returned in errmsg$, if provided in the function arguments.

URL-encoded strings are comprised of name-value pairs with special character encoding. Use the following functions to create or parse the URL-encoded data string:

urlgetfld(datastr$,name$)	Returns the value of the name$ field. The value is returned without URL encoding. mailto$=urlgetfld(datastring$,"to")
urlsetfld(datastr$,name$,value$)	Returns a URL-encoded string with the field name$ set to value$. The field is added if necessary. datastring$=urlsetfld(datastring$,"to",someone@somewhere.com)
urldelflds(datastr$,names$)	Returns the a URL-encoded string after removing the fields specified in name$ from the URL-encoded string datastr$. Multiple fields can be separated by commas. datastring$=urldelflds(datastring$,"to,from,subject,body")
urlgetnames$(datastr$)	Returns a list of field names in the data string. fldlist$=urlgetnames$(datastring$) count=parsec(fldlist$,",’)