|
After view pages, the most important pages in a data-intensive
application are the insert pages. Meanwhile, for some reasons the insert
pages are among the most complicated pages of these applications. Because
of the existence of data entry forms, insert pages demand for more interaction. Also we need to devise various data entry elements in the forms
and we need to verify the data that the user inputs in the forms for correctness
and consistency.
The syntax used for describing insert pages is similar to the view
pages. However, in an insert page we need to specify the name of the
target table for storing the submitted data, while in view pages, a database
query is provided for retrieving information. Like view pages, the
insert pages can be of different types. In single-row insert pages the
user enters values for the attributes of a single row.
Also it is possible to design insert pages that input the attributes of
several rows and more importantly we can use hybrid insert pages to
simultaneously input information for two tables which have a one-to-many
relationship. Usually the insert pages are of hybrid or single-row types.
In this section we discuss the features of the insert pages while designing the
pages of the address book application.
The contactinsert page is used to add a new contact to the address
book. This page allows the user to input contact's personal information as
well as his/her email addresses.
Since it is possible to add new email addresses for the contacts by following
the "Add New Email" link in the contactdetail page, we could have decided to
design an insert page which only receives the personal information for the
contact and then require the user to use the above mentioned page for adding the email addresses.
However it is much more convenient for the user to do both tasks in a single
step.
So we need an insert page that inserts the personal information of the contact in the
contact table and his/her email addresses in the email table. It is useful
to view the final generated page before providing the XML definition:
Insert contact
page in browser
It is seen that every required attribute for the two tables is
included in the data entry form. The id attributes were defined as serial
fields when creating the tables and their values are automatically inserted by
the DBMS software when the rows are inserted. (We will see later that it is
possible to simulate the auto-increment fields in XPage without using the serial
fields.) The XML definition for the contactinsert page is displayed in the
following figure.
<?xml version="1.0" encoding="UTF-8"?>
<page type="insert">
<title>Insert New Contact</title>
<icon>contactinsert.gif</icon>
<top>
<targettable>contact</targettable>
<primarykey>id</primarykey>
<fields>
<field name="name" caption="First Name"
size="20"/>
<field name="lastname" caption="Last Name"
size="30"/>
<field name="phone" caption="Phone#" size="15"/>
<field type="text" name="address"
caption="Address" size="50"/>
</fields>
<exportcombo>
<field>lastname</field>
<field>name</field>
</exportcombo>
</top>
<body optional="true" rows="5">
<targettable>email</targettable>
<foreignkey>contactid</foreignkey>
<fields>
<field name="email" caption="Email Address"
size="50"/>
<field name="comment" caption="Comment" size="50"
optional="true"/>
</fields>
</body>
</page>
The type attribute of the <page> tag is equal to "insert" and it denotes that this is an insert page. The <title> and <icon> tags are used
like the view pages. Since this is a hybrid page, it includes two separate
<top> and <body> sections. As stated earlier, each section needs
to define a target table for inserting the form data. The name of
the target table is provided in the <targettable> tag. The <primarykey>
tag in the <top> section and the <foreignkey> tag in the <body> section are used
to define the relationship between the the two tables. For the insert
pages that include only the <top> section or the <body> section, it is not necessary to
define the <primarykey> or <foreignkey> tags. The <primarykey> tag
specifies the name of the primary
key attribute in the table of the <top> section (the "one" side of the
relationship) and the <foreignkey> tag specifies the name of the foreign key
attribute in the table of the <body> section (the "many" side of the
relationship). In the contactinsert page the "id" and "contactid" attributes
are defined as the primary key and foreign key of the contact and email tables,
respectively.
Definition of the <body> tag read: <body optional="true"
rows="5">. Unlike view page where the number of rows displayed in the
<body> section is determined by the number of rows returned from executing the query, in insert pages we need to explicitly specify the maximum number of rows that the user can
fill out in the body of the form. The optional="true" expression means that the user is not
required to fill out any of the rows. This property affects the
operation of the form verification facility, which is introduced shortly.
Upon submission of the form by the user, the tool inserts the
values input in the header of the form in the <top> table. Also based on
the number of rows that the user has filled out in the body of the form, it
inserts the necessary rows in the <body> table. For these rows, the value of the foreign
key attribute is set to the value of the primary key attribute of the <top>
table. Inserting rows is accomplished by dynamically constructing INSERT queries from
the values provided in the form and the names of the attributes provided in the
describing XML document and submitting them to the database. The tool performs
all necessary insert operations inside a transaction, so that if any error occurs the
previously-submitted queries are roll-backed.
In the definition of an insert page, the only valid tag that can appear inside the
<fields> section is the <field> tag. Every <field> tag corresponds to
one
data entry field in the generated form. It is not meaningful to use the <cfield> and <link> tags
in insert pages. The developer should specify the following attributes for every <field> tag:
-
"name" specifies the name of the attribute which receives the
value in the target table
-
"caption" is used to specify the caption of the input field
-
"size" denotes the size of the single-line and multi-line text
boxes
-
"type" specifies the type of data entry element used
The caption attribute is used in the header of the columns or to
the left of the data entry fields. The insert pages support different
data entry elements. For example in this page a multi-line text input has
been used for receiving the value of the address attribute, which is of text
type. The following list shows the currently supported data entry elements
and the corresponding values for the type attribute:
-
(default) single-line text box
-
text: multi-line text box
-
constant: constant-valued field
-
password: password field
-
combo: drop-down input box
-
seed: input whose default value is retrieved from execution of a
query
In the address book application, we have used only the first two
types. Examples on usage of the other types can be found in the demo site.
Based on the type of the fields, it may be necessary to include other attributes
in the definition of the <field> tags.
The constant fields are used for
generating contact data entry fields. These fields appear as normal text
boxes on the form, but the user can not change their values.
Contact fields are usually defined as hidden so that they are not displayed on
the form at all. But the combo and seed fields
are more powerful. Combo fields are used when we want to input the foreign key attributes.
If there is a foreign key among the
attributes of a table and we want to insert a new row in that table, then we should
provide the value of the primary key attribute
for some row in the referenced table as the value of the foreign key attribute.
Combo fields let the user do that by displaying all rows of the
referenced table in a drop-down box. By selecting any of the
rows, the value of the primary key attribute of the row is assigned as the value
of the input on the form and it is finally inserted in the database when the form
is submitted.
In addition to the name, caption, size and type attributes, there
are some optional attributes which can be used to change the behavior of the
insert pages for each of the fields. For example in the contactinsert
page, the <field> tag corresponding to the comment attribute includes an
optional="true" expression. It means that the user is not required to
enter values in this field. It is also possible to set some
fields hidden by adding the hidden="true" expression.
XPage features a form verification facility which automatically
validates the insert and edit forms upon submission. It checks to see if all non-optional
fields have been filled out; if there is at least one row in the body of a
form which is not optional and if for every filled row in the body, every
non-optional field has been filled out. If some information is missing,
the data is not inserted in the database and the form is redisplayed to the user,
while all the values that the user has entered are preserved. The
following two figures show two examples of incomplete forms.
Form
verification: Missing required attribute
Form
verification: Incomplete row
It is explained in subsequent sections that every insert page
can include two <code> sections named "onload" and "onsubmit". These
functions are defined in a programming language and can be used for complex
computations or for extending/overriding the normal behavior of the page. The onload code can be used to initialize some input
fields in the form or to totally cancel
the display of the insert page. The onsubmit code can be used for further
verification of the data input in the form; to submit additional queries to the
database when the rows are inserted or to implement a completely custom insert
procedure for inserting the data in the tables. These mechanism are
demonstrated in the applications of the demo site. |
