Table of Contents

Introduction#

Search forms provide an easy way to perform searches on data in your application's database. There are two steps
  • composing the search form
  • displaying the search results

Search Forms#

Makumba search forms build on the familiar concepts of other Makumba forms, such as the <mak:newForm>, and help you to rapidly build your input mask. First, you need to specify the data definition you want to search in, and specify a name identifier, to which you can refer to in your result display page.

The form stub#

<mak:searchForm in="company.Employee" name="searchEmployee">
  ....
</mak:searchForm>

This just provides the stub of the form, to actually have the user select options or input search terms, you have to provide search criteria on which field(s) to search on:

Search criteria#

<mak:searchForm in="company.Employee" name="searchPerson">
  <mak:criterion fields="name"> ... </mak:criterion>
  <mak:criterion fields="projects"> ... </mak:criterion>  
</mak:searchForm>

This tells Makumba that you want to search for an Employee, and as a criterion you want to use the name field.

Input control rendering#

Finally, you need to tell Makumba how you want to render the input control, so let's extend the example a bit further: 
<mak:searchForm in="company.Employee" name="searchEmployee">
  <mak:criterion fields="name"> <mak:searchField /> </mak:criterion>
  <mak:criterion fields="projects"> <mak:searchField forceInputStyle="single" /> </mak:criterion>  
</mak:searchForm>

This tells Makumba that we want a standard input control for the name, and from the given data definition, it will render a input box. For the projects criterion, which is a set, Makumba would normally create a multiple-select box. However in this case, we want to select only one project, and thus we can force the input style to be a 'single' select.

The <mak:searchField> builds on top of the <mak:input, and accepts the attributes defined there. For more details on this, please see the <mak:searchField documentation.

Note

In the future, a <mak:criterion .. /> without a body might by default behave like having a single, empty <mak:searchField/> inside, and thus help you to make standard search forms even faster.

Range searches#

For certain input types (namely int, real and date) you can do range searches, i.e. provide a lower and upper bound in between which the value should match.

You can enable a range search by specifying this in the <mak:criterion> tag, and by providing two <mak:searchField>, one for the beginning, and one for the end of the range.

To search e.g. for the birthday of employees, you would build a form as: 

<mak:searchForm in="company.Employee" name="searchEmployee">
  <mak:criterion fields="birthdate" isRange="true">
    between <mak:searchField /> and <mak:searchField role="rangeEnd" /> 
  </mak:criterion>
</mak:criterion>  
</mak:searchForm>

Modifying pattern matching#

By default, Makumba will evaluate your search terms or search option selections as an exact equality match with the values in the database. For range matches, such as date or number ranges, the default match is "between inclusive", i.e. the comparison is true if the search value is in between the range boundaries, or equal to one of them.

You may want to modify this behaviour, which can be done by providing a matchMode attribute to the <mak:criterion>, e.g.: 

<mak:searchForm in="company.Employee" name="searchEmployee">
  <mak:criterion fields="name" matchMode="contains"> <mak:searchField /> </mak:criterion>
</mak:searchForm>

This will change the matching to any name that contains the search term.

If you want to let the user decide on how to do the matching, you can provide another input control by using <mak:matchMode>: 

<mak:searchForm in="company.Employee" name="searchEmployee">
  <mak:criterion fields="name"> <mak:matchMode matchModes="contains, equals, begins, ends"> <mak:searchField /> </mak:criterion>
</mak:searchForm>

This will show an input control that lets the user chose between the different matching modes. For the complete list of available attribute values, please refer to the <mak:matchMode> documentation.

Displaying Search Results#

Displaying results from the search is in principle equal to displaying results from any other database query. Thus, displaying results from a search form builds on the <mak:list> concept. The <mak:resultList> will automatically iterate over the results from a specified search form. Contrary to the <mak:list>, you do not need to provide a from and where section, but just specify the name of the search form to take the results from with the resultsFrom attribute.

The name of the object selected in the list is fixed to 'o', sub-sets get selected as 'o_subFieldName': 

<mak:resultList resultsFrom="searchEmployee">
  Name: <mak:value expr="o.name"/> <br/>
</mak:resultList>

Advanced result display#

When a search form is submitted, Makumba will respond with creating several attributes. If you want to do more advanced things in the search page, e.g. sorting of the parameters, you might need to access the pageContext attributes describing the search and the results. They are as follows:

Attribute name description
<searchFormName>Done Boolean, saying whether a search was performed (or this is the first time accessing the form). Can be used e.g. as <c:if test="${<searchFormName>Done}"/> Do something when the search was done </c:if>
<searchFormName>QueryString The query string containing the values for the form fields filled in in the search. Use this e.g. as <a href="searchPage.jsp?${<searchFormName>QueryString}&sortBy=name"> when you want to provide sorting by a specific field.
<searchFormName>VariableFrom The additional data definitions needed to perform the query, will be used by mak:resultList in the variableFrom=".." attribute.
<searchFormName>Where The filter conditions for the matching records, will be used by mak:resultList in the where=".." attribute.

Category Usage

Add Comment
« This page was last updated on February 27 2011