Quick Tour
The Form System of WebAG Automat
As a component of WebAG Automat, the Form Editor
provides you with a simple tool to create on-screen forms, ranging from simple
to complex, without requiring any special knowledge of HTML. All customized
data processing can be handled through the procedural language PL/SQL (an
enhancement of SQL), with numerous basic processing functions.
The purpose of this Quick Tour is to explain the most central functions
of the Form System and to help you create, process and administrate your first
forms.
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.
Calling up the Form System
Forms can only be created and administrated by a
central webmaster. The Form Editor can be found in the navigation tree under
the item “System Forms”. This is also the location of two further elements
you need for your work with forms – the form drivers and the Container
Monitor (see below).
Illustration
1 - Form System
Structure of the Editor
As soon as you have created a new form – which may be
either blank or a copy of a previous form – the new form is opened in edit
mode in the Editor.
Below the form name, a number of functions are displayed
which relate to the entire form: Copy, Delete, etc. Underneath, in the yellow
field, the application shows a number of form details which are editable. The
main section of the Editor is a grey area for placing the various form
elements. At this stage this section is still blank.
Illustration 2 - Form
Editor
Example: “Address Form”
In this Quick Tour we want to give you an example of how
you might create a simple address form. An address form consists of text
fields for a person’s surname, first name, street address, city, post code,
country, phone number and e-mail address. To help users with their input, we
want the city and country fields to offer values that are dependent on one
another, so that as soon as a country has been selected, the user is only
offered a selection of cities in that country.
The phone number field is to be verified in such a way
that only numeric input is permitted. This is the purpose of the standard
verifier “NUMBER”. E-mail addresses are to be verified for correct syntax,
allowing only the structure name@domain.com. To do so, we are going to
write a special PL/SQL function that will handle this task.
Next, all input entered into the address form is to be
sent by a form driver to the central webmaster.
Internal form fields and their labels
| Label |
Name (intern) |
| First name |
p_firstname_text |
| Surname |
p_surname_text |
| Country |
p_country_select |
| City |
p_city_select |
| Post code |
p_postcode_text |
| Telephone |
p_telephone_text |
| e-Mail |
p_email_text |
|
| Illustration
3 – form details |
These elements can then be inserted in the Editor. Both
their order and their individual attributes can be changed later.
The elements and their attributes
| First name |
| NAME |
p_firstname_text |
| LABEL |
First name |
| SIZE |
80 |
| REQUIRED |
activated |
| Surname |
| NAME |
p_surname_text |
| LABEL |
Surname |
| SIZE |
80 |
| REQUIRED |
activated |
| Country |
| NAME |
p_country_select |
| LABEL |
Country |
| SIZE |
1 |
| SQL in Option |
select distinct
nation_langtext NAME, nation VALUE
from w_nation order by nation_langtext |
| SELECTED |
Germany |
| FREE |
True |
| REQUIRED |
activated |
| Post code |
| NAME |
p_postcode_text |
| LABEL |
Post code |
| SIZE |
6 |
| REQUIRED |
activated |
| City |
| NAME |
p_city_select |
| LABEL |
City |
| SIZE |
1 |
| SQL in Option |
select distinct stadt NAME,
stadt_int_id VALUE
from w_stadt_int where nation = '${p_land_select}'
order by stadt |
| FREE |
True |
| REQUIRED |
activated |
| Telehone |
| NAME |
p_telephone_text |
| LABEL |
Telephone |
| SIZE |
20 |
| VALIDATE |
NUMBER |
| REQUIRED |
activated |
| email |
| NAME |
p_email_text |
| LABEL |
e-Mail |
| SIZE |
40 |
| VALIDATE |
my_validation.check_email (
i_value =>
'${VALUE}',
i_form_container_id => ${FORM_CONTAINER_ID},
i_lang =>
'${LANG}',
i_element_id =>
${ELEMENT_ID},
i_format
=> '${FORMAT}') |
| FORMAT |
name@domain.de |
| REQUIRED |
activated |
The Address Form in the Editor
table of
addresses
Edit form Copy
| Delete | XML-sourcecode
| XML-import | Test
form | Forms list
| Form-ID: |
1103154 |
| Subform
to: |
no related
top-level f |
| Formname: |
table of
addresses |
| Description: |
Quicktour
example form |
|
| TEXT |
edit
element | copy |
delete   |
|
| NAME |
p_firstname_ |
| SIZE |
80 |
| LABEL |
First
name |
| REQUIRED |
TRUE |
|
|
|
| Insert element: Textfield | Textarea | Checkbox | Select | Radiobutton | List |
| TEXT |
edit
element | copy |
delete |
|
| NAME |
p_surname_text |
| SIZE |
80 |
| LABEL |
Surname |
| REQUIRED |
TRUE |
|
|
|
| Insert element: Textfield | Textarea | Checkbox | Select | Radiobutton | List |
| SELECT |
edit
element | copy |
delete |
|
| NAME |
p_country_select |
| SIZE |
1 |
| FREE |
TRUE |
| LABEL |
Country |
| REQUIRED |
TRUE |
|
|
| OPTION |
edit
element | copy |
delete |
|
| NAME |
p_country_option |
| VALUE |
default |
| SQL |
select distinct nation_langtext
NAME, nation (...) |
|
|
|
|
| Insert element: Textfield | Textarea | Checkbox | Select | Radiobutton | List |
| TEXT |
edit
element | copy |
delete |
|
| NAME |
p_postcodetext |
| SIZE |
6 |
| LABEL |
Post
Code |
| REQUIRED |
TRUE |
|
|
|
| Insert element: Textfield | Textarea | Checkbox | Select | Radiobutton | List |
| SELECT |
edit
element | copy |
delete |
|
| NAME |
p_city_select |
| SIZE |
1 |
| FREE |
TRUE |
| LABEL |
City |
| REQUIRED |
TRUE |
|
|
| OPTION |
edit
element | copy |
delete |
|
| NAME |
p_city_option |
| VALUE |
default |
| SQL |
select distinct stadt NAME,
stadt_int_id VALU (...) |
|
|
|
|
| Insert element: Textfield | Textarea | Checkbox | Select | Radiobutton | List |
| TEXT |
edit
element | copy |
delete |
|
| NAME |
p_telephone_text |
| SIZE |
20 |
| LABEL |
Telehpone |
| VALIDATE |
NUMBER |
| REQUIRED |
FALSE |
|
|
|
| Insert element: Textfield | Textarea | Checkbox | Select | Radiobutton | List |
| TEXT |
edit
element | copy |
delete |
|
| NAME |
p_email_text |
| SIZE |
20 |
| LABEL |
e-Mail |
| VALIDATE |
my_validation.check_email
(i_value => '${VALU (...) |
| FORMAT |
name@domain.de |
| REQUIRED |
FALSE |
|
|
|
| Insert element: Textfield | Textarea | Checkbox | Select | Radiobutton | List |
|
|
Illustration
4 - Addressform in the editor |
The Validation Procedure “check_email”
Note the following call for a validation procedure in
the attribute VALIDATION:
my_validation.check_email (
i_value =>
'${VALUE}',
i_form_container_id => ${FORM_CONTAINER_ID},
i_lang =>
'${LANG}',
i_element_id =>
${ELEMENT_ID},
i_format
=> '${FORMAT}') |
|
Illustration 5 -
Procedure call for validation |
Enter this call in a single line. In this instance, it
is only for reasons of clarity that we have formatted the call in the way
shown above, spread out over several lines. Make sure you put the string
variables in single quotes (' '). If you are a PL/SQL programmer, make sure
you do not conclude this call with a semicolon (;).
Source Text of the Validation Procedure
For the following validation procedure and possibly for
further, custom-defined ones, we want to create a dedicated PL/SQL package,
e.g. “my_validation”, shown in the call above.
To validate an e-mail address, the procedure checks
whether the string contains an @ and whether the characters before (pre_at)
and after (post_at)
the @ are permitted combinations of letters, figures and special characters
(i.e. “_” underscore and “.” full stop). The top level domain (.co.uk,
.com, .org, .de, .fr, .nl, etc.) is checked against a list of items (in the
database).
Note the following source text template which can be
used in this form for ANY validation procedure. We are not going to quote the
entire code at this point. Instead we would refer you to the PL/SQL training
course run by Enterprise Web AG.
PROCEDURE check_email (
-- Zu pruefender Wert
i_value
IN VARCHAR2 DEFAULT NULL,
i_list_row
IN NUMBER DEFAULT
NULL,
-- Angaben zum Container
i_form_container_id IN NUMBER,
i_lang
IN VARCHAR2 DEFAULT NULL,
-- Angaben Eingabeelement
i_element_id IN
NUMBER,
i_format
IN VARCHAR2 DEFAULT
NULL)
IS
BEGIN --
Implementation
EXCEPTION
WHEN others THEN
IF i_lang = 'de' THEN
raise_application_error(-20815,'Fehlermeldung
Deutsch');
ELSE
raise_application_error(-20815,'Error
message english');
END IF;
END; |
|
Illustration 6 -
Source pattern for validating |
The Address Form Driver
The content of the form is to be sent to an e-mail
address. To achieve this, we need to create an address form driver.
First, we assign the address form we have created to the
form driver. This is the form which the form driver will start. In this simple
example, authorization takes place without any login. For our test, we can use
the design, layout and trigger set that are available in the installed
Authoring System. As this form is relatively small, we only need a width of
600 pixels for the division into columns. In this instance, the language –
English or German – will only affect the error messages returned in the
validation procedures.
Of the three operations Init, Submit and Delete,
we only need Submit. No initialization is required for this form. To
delete, we are going to use the standard function for the deletion of
container contents.
Submit
The specified procedure for sending e-mails uses the
following call:
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
=> 'Formular-Mail',
i_format
=> 'TEXT')
|
|
Illustration 7 –
Procedure call SUBMIT for form drivers |
The parameters i_from, i_to, i_subject and i_format
can be customized to suit your own needs.
Testing the Address Form
The address form can now be tested straight from within
the Form Editor.
Illustration 8 –
Address form (Form Editor)
You are now prompted to select a form driver to control
the form. This means that you need to have created at least one driver before
the test. Alternatively, it is also possible to start the testing of a driver
while editing a form driver.
Integration into Custom-Defined Websites
To call up the address form on a website, the
application calls up the PL/SQL procedure wt_container_init with the form
driver ID. This procedure checks for any authorization, creates the required
container(s) and calls up the relevant form with the settings specified in its
driver.
The call depends on the settings made in the PL/SQL
cartridge, as follows, and can be entered as a hyperlink:
| http://www.webag.de/pls/automat/wt_show_form.form_container_init?p_form_driver_id=xxxxx |
|
Illustration 9 –
Procedure call SUBMIT for form drivers |
The form_driver_id
is assigned uniquely to each form driver. It can be read in the settings of
the relevant form driver.
Processing Address Details from the Container
Address details can be transferred from the XML
container to a relational database scheme with the help of the XML Toolkit
from Oracle. Enterprise Web AG would also be pleased to conduct such projects
on site, as part of special training seminars. Should you be interested,
please do not hesitate to contact us (support@webag.com).
We look forward to hearing from you.
