Search Pages

The most useful part of an address book is its search facility.  XPage offers a specific page type for searching.  In this section we will develop a page that allows the users to search the address book for specific contacts based on name, last name, phone number, address and email addresses.  In a search page, the developer should specify the attributes in which the user can search and they way the search is performed in each attribute.  The search result is finally displayed in a view page.  That is, every search page should specify a view page for showing the result of the search.  The output of the search page that we are going to design is shown in the following figure.

Search page in browser

The user can define the search criteria by specifying values for each one of the fields.  If more than one field is filled out, the generated conditional phrases are ANDed together.  The definition of this page is shown in the following figure.

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

<page type="search">
  <redirectto>contactlist</redirectto>
  <title>Search for Contacts</title>
  <icon>contactsearch.gif</icon>
  <fields>
    <field name="name" search="contact.name" caption="First Name" size="20" type="exact"/>
    <field name="lastname" search="contact.lastname" caption="Last Name" size="30" type="exact"/>
    <field name="phone" search="contact.phone" caption="Phone#" size="15" type="range"/>
    <field name="address" search="contact.address" caption="Address" size="30" type="partial"/>
    <hr/>
    <field name="email" search="email.email" caption="Email Address" size="50" type="exact"/>
  </fields>
</page>

Every input box is defined with a <field> tag.  For each <field> tag, the developer should provide the following attributes:

• name gives a unique identifier for the search box (used only in naming the form input variable)

• search specifies the attribute in which the entered value is searched

• caption is shown next to the input box

• size specifies the size of the input shown

• type defines the search type and can be one of the following: exact, partial or range

There is no query in the definition of this page.  As stated above, every search page depends on a view page to display its search results.  The <redirectto> tag specifies the name of the view page that can display the search results.  In this example the contactlist page has been introduced as the page that should display the result of search.  Referring to the definition of contactlist page, it is seen that in addition to the <querysource> tag, that page contains a <searchquerysource> tag which specifies contactsearch.xml as the name of the file containing the query statement.  This tag and the corresponding query are exactly defined for performing the search requested by the contactsearch page.  In fact this query belongs to the search page, however for some implementation considerations the query is defined in the view page.

When the user submits the information in the form, the search page constructs a conditional phrase based on the values provided by the user and the name of attributes provided in the page definition and sends it to the designated view page.  In the view page, this conditional phrase is appended to the where clause of the search query and the modified query is executed against the database.  The result is that those rows that match the criteria specified by the user are retrieved and displayed in the page, just like a normal view page.  However the view page is using the query of the search page instead of its  own query.

The trickiest part in designing a search page is defining the proper search query in the <searchquerysource> tag.  Since the view page will use this query to extract the rows from the database, it should include in its results every attribute that is displayed in the view page.  On the other hand the query should include every table and every attribute that are used in defining the search criteria.  These are the attributes that the user can search in them and appear in the search form.  When we want to search only in the attributes of a single table, there is no difference between the search query and the normal query of the view page.  However when we need to filter the search results based on the values of the relating rows in other tables, a properly modified search query should be defined.

In this example, since we need to search for contacts based on email addresses, the search query should join the contact and email tables.  This needs to be done because the search page may pass conditional phrases like email.email = "me@example.com"  to the view page and since the view page adds the phrase to the where clause of the search query, it needs to include the email table.  The query stored in contactemail.xml file is as follows:

SELECT DISTINCT contact.id, name, lastname, phone, address
FROM contact, email
WHERE email.contactid = contact.id

This query joins the contact and email tables; however it only selects the attributes of the contact table.  It is because the contactlist page is only expecting the attributes of the contact.  Also the query should be defined as DISTINCT so that every matching row is repeated only once.  If we omit the DISTINCT word, then every matching contact is repeated by the number of his/her email addresses.

If we enter "Mahjourian" in the last name field, the search page sends this phrase to the contactlist page:

(contact.lastname=’Mahjourian’)

The contactlist page then combines this expression with the defined query and constructs the following statement:

SELECT DISTINCT contact.id, name, lastname, phone, address
FROM contact, email
WHERE email.contactid = contact.id
AND (contact.lastname=’Mahjourian’)

Upon executing this query, a single row is returned from the database.  The search results page is displayed in the following figure.  Just like the normal view page, it is possible to follow the links to edit or delete the displayed row.

Search results page

The way the entered values are searched in the attributes of the underlying query is determined by the type attribute:

• exact means that the entered value should be exactly equal to the attribute value

• partial means that a row is selected for which the entered value is a substring of the attribute value

• range means that the page should display two input boxes allowing the user to limit the value of the attribute from one or two sides

In practice, it is not useful to search for phone numbers in a specific range.  The range type was used here just for the sake of an example.