Single-Row Insert Pages

Although XPage supports hybrid insert pages, it is possible to address all data entry needs of the applications by only using the single-row insert pages.  In this section we will develop the emailadd page, which is accessible by following the "Add New Email" link in the contactdetail page.  This page is used for adding a new email address and an associated comment to the information of a specific contact.  This is accomplished by adding a new row to the email table and linking it to the appropriate row in the contact table by inserting the correct value for the contactid attribute.  The definition of the emailadd page is as follows.

<?xml version="1.0" encoding="UTF-8"?>

<page type="insert">
  <title>Add Email Address</title>
  <icon>emailinsert.gif</icon>
  <top>
    <targettable>email</targettable>
    <primarykey>id</primarykey>
    <querysource>xmlquery/contact.xml</querysource>
    <pageparam>id</pageparam>
    <fields>
      <field name="lastname" caption="Contact" type="display"/>
      <field name="contactid" caption="Contact" type="constant" value="pageparam" hidden="true"/>
      <field name="email" caption="Email Address" size="50"/>
      <field name="comment" caption="Comment" size="50" optional="true"/>
    </fields>
  </top>
</page>

There are two input fields available to the user in this page.  The third <field> tag defines the email input field and the fourth tag defines the optional comment input field.  The value of the contactid attribute is determined from the value of the parameter which is passed to the page.  It is specified in the contactdetail page that the "Add New Email" link sends the value of the id attribute for the selected contact to this page.  So a constant input is devised in this page to receive this parameter and insert it in the contactid attribute.  In constant fields, the value attribute determines the value of the field.  In this page, the value attribute is set to "pageparam" for the contactid field.  The normal behavior is that this value is interpreted as a literal string, however "pageparam" means that the value of the parameter passed to the page should be assigned to the input.  So when the form is being constructed, the value of the id attribute for the contact--for which the email address is inserted--is assigned to the contactid input field.  The field is not shown to the user, as it is set hidden in the definition.

This page is a single-row insert page, so it only includes a <top> section.  The <targettable> tag specifies that the email table is the target table for the page.  Meanwhile the page definition also includes a <querysource> tag, just like the view pages.  This is related to another useful feature of insert pages that enables them to display auxiliary information inside the forms.  That is, in addition to receiving information from the user, insert pages can execute a query (usually returning a single row) against the database and display some of the returned attribute values inside the data entry form as auxiliary information.  This extra information has no effect on data collection and insertion process and it is only provided to help the end user.  For example in this page, from the received parameter it is possible to identify the contact for which the email address is inserted.  So as the developer we have decided to retrieve the name of the contact from the database and display it to the user beside the data entry fields.  The following figure shows the emailadd page in a browser.

Add Email Address page in browser

Displaying the contact name is accomplished by the first <field> tag in the XML definition.  For this tag, the type attribute is set to "display".  This means that the <field> tag is not meant to produce any data entry element, rather it is used to display the value of some attribute from the result of the query defined in <querysource>.  The name attribute denotes the name of the query attribute which should be displayed.  Just like the view pages, the <pageparam> tag is incorporated when executing the query to retrieve the appropriate row.

Instead of requiring the user to follow the Add New Email link for adding a new email address, we could have designed a stand-alone page which allows the user to specify the associated contact for the new email address on the form itself.  In this case, a combo input is needed to let the user select the contact for which the email address should be inserted.  This page has been implemented in the demo site.