Skip to end of metadata
Go to start of metadata

To deal with large amounts of data, we use the jquery library tablesorter with the Pager with Filter plugins.

Using these plugins, you set which column(s) in the table you would like to search on, and specify which columns are sorted. The actual searches and sorting are done on the server.

Behaviour and Server Notes

Searches need to be case insensitive and partial matches. So if the user enters "fio mal" it will match "fio", "Fiona Malikoff", "Malcolm Fraser" and "OFFIO". Split the search phrase into tokens on whitespace and then and look for each of them in first name, last name and (if appropriate) login separately.

Examples of this may be found in FindUserLessonsAction.getUserSet() and LearnerProgressDAO.buildLearnersByLessonQuery()

When the paging/search is done on the server, the parameters are passed through to the DAO layer and used as part of the Hibernate query. This reduces the number of Java objects required to be built by Hibernate. Two calls are required - one to get the data for the current page and one to get the overall number of matches (for the Page X out of Y indicator).

The input string from the user should be escaped using StringEscapeUtils.escapeSql(searchString) before building the query.

A typical search part of the query would be: " o.firstname LIKE CONCAT('%', :searchString, '%')". This does a case insensitive search using a bound variable.

When a search is done, the results are paged just the same as if a search wasn't done.

Sorting and Searching Code Example

In the following code, the table can be sorted on the first column (column[0]) or the second column (column[1]) and these parameters contain either 0 (sort ascending) or 1 (sort descending). The search/filter string from the first column comes through as fcol[0]. If it was possible to filter on the second column then it would come through as fcol[1].

Still to do: Filtering out characters?

UI Notes

To use the search, make sure you are including all the following Javascript files and stylesheets. The widgets file is needed for the searching and for the bootstrap theme.

The following code is in the main stylesheets for LAMS. This should ensure that the disabled search boxes (that appear in columns that do not have a search, when search is enabled) are not shown.

Typical tablesorter definition. Columns start at index 0, so the entry in header for "1" refers to the second column on the screen. In the example below you can search/filter and sort on the first column, sort only on the second column, and neither filter or sort on the third column.

The "uitheme" widget is needed for the bootstrap theme, as is the headerTemplate entry. If you omit the headerTemplate entry, you won't get the sort icons in the header.

This uses the Bootstrap theme (theme-bootstrap.css) with the striped lines widget ("zebra") and the searching widget ("filter"). It sorts and searches on the first column (column 0) but not the second or third columns.

The hint text "Search..." which appears in the search box is internationalized. A typical definition is:

The default search delay is set to 700ms, as the default (300ms) is too short and triggers searches before user has finished typing their search text.

Next define the pager javascript.

The URL specified in ajaxURL needs the parameters &page={page}&size={size} for paging.

The URL specified in ajaxURL needs the parameters &{sortList:column} for sorting.

The URL specified in ajaxURL needs the parameter &{filterList:fcol} for searching. This translates to a fcol[<columnnumber>]=<search value> on the URL.

Finally in the page itself, use the <lams:TSTable> tag to define the table.

Attributes:

  • numColumns: Required. Number of columns in the table - needed so that the pager in the footer extends across the table.
  • data-session-id: Optional. Used for tables where an id is required for the URL call.
  • tableClass: Optional. Defaults to "tablesorter". Only include if you need a different class for your table.
  • pagerClass: Optional. Defaults to "ts-pager". Only include if you need a different class for your pager.
  • test: Optional. Set this to anything and "2" is added as a page size selection. Handy for testing the paging. Do not include this attribute in a release version.

The body of the tag is the header row for the table. Do not include the table row tags - they are built into the tag.

  • No labels