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"?>
<title>Add Email Address</title>
<field name="lastname" caption="Contact"
<field name="contactid" caption="Contact"
type="constant" value="pageparam" hidden="true"/>
<field name="email" caption="Email Address"
<field name="comment" caption="Comment" size="50"
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
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.
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
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.