Browser Forms Configuration

 Top 

 

browser Forms configuration

 

The archive browser interface supports custom forms that can be accessed from specific points.  These forms, when submitted, execute an UnForm job and provide that job with information from the form as well as the user's browser session and the CGI environment.  The UnForm job can perform tasks that might involve updating document properties on a selected or related document, or execute some other task related to a document.

 

When the job is run, it can be designed to return data to the browser, in the form of a PDF file or HTML text.  Optionally, the job can be run asynchronously and a configurable response message is returned instead.

 

The job must be designed to operate with no usable input stream.  If the job's output is to be returned to the browser, the first page of data will be replaced or suppressed by the job. Variables are provided to access information the user completed in the form, so typically the job will be designed with code blocks that interact with this data.

 

There are several related configuration steps for  setting up browser forms:

 

•HTML forms must be defined and stored in the server's active web/en-us or web/language directory.  The forms must have a .html extension.
 
•A rule file and rule set must be created, designed to act upon the data from the form.  This rule set will have access to some template variables: cgi$, env$, and session$, which are populated from the form and the user's session.
 
•The forms.ini file must be defined to enable users or groups to access forms designed for a given library and document type.

 

 

HTML Form Structure

 

The HTML form may have any valid HTML structure for a form, but must contain a few mandatory elements.  The form_sample.html file found in web/en-us provides this example form code:

 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>

   <link rel="stylesheet" type="text/css" href="[SCRIPT_NAME]?fl=default.css" />

   <link rel="stylesheet" type="text/css" href="[SCRIPT_NAME]?fl=custom.css" />

   <script language="JavaScript" src="[SCRIPT_NAME]?fl=common.js"></script>

   <title>

         Document Approval

   </title>

</head>

<body onunload="saveWindowInfo()">

 

<h2>Approve or Deny Action on this document</h2>

 

<form name="approval" action="[SCRIPT_NAME]" method="post">

<input type="hidden" name="a" value="uf">

<input type="hidden" name="args" value="-f cgiforms.rul -r approval -p pdf">

<input type="hidden" name="run" value="">

<input type="hidden" name="async" value="0">

<input type="hidden" name="lb" value="[lb]">

<input type="hidden" name="doctype" value="[doctype]">

<input type="hidden" name="docid" value="[docid]">

 

<table class="form">

       <tr>

               <th>Library</th>

               <td>[lb]</td>

       </tr>

       <tr>

               <th>Doc Type</th>

               <td>[doctype]</td>

       </tr>

       <tr>

               <th>Doc ID</th>

               <td>[docid]</td>

       </tr>

       <tr>

               <th>Categories</th>

               <td>

                       <script>

                               // present categories in lines

                               var cat='[categories]';

                               cat=cat.replace(/;/g,"<br>");

                               cat=cat.replace(/\|/g," &gt; ");

                               document.write(cat);

                       

                       </script>

               </td>

       </tr>

       <tr>

               <th>Approval</th>

               <td>

                       <input type="radio" name="approval" value="0" checked>Denied<br>

                       <input type="radio" name="approval" value="1">Approved<br>

               </td>

       </tr>

       <tr>

               <td colspan="2" style="text-align:center;">

                       <input type="button" value="Submit" onclick="submitForm()">

                       &nbsp;&nbsp;&nbsp;

                       <input type="button" value="Cancel" onclick="window.close();">

               </td>

       </tr>

</table>

</form>

 

</body>

</html>

<script>

       function submitForm() {

               document.approval.run.value="y";

               document.approval.submit();

       }

</script>

 

 

This example shows a form related to particular document, identified by the CGI fields lb, doctype, and docid.   Document field values are represented by tags [fieldname], where the field name can be any of lb, doctype, docid, date, time, title, entityid, notes, keywords, categories, links, dateupdated, and timeupdated.  Date fields are provided in YYYYMMDD format, time fields in HH:MM:SS format, keywords and links in semicolon-delimited format, categories in semicolon (category), vertical bar (segment) delimited format, and notes with hard line breaks represented as "\n" literal sequences.

 

In the form above, notice how javascript code is used to display categories with different line and segment delimiters.

 

Several fields must submitted with the form in addition to lb, doctype, and docid.  These include a (set to "uf"), args (set to a string of command line arguments), and run (set to a non-null value when the form is submitted (see the submitForm() function at the bottom of the document).  Optionally, the async field can be set to 1 to run the UnForm job asynchronously.  When this happens, the browser response is based on the form_async.html document found in web/en-us (or web/­language if configured). Otherwise, the browser response is either the UnForm job output (typically a PDF file) or a text response set into the cgiresponse$ variable in one of the job's code blocks.

 

It is possible to have the text response contain script code that simply closes the window:

 

<script>window.close();</script>

 

The variable args is especially important, as it specifies, at a minimum, the rule file and rule set to execute when the form is submitted.  It may also supply other options, such as -prm parameters, or a ‑p pdf if the job's output will be the response to the browser.

 

CGI-Driven Rule Sets

The UnForm job that runs is a rule set named in the args variable of the HTML form, with the ‑f rulefile ‑r ruleset options.  A sample rule set is defined in the samples/cgiforms.rul file, called "approval".

 

[approval]

prejob{

       approved=num(cgi.approval$)

       cgiresponse$="Approved"

       if not(approved) then cgiresponse$="Not approved"

}

 

In this very simple rule set, a value is sent from the HTML form field "approval".  This field is a radio button with a value of 0 or 1, depending on which button is checked (see the HTML sample above for the HTML form coding used).  The variable cgiresponse$ is set to a text value that is returned to the browser.

 

Alternatively, if cgiresponse$ is not set, then the job's output is returned to the browser.  In this case, the HTML form would specify a "-r approval2" and "-p pdf" in the args variable.  The result will be a simple PDF document with text indicating the value of the approval field.  Note that the print stream data contains data communicated to the rule set that is normally of no use to the user, hence the use of the notext command to suppress print stream text.  Other techniques might be code block resets of the text$[] array, or an erase command.

 

[approval2]

prejob{

       approved=num(cgi.approval$)

}

notext

text 10,10,{"Approval: "+str(approved)},cgtimes,12

 

 

There are three template strings provided to code blocks in a CGI-driven rule set:

 

•cgi$ contains all the form fields that are present in the HTML form.  All cgi$ fields are string fields, so all are accessed as above: cgi.field$.
 
•env$ contains the CGI environment variables, if needed, such as env.script_name$ and env.remote_host$.  CGI environment variables are documented in many places on the Internet and in numerous books on web scripting.
 
•session$ contains fields related to the user's session.  Of particular note might be the user login ID, which is found in session.s_userid$.
 

 

Form Access Configuration

The forms.ini file contains configuration information that the browser interface uses to provide automatic links to forms under certain circumstances.  A sample forms.sds file is provided with the UnForm installation for reference.

 

Document-Oriented Forms

When a user is logged in and viewing document properties or a document image, a Forms tab is offered if any forms are configured that meet the session criteria, and links to all available forms are provided in that panel.

 

Here is a sample forms.ini file:

 

#sections by library|doctype

# user:<name>=form name[,description]

# group:<name>=form name[,description]

# *=form name[,description]

 

[demo_sales|OpInvoice]

user:theboss=form_approval,Approval Form

group:sales=form_rep_action,Sales Rep Action

*=form_site,Site Form Info

 

Sections in this file are identified by a [library|doctype] heading.  When a document of that document type is viewed from that library, forms configured on the following lines will be available, depending on the user and user group membership.  Any given form is only presented once, even if the circumstances would cause multiple configuration lines to present the same form.

 

In the above example, the user "theboss" can access the form_approval.html form, any user in the group "sales" can access the "form_rep_action.html" form, and any user can access the "form_site.html" form.  All forms that meet the security criteria are available.  For example, user "theboss" will have access to form_approval and form_site, and any user in the group "sales" will have access to form_rep_action and form_site.

 

Search- and Marked-Related Forms

In addition to forms selected when viewing documents of a configured library and document type, forms can also be executed from search results and marked record lists.  These are configured in a similar manner, with sections in the forms.ini file.

 

A [search] section denotes user or group form access when viewing search results.  If the results of a saved search are being viewed, then a section named [search|saved search name] can be defined, also with user:userid and/or group:groupid access.  Search-based rule sets can use a search object's doclist object to navigate and react to the search results.

 

Finally, a [marked] section can be defined to allow forms driven from a marked records list.  The marked object can be used to navigate and manipulate the marked record list for a user's session.

 

[search]

group:managers=form_transfer,Transfer Documents Form

user:admin=form_transfer,Transfer Documents Form

 

[search|CurrentInvoices]

group:AR=form_CurrentInvReport,Report of Current Invoices

 

[marked]

user:jsmith=form_jsmith_purge,Purge Marked Documents