How the pagination / navigation widget works

How the pagination / navigation widget works


In your application you probably display list of information. The information you are displaying can become longer than fits on the page and most of the time you want to use pagination to display all of the data.

OutSystems has a component for you to make it easy to for you to add this functionality to your application. It is called the “List_Navigation” widget that comes with the RichWidgets.

This article describes how to use it step by step for a better understanding of the widget.

Create the countries page without list navigation

I have a country entity which contains 227 countries. On the screen I want to display the id, name and region of the countries, sorted by the name of the country.

Step 1

In the preparation create an aggregate to fetch all the countries ordered by the name.

Step 2

On the screen place a table records widget, set the source record list of the table widget to the aggregate from step 1 and set the line count to 9999 to be sure all the countries are displayed. Add the columns row number, id, name and region to the table records.

Above the table the number of records in the aggregate is shown.

As a result the page shows all the records of the country entity in alphabetical order.

All the 227 records are in the aggregate and all of the records are on the screen as one long list.

Add paging / navigation to the screen

Now let’s use the “List_navigation” widget to display only 10 countries on the screen and give the user a control the loop through the countries.

Step 1

Reference the List_Navigation widget from the RichWidgets module.

Step 2

Set the line count of the table records widget to 10 so only 10 records are displayed on the screen.

Step 3

Add the List_navigation widgets to the screen and set the properties of the widget.

The Id of the widget display the data
The number of lines that will be shown in the data widget
The total rows that can be displayed
The maximum numbers of displayed page numbers
On notify action     
Screen action to be called when a button of the List_Navigation has been pressed

The filled in widget looks like

Please be aware the Count property of the GetCountries aggregate contains the number of all records of the aggregates while the length property contains the number of records that are actually fetched from the database and are in the aggregate itself.

The screen now looks like.

Yes! Our pagination is there but when nothing happens when pressing the buttons.
 Let’s fix that!

Step 4

I need to implement the OnNotifyListnavigation screen action when the user press a button.

In this function we need to requery the countries aggregate to get the records we need to display, refresh the expression to show the number of records in the aggregate and need to display the table records widget to actually show the new records. And of course we need to refresh the List_Navigation widget itself to display the changes.

Let’s try it again!

Bummer, it’s still not working. We need to fix even more!

The List_Navigation widgets is changing, it sow on which page you are, shows the previous button now. But the number of records in the aggregate does not change and also the data in the table records widget hasn’t changed.

Step 5

Let’s have a look at the properties of the table recorders widget.

There is a start index property here which tells the table records widget where to start displaying of the records that are in the source of the table records widget. For now it always start at the begin of the list!

I need to tell the table records widget where to start showing the records, on which page the users is!

We need a server action from the RichWidgets module for this which is called “List_Navigation_GetStartIndex”.

This sever action tells the current start index of the table records widget. Let’s use this in the start index property of the table records widget.

The first argument of this screen action is the runtime id of the table records widget and the second parameter tell it to remember the value of that in a session variable.

Please remark this function does not get the runtime id of the List_Navigation widget as the first parameter but the runtime id of the table record widget! Because the List_Navigation widget is connected to the table records widget through the ListWidgetId property of the list_navigation widget this is working!

And other magic is happening here! Because the aggregate GetCountries is connected to the table records widgets through the “Source Record List” property the aggregate now knows how many records must be fetched so the table records widgets can show the right records.

Let’s try it again.

Yes! The pagination is working!

Some tips and tricks

When the content of the source record list of the table records widgets changes the might be less records in the source than it’s to be displayed because of the current page. The user is on page 10 but there only records for 4 pages. At this point you need to reset the start index. This can be done with the sever action “List_Navigation_ResetStartIndex”.

The aggregate will need to fetch all the records up to the records that are actually displayed on the screen. If you have a list count of 10 and the user is on page 1.000 the aggregate must fetch 10 * 1000 = 10.000 record to display only the last 10. So the performance is decreasing when page numbers are increasing. You can use some advanced SQL technics here to avoid this problem but that’s out of scope of this article.

I hope you liked my explanation of the List_Navigation widget.

Hi Johan,

Nice explanation about paging & List_Navigation.



Thank you very much.