About XPage
How It Works
A Case Study
View Pages
      Multi-Row
      Single-Row
      Hybrid
Insert Pages
      Hybrid
      Single-Row
Edit Pages
Search Pages
Delete Pages
      Single-Row
      Hybrid
Overall Features
      Page Features
Engineer's View
      System Catalog
      Page Types
      View Pages
      Insert Pages
      Edit Pages
      Search Pages
      Delete Pages

SourceForge Logo

 

Insert Pages

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.

Hybrid Insert Pages

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.