Database Scroller Library

After selecting data from the database comes the problem of what to do if it is too much for a User to read at once. You could send it all to the Browser and let the User scroll the Web Page, or you could devise a method that breaks the data up into multiple Web Pages, with a pre-selected number of records per page view. This second approach is what the Scroller Library does for you.

To use the Scroller Library, insert the following statement at the top of your page:

< include name="dbs.hei" />

A simple Scroller Application consists of two parts. The first part executes a query and stores the resulting relation in the Session Variable se.Scroller as follows:

<dbsQuery se.Scroller> select * from guestbook </dbsQuery>

The second part is the Scroller itself, an Environment Tag that passes the data in se.Scroller to other Tags for proper formatting and display. Here is an example:

<dbsScroller se.Scroller> <h2> Here is the search Result </h2> <table border> <dbsTableHead se.Scroller> <dbsTableBody se.Scroller> </table> <p> <dbsControlLine se.Scroller> </dbsScroller>

The <dbsTableHead> Tag creates a table headline containing all the field names. The <dbsTableBody> Tag creates a separate table row for each record to be display. Finally, <dbsControlLine> shows first, prev, next, and last buttons, as well as a Scroll Bar.

An application should execute the <dbsQuery> Tag immediately after the User has submitted a query (see Query Forms for information on how complex queries can be created with forms). The Scroll Box created by <dbaScroller> shows the result of this query one page at a time. The User can click on the Scroll Buttons to get to the previous, first, or last page, or alternatively, on a page number to directly go to a particular page.

The Scroller can be easily customized to fit a wide range of situations. Rows do not necessarily have to be shown in Table Format. Other formats are possible and you can select what information to show for each row. It is even possible to read additional information per row from the database. The Scroll Buttons and the Scroll Bar can be customized, as well as the maximum number of rows to display per page.

The Scroller uses Session Mode and keeps all data returned by a query in Session Memory. Therefore, the User can branch off to other pages and come back later to continue scrolling through the data without having to re-submit or re-execute the query. Also, Scrollers with a different layout can be used to display the same data. The Scroller data should be deleted by se.Scroller=null when it is no longer needed. As long as the Scroller data is empty, the Scroller simply disappears.

dbs Tags

< dbsQuery *dbsName max=200 pagesize=5 > ... </dbsQuery>

The body of the <dbsQuery> Environment Tag (i.e. the portion represented by the "..." above) must contain a valid SQL query. This query is evaluated and the result assigned to the Scroller. The dbsName parameter must be a Session Variable (e.g. - se.Scroller). The max parameter specifies the maximum number of rows to read from the database, and pagesize is number of records the Scroller shows per page.

If you are using <dbsQuery> and on the same page, remember to make sure that the <dbsQuery> Tag is executed only the first time the User has submitted a query.

< dbsScroller dbsName pagesize=null> ... </dbsScroller>

This Environment Tag displays the Scroller specified by the dbsName parameter. It must be the same name as given in the preceding <dbsQuery>. If dbsName contains no data (i.e. it has a null value), then nothing will be displayed. If pagesize is given, then the current size is updated to reflect the new value, otherwise it stays the same.

The Scroller will initially display the first page. If the User clicks on a Scroll Button, the Scroller will fetch the appropriate data and display a new page.

Inside the Tag, the formatting of the Scroll Box must be defined. Most of the following Tags are used for this purpose.

< dbsLine dbsName *r />

The inner part of the <dbsLine> Environment is called once for each row to be displayed. The r parameter is an output parameter containing the value of the current row.

Therefore, you describe how each row should be formatted from within the <dbsLine> Environment Tag.

< dbsTableLine dbsName r />

The <dbsTableLine> Tag can be used inside a <dbsLine> to format the current row in a way suitable for inclusion in a HTML Table. <dbsTableLine> prints the content of all fields belonging to r enclosed in <td> and </td> Tags.

< dbsTableBody dbsName />

The <dbsTableBody> Tag is an alternative to the <dbsLine> Tag. It shows all rows belonging to the current page in HTML Table Format. More precisely, all rows are displayed within <tr> and </tr> Tags. To display a complete Table, the HTML <table> and </table> Tags must be added, and a headline will also be useful.

< dbsTableHeadLine dbsName />

This Tag produces a headline in HTML Table Format. It displays all the field names, separated by <th> and </th> Tags.

< dbsTableHead dbsName />

This Tag works similar to the one above, but also includes the necessary HTML <tr> and </tr> Tags.

< dbsANext dbsName > ... </dbsANext>

This Environment Tag should be used inside the Tag, but not inside the <dbsLine> Tag. It creates a link that scrolls to the next page.

< dbsAPrev dbsName > ... </dbsAPrev>

This Environment Tag should be used inside the Tag, but not inside the <dbsLine> Tag. It creates a link that scrolls to the previous page.

< dbsAFirst dbsName > ... </dbsAFirst>

This Environment Tag should be used inside the Tag, but not inside the <dbsLine> Tag. It creates a link that scrolls to the first page.

< dbsALast dbsName > ... </dbsALast>

This Environment Tag should be used inside the Tag, but not inside the <dbsLine> Tag. It creates a link that scrolls to the last page.

< dbsScrollBarNum dbsName > ... </dbsScrollBarNum>

This Tag should be used inside the Tag, but not inside the <dbsLine> Tag. It produces a particular type of Scroll Bar in HTML format, in this case a list of page numbers. The current page number is printed in bold format to make it easier for the User to keep track of where (s)he is. The User can click on a number to go directly to the desired page. Inside the Environment, you can specify what should be printed between the numbers (usually one or two spaces to keep the numbers separated).

< dbsControls dbsName />

This Tag shows four links: First | Prev | Next | Last, with the obvious functionality.

< dbsControlLine dbsName />

This Tag shows four links: First | Prev | Next | Last, with the obvious functionality, followed by a Scroll Bar.