WebAG Automat 4.3

Overview of Documentation
Copyright © Enterprise Web AG.

 webag_logo.jpg (2199 Byte)

Form System
July, 2003

Contents

1. System Outline

1.1 Form Editor
1.2 Form Drivers
1.3 Container Monitor

2. Authorization

2.1 Form Editor
2.2 Form Drivers

3. Form Editor

3.1 Create New Form
   3.1.1 Edit Form
   3.1.2 Edit Element
   3.1.3 Subforms

4. Form Drivers

4.1 Edit a Form Driver
4.2 Test a Form Driver
   4.2.1. Form Input

5. Container Monitor

Contents | Back | Forward

1. System Outline

The Form Editor, as part of WebAG Automat, provides you with a simple way to create web forms. Using the Authoring System as a basis, we have designed an editor that allows you to compile all the relevant form elements: input fields, checkboxes, radio buttons, dropdown menus and combinations of these elements in lists. Attributes range from the restriction of field lengths to special input validation, so that a large number of applications are possible. Moreover, the system contains numerous innovative input facilities while allowing you to design your own specific layout and process data from an XML container.

  

Contents | Back | Forward

1.1 Form Editor

Use the Form Editor to compile a form with any of the available elements. There are no restrictions on the number or order of form elements. You decide. However, if you want to design a more complex form, you may prefer to maintain clarity by dividing the main form into two or more subforms. Elements can be grouped together in lists, so that several records can be saved in the form of tables.

Use attributes to restrict input options. The application has a field length restrictor for text fields, default values in dropdown menus (if you like, depending on input in other fields), and it allows you to mark so-called mandatory fields where input must not be omitted. It also has input validation functions both for default input and for custom-defined text.

The raw form is saved to the database in editable XML code, without any layout or design specifications. This starter form is filled with data in a container when entries are made, allowing either user-specific access control or anonymous access.

Users can edit form data until they close the form and then initiate the specific data processing procedure that follows and which is detailed in a form driver. This means that a form need not be completed in one session, but can be populated with data gradually, in several sessions.

 Contents | Back | Forward

1.2 Form Drivers

Each form driver contains form-specific processing instructions. This includes layout details and any authorities (anonymous or registered) on which the form may be based.

The INIT, SUBMIT and DELETE procedures specify what is to happen to the form once it has been completed and what should be done with the form data after the conclusion or cancellation of the input. The administrator can use all the options provided by the Oracle XML kit for PL/SQL in processing freely accessible form data from the XML container.

Contents | Back | Forward

1.3 Container Monitor

The Container Monitor is a control tool for any form input that is made and therefore only accessible to the administrator. Using specific selection criteria and a sort option (sorted by users and by changes made), the administrator can have specific access to the XML code of a form, irrespective of whether it has or still is being completed.

As well as the date of the last change and the name of the user, the administrator can view the internal processing number (ID) of the container. Moreover, he or she can delete the entire container or edit its content.

Contents | Back | Forward

2. Authorization

Privileges can be set on raw forms, form drivers and form container browsing. This relieves the administrator because creating and editing forms and form drivers can be carried to experienced authors.

 

2.1 Form-Editor

Administrators can appoint authors to edit already created forms.

The allocation of form authors occurs form by form in the particular form editor view. We use the same kind of allocation as  we do for pages or folders.

An author who can edit forms gets a folder named Forms in the authoring system's navigation tree after he logged in. In the forms list he gets all forms he can edit.

 

2.2 Form-Driver

Administrators can appoint authors and container editors individually to form drivers.

The allocation occurs in the form drivers settings. We use the same kind of allocation as  we do for pages or folders.

Authors

Authors can edit already created form drivers and test them. An author who can edit form drivers gets a folder named Form driver in the authoring system's navigation tree after he logged in. In the form drivers list he gets all form drivers he can edit.

Container-Editors

Container-Editors can monitor form containers, i.e. see them. A user who can see form containers gets a folder named Container monitor in the authoring system's navigation tree after he logged in. Forms can be viewed there like described in  5. Container Monitor.

Inhalt | Zurück | Vor

 

3. Form Editor

3.1 Create New Form

Each forms is created separately by the administrator. Grouping – i.e. the assignment of subforms to forms – takes place separately in the Editor for each form.

The function “Create New Form” presents a blank form without any elements. This new form may also be a copy of a different form, which is later edited in the Editor.

Contents | Back | Forward

3.1.1 Edit Form

Form editing mode is based on the same principle as page editing and has an intuitive user interface. Each form element is added in the same way that paragraphs would be added to a page. The same applies to the positioning and editing of elements. Depending on the type, form elements can be distinguished from or associated with each another through the use of colours, indents and frames.

Contents | Back | Forward

Copy and Delete

Of the form editing functions, copying and deletion are fairly self-explanatory. Copying automatically calls up edit mode for the resulting copy. Deletion is preceded by a confirmation prompt and the specification of the form that is to be deleted.

Contents | Back | Forward

XML Source Text

XML source text is generated by the form system in the background and saved to the database. Any changes to the source code or to the database should only be conducted by experienced administrators. It is important that all modifications must comply with XML syntax. If this syntax is violated, the Form Editor returns an error message, and correction can only take place in the XML source text.

Any work on source text should be restricted to changes to existing elements. However, if you wish to add new form elements, use the Editor, as the application allocates internal IDs (attribute IDs) which are unique. However, their uniqueness cannot be guaranteed under the manual editing of source text.

Contents | Back | Forward

XML Import

XML Import allows you to import the XML source text of an existing form. This function also handles the adjustment of IDs. We would recommend creating a blank form and copying the source text into the XML import field, using Copy & Paste.

Contents | Back | Forward

Test Form

It is also possible to test a form during development. To do so, create a form container for the relevant form and, if necessary, for its subforms. The completion of the form container with data can be monitored in the Container-Monitor.

A form can only be tested if it has a Formr-Driver. Otherwise no testing is possible, nor can the form go live.

Once a Form-Driver has been assigned and the form container has been automatically created, you can call up the form.

Contents | Back | Forward

3.1.2 Edit Element

Each form consists of a number of elements. You can place any number of elements in any order, and it is also possible to change the order. The basic Copy and Delete function can be applied to elements without affecting the uniqueness of internal IDs.

The following elements can be selected:

Name Internet term Internal XML tag (*)
Text field Text field wt_TEXT
Text area Text aera wt_TEXTAREA
Checkbox Ceckbox wt_CHECKBOX
Dropdown menu
  • Option
 Select
  • Option
 wt_SELECT
  • wt_OPTION
Radio button
  • Option
 Radio Button
  • Option
 wt_RADIO
  • wt_OPTION
List
  • Row in table
  • Next elements
 List
  • Row
 wt_LIST
  • wt_ROW
External External wt_EXTERNAL
Hidden Hidden wt_HIDDEN

(*) TAGs are case-sensitive

Dropdown menus, radio buttons and lists have nested TAGs. In the case of dropdown menus and radio buttons, these TAGs are options (which may be one or more in each case), headed by wt_OPTION. Lists are created in the form of tables. In a header, headed by wt_ROW, they can accommodate all the other elements as columns, with the exception of lists themselves.

When elements with nested TAGs are created, the Editor indicates this through colours, indenting and frames. Dropdown menu items and radio buttons can be copied, pasted, deleted and positioned within the relevant frame.

Elements and Attributes

Each element can have attributes assigned to it, so that a certain control flow is possible even at the preliminary stage of the editing process. Not only can you restrict the length of an input field, but it is also possible to define certain default values for fields, designate fields as mandatory and assign validation procedures to the input.

The following attributes are permitted for each element:

  wt_TEXT wt_TEXTAREA wt_CHECKBOX wt_SELECT wt_OPTION wt_RADIO wt_OPTION wt_EXTERNAL

wt_LIST

 wt_HIDDEN
NAME x x x x x x   x x x
LABEL x x x x x x x x x  
URL x x x x   x   x x  
ON_INSERT                 x  
ON_DELETE                 x  
MAX_ROWS                 x  
PROMPT x x x x   x   x    
PROMPT_FREE       x            
VALUE x x x   x   x x available
elements:

wt_TEXT
wt_TEXTAREA
wt_CHECKBOX
wt_SELECT
wt_RADIO
wt_EXTERNAL
wt_HIDDEN

 x
SIZE x     x          
ROWS   x              
COLS   x              
ON_EDIT               x  
ON_SHOW               x  
ON_CHANGE x x x x   x   x  
TARGET               x  
INPUT               x  
VALIDATE x x              
FORMAT x x              
CHECKED     x       x x  
SELECTED       x          
FREE       x          
SQL         x        
REQUIRED x x   x   x      

 

Let us have a look at each element in detail:

Text field (wt_TEXT)
Single-line text fields can be restricted for input length. Their content (VALUE) can be obtained through validation procedures or through the OPTIONS provided in a dropdown menu, via the variable ${VALUE} (‘${VALUE}’ for the content of a string). A pop-up window is presented to allow the editing of a text field in form input.

Text area (wt_TEXTAREA)
The size of a text area is determined by the number of columns (COLS) and rows (ROWS).

Checkbox (wt_CHECKBOX)
Checkboxes allow the user to place checkmarks. They cannot be grouped in the same way as radio buttons.

Dropdown menu (wt_SELECT mit wt_OPTION)
A dropdown menu can be filled with OPTIONs either manually or automatically, based on SQL instructions from database tables. If required, it is also possible to enter any values that are not specified in the menu. Whenever a form is completed, the VALUE of the dropdown menu is marked to indicate whether an entry comes from a list of values or whether it is free text.

Radio Button (wt_RADIO mit wt_OPTION)
The content of a group of radio buttons is specified through wt_OPTIONs. Users are restricted to one selection within each group.

List (wt_LIST)
In a list, all elements may occur any number of times, except lists themselves (so that there cannot be nested lists). The elements of a list are assigned through its attributes. All the possible elements outside and within the list are displayed and can be assigned.

Extern (wt_EXTERNAL)
Own fields defined and stored in PL/SQL Stored Procedures. File Upload is preset and also WebAG Automat standard functionality.

Hidden (wt_HIDDEN)
Hidden fields can be used for the transportation of details that are not displayed on the form web page.

 

Let us have a look at each attribute:

NAME
Description Internal name of an element. Useful for any further processing of form data alongside the internally assigned unique ID attribute.
Use in wt_TEXT, wt_TEXTAREA, wt_CHECKBOX, wt_SELECT und wt_OPTION, wt_RADIO, wt_LIST, wt_EXTERNAL, wt_HIDDEN


LABEL
Description This function displays an element in form view.
Use in wt_TEXT, wt_TEXTAREA, wt_CHECKBOX, wt_SELECT / wt_RADIO und wt_OPTION, wt_EXTERNAL, wt_LIST


URL
Description Internet/intranet address as a reference to a help text accompanying a form element
Use in wt_TEXT, wt_TEXTAREA, wt_CHECKBOX, wt_SELECT, wt_RADIO, wt_EXTERNAL, wt_LIST

 

ON_INSERT
Description PL/SQL procedure which is run when adding a row to a list. The syntax is:

my_package.on_insert (
   i_form_container_id => ${FORM_CONTAINER_ID},
   i_element_name      =>'${ELEMENT_NAME}',
   i_row               =>${ROW})
 
Variables The following variables can be passed on to the insert procedure so that they are replaced upon execution:
  • ${FORM_CONTAINER_ID}
    Internal ID of the form container

  • ${LANG}
    Language variable DE or EN, (set in form driver)
  • ${ELEMENT_ID}
    ID of the current form element
  • ${ELEMENT_NAME}
    Internal name of the current form element
  • ${ROW}
    List Row
Use in wt_LIST

 

ON_DELETE
Description PL/SQL procedure which is run when deleting a row from a list. The syntax is:

my_package.on_delete (
   i_form_container_id => ${FORM_CONTAINER_ID},
   i_element_name      =>'${ELEMENT_NAME}',
   i_row               =>${ROW})
 
Variables The following variables can be passed on to the delete procedure so that they are replaced upon execution:
  • ${FORM_CONTAINER_ID}
    Internal ID of the form container

  • ${LANG}
    Language variable DE or EN, (set in form driver)
  • ${ELEMENT_ID}
    ID of the current form element
  • ${ELEMENT_NAME}
    Internal name of the current form element
  • ${ROW}
    List Row
Use in wt_LIST

 

MAX_ROWS
Description Limitation of rows in a list
Use in wt_LIST

 

PROMPT
Description Additional text when activating an input field
Use in wt_TEXT, wt_TEXTAREA, wt_CHECKBOX, wt_SELECT, wt_RADIO, wt_EXTERNAL

 

PROMPT_FREE
Description Additional text for free-input when activating an input field
Use in wt_TEXT, wt_TEXTAREA, wt_CHECKBOX, wt_SELECT, wt_RADIO, wt_EXTERNAL


VALUE
Description A specific default value in an element, shown in form view.
Use in wt_TEXT, wt_TEXTAREA, wt_CHECKBOX, wt_OPTION, wt_EXTERNAL, wt_HIDDEN


SIZE
Description Length of characters in a text field or number of elements in a dropdown menu
Use in wt_TEXT, wt_SELECT


ROWS, COLS
Description Number of columns and rows in a text area
Use in wt_TEXTAREA

 

ON_EDIT
Description PL/SQL Procedure executed when editing a field. The syntax is:

wt_show_form.edit_upload(
   i_form_container_id => ${FORM_CONTAINER_ID},
   i_lang              =>'${LANG}',
   i_element_id        =>${ELEMENT_ID},
   i_element_name      =>'${ELEMENT_NAME}')
 
Variables The following variables can be passed on to the edit procedure so that they are replaced upon execution:
  • ${FORM_CONTAINER_ID}
    Internal ID of the form container

  • ${LANG}
    Language variable DE or EN, (set in form driver)
  • ${ELEMENT_ID}
    ID of the current form element
  • ${ELEMENT_NAME}
    Internal name of the current form element
  • ${ROW}
    List Row
Use in wt_EXTERNAL

 

ON_SHOW
Description PL/SQL Procedure executed when showing the value of a field. The syntax is:

wt_show_form.show_upload(
   i_form_container_id => ${FORM_CONTAINER_ID},
   i_element_id        =>${ELEMENT_ID})
 
Variables The following variables can be passed on to the show procedure so that they are replaced upon execution:
  • ${FORM_CONTAINER_ID}
    Internal ID of the form container

  • ${LANG}
    Language variable DE or EN, (set in form driver)
  • ${ELEMENT_ID}
    ID of the current form element
  • ${ELEMENT_NAME}
    Internal name of the current form element
  • ${ROW}
    List Row
Use in wt_EXTERNAL

 

ON_CHANGE
Description PL/SQL procedure which is run after a value has been changed. The syntax is:

my_package.on_change(
   i_form_container_id => ${FORM_CONTAINER_ID},
   i_element_name      =>'${ELEMENT_NAME}',
   i_row               =>${ROW})
 
Variables The following variables can be passed on to the change procedure so that they are replaced upon execution:
  • ${FORM_CONTAINER_ID}
    Internal ID of the form container

  • ${LANG}
    Language variable DE or EN, (set in form driver)
  • ${ELEMENT_ID}
    ID of the current form element
  • ${ELEMENT_NAME}
    Internal name of the current form element
  • ${ROW}
    List Row
Use in wt_TEXT, wt_TEXTAREA, wt_CHECKBOX, wt_SELECT, wt_RADIO

 

TARGET
Description Target window of external field (_self, _blank)
Use in wt_EXTERNAL

 

INPUT
Description Makes input in the field possible or not (enable/disable input link)
Use in wt_EXTERNAL


VALIDATE
Description PL/SQL procedure for an input validation routine. Called up in form input along with the container ID. Two validation elements are available by default: DATE und NUMBER
Variables The following variables can be passed on to the validation procedure so that they are replaced upon execution:
  • ${FORM_CONTAINER_ID}
    Internal ID of the form container

  • ${LANG}
    Language variable DE or EN, (set in form driver)
  • ${ELEMENT_ID}
    ID of the current form element
  • ${ELEMENT_NAME}
    Internal name of the current form element
  • ${VALUE}
    Input value 
  • ${FORMAT}
    Format string for NUMBER, DATE or own validating procedures.
Use in wt_TEXT, wt_TEXTAREA


FORMAT
Description Formatting instructions for the validation routine, e.g. DD.MM.YYYY for the date or 999.99 for numeric input.
Use in wt_TEXT, wt_TEXTAREA


CHECKED
Description Preselection of a checkbox or radio button. In the case of a radio button,  CHECKED=TRUE automatically means that all the other associated elements are set to CHECKED=FALSE. 
Use in wt_CHECKBOX,  wt_OPTION in wt_RADIO


SELECTED
Description Preselection of a value in a dropdown menu. The values of the relevant wt_OPTIONs are available for selection.
Use in wt_SELECT


FREE
Description Free text input permitted alongside elements from a dropdown menu.
Use in wt_SELECT


SQL
Description

SQL instruction to fill NAME-VALUE pairs in a dropdown menu. The syntax is:

SELECT row_x NAME, row_y VALUE
  FROM table
 WHERE condition

The WHERE condition may contain the variable ${<element­_name>}, where  element_name is the internal name (attribute: NAME) of an element used in the form. If it is a string, single quotes must be used:  '${<element_name>}'

The variable of the SQL instruction is replaced during form input. This makes it possible to create dependencies between input in other fields and select elements, e.g. displaying certain cities after a country has been selected.
Use in wt_OPTION in wt_SELECT 


REQUIRED
Description Marks a field as mandatory, so that input is required. Checking takes place when the form has been filled in. If input is missing, a suitable alert is presented.
Use in wt_TEXT, wt_TEXTAREA, wt_SELECT, wt_RADIO

NB:
The Quick Tour of the Form System contains an example of a custom-defined validation function for checking the correct syntax of an e-mail address.

Contents | Back | Forward

3.1.3 Subforms

If a form is of a more complex kind, we would recommend dividing it into subforms. You can define and associate any number of subforms with a given form. However, each form cannot occur as a subform more than once. It is not possible to use a form as a subform for several different main forms. This is taken into account when a list of possible main forms is presented for allocation.

Once a subform has been allocated, this allocation can easily be reversed again any time, without affecting data that has already been entered. As with all changes to the raw form, existing data is left intact.

Contents | Back | Forward

 

4. Form Drivers

4.1 Edit a Form Driver

Each form driver can be created for no more than one form, though a form may have several form drivers, so that a variety of different processing options become available. All (main) forms are selectable.

Each form driver has a language variable associated with it – ${LANG} – which can be queried in custom-defined validation procedures. This means, for instance, that a date on an English form can be validated under English rules, and a date on a German form under German rules.


Authorization

The authorization blueprint, which is also used in the Authoring System, is applied to forms in a similar way. You can specify in each form driver whether a form should be restricted to logged-in users or whether it can also be called up anonymously. If a form is subject to login, the user ID is associated with the form container, so that a user is identified each time he or she logs in and can then continue their data input. If anonymous use is permitted, the form must fill in and sent off in one sitting.

 

Design

Form output is associated with the website from which it receives its web page design information. In addition, it is possible to specify text layouts and trigger sets. The form is displayed together with the number and width of columns as well as with the selected layout and design details.

 

Form Input Mode

You can choose between two input windows – pop-up and pop-in windows. They refer to the way in which input is accepted by the form. Under “Pop-Up” a separate window is opened for each input, whereas under “Pop-In” input is entered into the current web page.

 

Form Processing - Init, Submit, Delete and Return

The processing of form data from the form container differs from one application to another. By default, the form system allows you not only to save data to an XML container in the database, but also to send data to a specified e-mail address.

To realize custom-defined applications through a call (Init), through the sending of data (Submit) or through the deletion (Delete) of a (partially) completed form, it is possible to use PL/SQL procedures that can access data in the XML container, specifying either custom-defined or internal parameters.

Enterprise WebAG offers specially customized training seminars on PL/SQL and on the relevant Oracle XML Toolkit, so that you can learn to develop custom-defined web applications within a short period of time.

 

Init

This procedure call is executed whenever the form is called up for the first time. As initialization is optional before completing a form, this function, too, is optional.

The PL/SQL procedure can be given form-specific data in the form of variables which are replaced when the procedure is called. Click here for a list of possible variables.

 

Submit

This procedure call is executed whenever form input is checked for mandatory fields and the form is concluded.

The PL/SQL procedure can be given form-specific data in the form of variables which are replaced when the procedure is called. Click here for a list of possible variables.

The example shows the calling of the default procedure for sending form data to an e-mail recipient. The procedure variable i_form_container_ID is assigned i_form_container_id => ${FORM_CONTAINER_ID}, so that it has the internal container ID of the data saving procedure and can be used for further processing.

Example: Sending container form data to an e-mail address.

wt_form_api.submit_handler_mail (
    i_form_container_id => ${FORM_CONTAINER_ID},
    i_from              => 'webmaster@webag.com',
    i_to                => 'info@webag.de',
    i_subject           => 'Form Mail',
    i_format            => 'TEXT')

The Quick Tour of the form system contains an example of a custom-defined validation function to check for the correct syntax of an e-mail address.

Delete

This procedure is called whenever form input is to be deleted.

The PL/SQL procedure can be given form-specific data in the form of variables which are replaced when the procedure is called. Click here for a list of possible variables.

 

Return Website URL

The internet/intranet address specified here is shown whenever a form is concluded after a successful check for mandatory input.

 

Variables in Procedure Calls

The variable ${FORM_CONTAINER_ID} is replaced by the current container ID of the form. To use the variable, it is possible for a call to have its own PL/SQL procedure, e.g. a line in the form of

i_form_container_id => ${FORM_CONTAINER_ID}

In such a case the procedure variable i_form_container_id has the value of the container ID.

Contents | Back | Forward

 

4.2 Test Form Driver

When testing a form driver, a container entry is created for the relevant form and offered for editing via a link.

 

4.2.1. Form Input

The form input page is shown with all the layout and design specifications that have been set. If the form consists of several subforms, then they can be selected via a dropdown menu. Input can be made separately in each field and – unlike in conventional form input – is saved immediately. To help with the input, it is possible to set the option “Save and Continue” in the input popup window. This means that each input can be acknowledged by pressing ENTER, whereupon the text cursor automatically goes to the next input field.

Contents | Back | Forward 

 

5. Container Monitor

The Container Monitor enables the administrator to monitor form input. Data output can be filtered and sorted, and it is also possible to conduct a full text search through all data items saved in XML format. The administrator can also call up each form for data input or delete it.

Only main forms can be viewed in the list of filtered forms. When calling the edit form, the relevant subforms are offered for editing in the usual way. Before a deletion, a query is presented, whereupon all subforms are deleted that belong to this form.

Contents | Back | Forward

 

WebAG Automat Documentation
Copyright © Enterprise Web AG.
All rights reserved.