You can add page-based navigation to an OCLps seeker result so users can work through large database search results without loading every matching object; this page is for ViewModel authors configuring a multi-variable seeker.
What search-result paging does
A seeker runs its search expression against persistence storage using OCLps, rather than instantiating every matching object in memory. Paging divides that result into pages and lets the user choose which page to fetch.
When paging is enabled, the seeker:
- Executes a
select count(*)query to determine how many database rows match the search. - Stores that total in
vSeekerResultCount. - Uses
vSeekerPageLengthas the requested number of rows per page. - Calculates the number of available pages in
vSeekerPageCount. - Fetches the page identified by
vSeekerPage.
For example, if a search finds 245 persons and vSeekerPageLength is 25, the seeker exposes 10 pages. Set vSeekerPage to 1 to fetch the first page, or 2 to fetch the second page.
Configure a paged seeker
Use the multi-variable seeker configuration described in Seeker view. Paging is switched on by defining the paging variables that the seeker recognizes.
- Create or open the ViewModel that contains your search expressions and
vSeekerResult. See Searching for the seeker structure. - Define these variables in the seeker context:
| Variable | Purpose | How it is used |
|---|---|---|
vSeekerResultCount
|
Total number of matching rows | The seeker assigns the count returned by its database count query. |
vSeekerPageLength
|
Page size | Set this to the number of rows you want on each page. You can also expose it to the user when the page size should be selectable. |
vSeekerPageCount
|
Number of pages available | The seeker calculates this from the result count and page length. |
vSeekerPage
|
Page to retrieve | Set this before running the search. Valid pages are 1 through vSeekerPageCount.
|
- Set
vSeekerPageLengthto a suitable page size. For example, set it to 25 when the result grid should show 25 rows at a time. - Set
vSeekerPageto the page the user requests, such as 1 for the initial search. - Run the seeker. It updates the count and page-count variables and populates
vSeekerResultwith the selected page. - When the user moves to another page, update
vSeekerPageand run the seeker again.
The conceptual page-count calculation is vSeekerResultCount / vSeekerPageLength. Treat vSeekerPageCount as the value supplied by the seeker and keep vSeekerPage within its available range.
Worked example
Assume a customer seeker returns 87 matching customers.
| Setting or result | Value |
|---|---|
vSeekerPageLength
|
20 |
vSeekerResultCount after search
|
87 |
vSeekerPageCount
|
5 |
| First request | Set vSeekerPage to 1; retrieve the first 20 customers.
|
| Later request | Set vSeekerPage to 5; retrieve the final page.
|
Mark the result grid
The framework needs to know which grid displays the seeker results. Add the tagged value IsSeekerResultGrid=true to the Nesting that supplies the result grid.
AutoForms-generated seekers add this configuration. If you build the seeker UI yourself, add the tagged value to the correct grid nesting; otherwise, the generated paging UI cannot identify the search-result grid.
MaxFetch and paging
MaxFetch controls the maximum number of records returned by a seeker. It is a tagged value and is independent of the paging variables.
If you do not use MaxFetch, the default maximum is 20 records. MaxFetch does not require vSeekerResultCount, vSeekerPageLength, vSeekerPageCount, or vSeekerPage.
Use paging when users must navigate a larger result set page by page. Use MaxFetch when you must cap the number of returned records. Do not assume that client-side sorting of the rows currently displayed will sort the complete search result.
Ordering and partial results
Paging means that only part of the complete result set is loaded. Therefore, a change in sort order must rerun the search in the database; sorting only the rows on the current page does not produce the correct ordering for all matching rows. This applies to filtering as well when it is performed server-side. For the underlying distinction between search, filtering, ordering, and partial result sets, see Tables, search and ordering.
For example, a search may find more than 1,000 persons named Adam while page 1 displays only 25 of them. Sorting those 25 rows by last name cannot show the first 25 last names across all matching Adams. Rerun the seeker with the requested database ordering instead.
Client availability
Generated paging UI is available in the WPF client and the Angular Turnkey client. AutoForms seekers use the required seeker and result-grid conventions.
Related seeker behavior
A seeker can contain multiple search expressions. The seeker evaluates available expressions to find results, and the expression order affects which search is used. Paging applies to the result set produced by that seeker search; it does not replace search-expression design. See OCLOperators Search and Seeker view.