Display a List of Search Results¶

Class diagram¶

To clarify the placement of the classes and tag files provided by the framework, the classes and JSP of the business application that performs user search are included in the structure.

The application programmer can implement paging without implementing the details since the classes provided by the framework and the tag files provided by the sample perform the processing required for paging.

DbAccessSupport class¶

The DbAccessSupport class is a support class that simply implements the database access process provided by the database access function.

DbAccessSupport provides a search method that executes a search for a list search. The search method receives the SQL_ID and ListSearchInfo, and performs the following processes.

• Obtains the number of search results from the specified SQL_ID and ListSearchInfo.
• Throws TooManyResultException when the number of search results exceeds the maximum number.
• Executes the search and returns the search results when the number of search results does not exceed the maximum number. Sets the number of search results in ListSearchInfo that is specified by the argument.

The SQL statement specified by the SQL_ID specifies the SQL statement (i.e. the SELECT statement) that performs the search based on the search conditions required for business. The framework acquires the number of search results based on the SQL statement that executes the search, and to execute the search by specifying the start position of the search results and the number of results obtained.

TooManyResultException retains the maximum number of search results (upper limit) and the (actual) number of search results obtained. To configure the upper limit for the number of search results, see Default settings for the search result list display function.

An implementation example for the search process using the search method is shown below.

// Acquire the validated search conditions
W11AC01SearchForm condition = ...;

// Execute search
SqlResultSet searchResult = null;
try {

    // Search process with paging.
    // "SELECT_USER_BY_CONDITION" is the SQL_ID for the SELECT statement that performs user search.
    searchResult = search("SELECT_USER_BY_CONDITION", condition);

} catch (TooManyResultException e) {

    // Error handling when the number of search results exceeds the maximum number.
    // TooManyResultException provides the maximum number of search results (upper limit) and the actual number of search results.
    // "MSG00024" is the message ID for the message "Search results has exceeded the maximum number of ({0} records)".
    throw new ApplicationException(
        MessageUtil.createMessage(MessageLevel.ERROR, "MSG00024", e.getMaxResultCount()));
}

Main attributes of the listSearchResult tag¶

The main attributes of the listSearchResult tag are shown below. For more information on all the attributes, see listSearchResult tag.

If the search result specified by the resultSetName attribute does not exist in the request scope, the listSearchResult tag will not output anything. This corresponds to the case where the initial display of the search screen does not output anything.

Search result list¶

The number of search results is displayed when true (default is true) is specified in the useResultCount attribute and the search results exist in the request scope. By default, the number of search results is output in the following format.

Search results <%-- resultCount property of ListSearchInfo --%>Record

To change the default format, specify the JSP fragment in the resultCountFragment attribute. An example of specifying the resultCountFragment attribute is shown below. Since the JSP fragment is called from a custom tag for evaluation, the ListSearchInfo object can be accessed using the name specified in the listSearchInfoName attribute.

<nbs:listSearchResult listSearchInfoName="11AC_W11AC01"
                   searchUri="/action/ss11AC/W11AC01Action/RW11AC0102"
                   resultSetName="searchResult">

   <%-- Specify the JSP fragment in the resultCountFragment attribute. --%>
   <jsp:attribute name="resultCountFragment">
   [Search results <n:write name="searchCondition.resultCount" />page]
   </jsp:attribute>

   <%-- Other attributes are omitted. --%>

</nbs:listSearchResult>

The format for the number of search results after the specification mentioned above is as follows.

[Search results <%-- resultCount property of ListSearchInfo --%> page]

Paging¶

Paging is displayed when the usePaging attribute is specified as true (the default is true). The paging screen elements are shown below. Paging consists of the current page number and the submit elements for moving the page.

The entire paging is displayed when the number of search results is 1 or more. Assuming that the entire paging is displayed, the paging screen elements are as shown below.

The typical attributes that can be specified by the paging screen elements are as follows. For more information on all the attributes, see listSearchResult tag.

• Whether or not each screen element can be used
• Label for each screen element (such as first, previous, next, last)

• Current page number that is changed by the JSP fragment
• Page numbers that cannot be changed because they use the page number for the label

• Tags used for each submit element (either n:submitLink, n:submit, n:button)

Search conditions when paging

The search conditions when paging uses conditions from the previous search (the conditions from the time when the currently displayed search results were obtained). This means that when paging is performed after changing the search conditions, the changed values of the search condition are discarded.

The search conditions can be maintained using a windowscope, similar to when input values are carried between screens. Therefore, when search conditions and a list of search results are arranged on a single screen, it is necessary to implement the forms for search conditions and list of search results separately.

What to do when search results are reduced when using paging

This section describes what to do when the search results are reduced due to other user operations while switching the search result page with each paging submit element.

This framework performs a search based on the specified page number and displays each paging screen element. The following is an example of the paging operation when the number of search results is reduced.

As a prerequisite, the number of acquired search results (number displayed per page) is 20 results.

First, assume that a search is performed and the search results are 44 results. Below is the paging display after the third page is selected.

The paging display and description of the contents displayed when the second page (or the previous page) is selected and the number of search results is reduced to 10 is described next. Each paging screen element is displayed as a search result for the second page.

Since the current page number and the submit element correspond to each other, it is possible to move to the search results page by selecting the submit element without it becoming inoperable. (Of course, if you perform a search again from the search form, the search results will be from the first page.)

The paging display after selecting “Previous” is shown next. The correspondence between the current page number and the total number of pages returns to normal.

Search result¶

The screen elements of the search result are shown below. The search result consists of a header row that displays column headings, and a body row that displays row data.

The search results are always displayed when they are in the request scope. When the search result is 0, only the header row is displayed.

The header row and body row are specified in the headerRowFragment attribute and bodyRowFragment attributes in the JSP fragment. The JSP fragment in the body row is called and evaluated in the search result loop (c:forEach tag of JSTL). Hence, the following attributes are provided to access the row data (var attribute of the c:forEach tag) and status (status attribute of the c:forEach tag) in the JSP fragment of the body row.

<n:set var="rowCount" value="${status.count}" />
<n:write name="rowCount" />

In addition, the following attributes are provided in the body row that specify the class attribute for changing the background color of every other row.

An example of user search specifications is shown below. The tag file prefix should be nbs.

<nbs:listSearchResult listSearchInfoName="11AC_W11AC01"
                   searchUri="/action/ss11AC/W11AC01Action/RW11AC0102"
                   resultSetName="searchResult">

   <%-- Specification of JSP fragment for the header row. --%>

   <jsp:attribute name="headerRowFragment">

       <tr>

           <th>Login ID</th>
           <th> Kanji name</th>
           <th> Kana name</th>
           <th>Group </th>
           <th>Extension number </th>
           <th>Email address</th>

       </tr>

   </jsp:attribute>

   <%-- Specify the JSP fragment for the body row. --%>

   <jsp:attribute name="bodyRowFragment">

       <%-- Access the class attribute using the default variable name "oddEvenCss". --%>

       <tr class="<n:write name='oddEvenCss' />">

           <%-- Access the row data using the default variable name "row". --%>

           <td>[<n:write name="count" />]<br/>[<n:write name="rowCount" />]<br/><n:write name="row.loginId" /></td>
           <td><n:write name="row.kanjiName" /></td>
           <td><n:write name="row.kanaName" /></td>
           <td><n:write name="row.ugroupId" />:<n:write name="row.ugroupName" /></td>
           <td><n:write name="row.extensionNumberBuilding" />-<n:write name="row.extensionNumberPersonal" /></td>
           <td><n:write name="row.mailAddress" /></td>

       </tr>

   </jsp:attribute>

</nbs:listSearchResult>

The search results after the above specifications are shown below.

How to implement the search process¶

To sort the search results, define an SQL statement using the variable ORDER BY syntax. The following is an example of an SQL statement using variable ORDER BY syntax.

In the SQL statement below, the variable ORDER BY clause is used to sort kanji names and kana names. To determine which ORDER BY to use, the value obtained from the sortId field of the search condition object is used, as described in $sort (sortId).For example, if the sortId field of the search condition object is kanaName_asc, the ORDER BY clause is converted to “ORDER BY USR.KANA_NAME, SA.LOGIN_ID”.

-- SQL statement using variable ORDER BY syntax
SELECT

   -- Omitted

FROM

   -- Omitted

WHERE

   -- Omitted

$sort (sortId) {
   (kanjiName_asc  USR.KANJI_NAME, SA.LOGIN_ID)
   (kanjiName_desc USR.KANJI_NAME DESC, SA.LOGIN_ID)
   (kanaName_asc   USR.KANA_NAME, SA.LOGIN_ID)
   (kanaName_desc  USR.KANA_NAME DESC, SA.LOGIN_ID) }

The ListSearchInfo class defines sortId property to support sorting. The sortId property is included in the input validation when sorting the search results. An implementation example of a class (W11AC01SearchForm) that inherits from ListSearchInfo is shown below.

// Class that inherits from ListSearchInfo.
public class W11AC01SearchForm extends ListSearchInfo {

    // Property definition of the search condition is omitted.

    // Constructors corresponding to the validation function.
    public W11AC01SearchForm(Map<String, Object> params) {

       // Property configuration of the search condition is omitted.

       // Sets the sortId property of ListSearchInfo.
       setSortId((String) params.get("sortId"));
    }

    // Override and add an annotation for input validation.
    @PropertyName("Sort ID")
    @Required
    public void setSortId(String sortId) {
        super.setSortId(sortId);
    }

    /** Properties to be validated (search condition properties are omitted) */
    private static final String[] SEARCH_COND_PROPS = new String[] { ..., "sortId"};

    // Override and return the property name of the search condition.
    // Usually the same as the property under validation.
    // Used by each paging submit element when submitting search conditions.
    public String[] getSearchConditionProps() {
        return SEARCH_COND_PROPS;
    }
}

listSearchSortSubmit tag¶

The listSearchSortSubmit tag outputs submit elements for sorting.

The required attributes and typical attributes of the listSearchSortSubmit tag are shown below. For a list of all the attributes that can be specified with the listSearchSortSubmit tag, see listSearchSortSubmit tag.

An implementation example of JSP using the listSearchSortSubmit tag is shown below. The tag file prefix should be nbs.

<nbs:listSearchResult listSearchInfoName="11AC_W11AC01"
                   searchUri="/action/ss11AC/W11AC01Action/RW11AC0102"
                   resultSetName="searchResult"
                   usePageNumberSubmit="true"
                   useLastSubmit="true">

   <jsp:attribute name="headerRowFragment">

       <tr>

           <%-- Columns except for Kanji name are omitted. --%>

           <th>

               <%-- Set Kanji name as a link for sorting.--%>
               <%-- Specify sort ID for ascending (kanjiName_asc) and descending (kanjiName_desc) according to the SQL statement. --%>

               <nbs:listSearchSortSubmit ascSortId="kanjiName_asc" descSortId="kanjiName_desc"
                                       label="Kanji name" uri="/action/ss11AC/W11AC01Action/RW11AC0102"
                                       name="kanjiNameSort" listSearchInfoName="11AC_W11AC01" />

           </th>

       </tr>

   </jsp:attribute>

   <jsp:attribute name="bodyRowFragment">

       <%-- Omitted --%>

   </jsp:attribute>

</nbs:listSearchResult>

The sort submit elements executes the search using the search conditions when searching from the search form. Similar to search conditions when using paging, use a window scope to maintain the search conditions.

The sort submit elements alway search the first page (page number: 1). This is because if the sorting is changed, the page number before the search becomes a relative position to the different order and not a meaningful page position after the search.

How the listSearchSortSubmit tag functions according to the current sort status

The listSearchSortSubmit tag determines the following values according to the current sort status. The current sort status is the sort ID used for the search.

• Sort ID to be sent as a request when a submit element is selected
• CSS class specified in the submit element according to ascending or descending order

This section describes the operation of the listSearchSortSubmit tag on the basis of the following implementation example.

<%-- Set Kanji name as a link for sorting.--%>
<%-- Specify sort ID for ascending (kanjiName_asc) and descending (kanjiName_desc) according to the SQL statement. --%>

<nbs:listSearchSortSubmit ascSortId="kanjiName_asc" descSortId="kanjiName_desc"
                         label="Kanji name" uri="/action/ss11AC/W11AC01Action/RW11AC0102"
                         name="kanjiNameSort" listSearchInfoName="11AC_W11AC01" />

Implementation example of CSS according to ascending or descending order

CSS is used to display an image that clearly indicates the ascending or descending order of the links for sorting, such as a screen image. An implementation example of CSS is shown below. It is assumed that the image file is placed in a location that can be referenced from the CSS file, and the CSS class name is defined with the default name.

/*
 * Configuration for sortCss attribute.
 * CSS class name of the sortCss attribute is always output.
 */
a.nablarch_sort {
    padding-right: 15px;
    background-position: 100% 0%;
    background-repeat: no-repeat;
}

/*
 * Configuration for ascCss attribute.
 * CSS class name of the ascCss attribute is output only when the submit elements are selected and are in ascending order.
 */
a.nablarch_asc {
    background-image: url("../img/asc.jpg");
}

/*
 * Configuration for descCss attribute.
 * CSS class name of the descCss attribute is output only when the submit elements are selected and are in descending order.
 */
a.nablarch_desc {
    background-image: url("../img/desc.jpg");
}

Place the tag file in the business application¶

Place the listSearchResult package in the business application as follows.

Copy from

META-INF/tags/listSearchResult

Copy to

/WEB-INF/tags directory of the business application

Revise the prefix in the tag file¶

In the sample implementation, “nbs” is added to the prefix in the tag file.Revise the prefix definition and prefix according to the location of the business application. The contents before and after the revision are displayed on the assumption that the file is placed in /WEB-INF/tags/listSearchResult.

Before revision

Prefix definition:

<%@ taglib prefix="nbs" uri="http://tis.co.jp/nablarch-biz-sample" %>

Prefix:

nbs

After revision

Prefix definition:

<%@ taglib prefix="listSearchResult" tagdir="/WEB-INF/tags/listSearchResult" %>

Prefix:

listSearchResult

listSearchResult tag¶

The listSearchResult tag dsiplays attributes for each screen element.

<n:set var="rowCount" value="${status.count}" />
<n:write name="rowCount" />

listSearchSortSubmit tag¶