SCROLLGRID item type

Defines a scrollable grid view widget.


This topic covers the SCROLLGRID item type definition in form files. See also the chapter dedicated to scrollgrid view programming.

SCROLLGRID item basics

A SCROLLGRID form item type defines a grid to show a scrolling list of data records in a set of positioned form fields.

The SCROLLGRID basically acts like a TABLE container, in the sense of its function as a record list container.

By default, scrollgrids display a fixed number of rows, and can be configured to be resizable in height.

A SCROLLGRID is controlled by a DISPLAY ARRAY or INPUT ARRAY dialog, see List dialogs for more details about this type of dialogs.


The SCROLLGRID form item defines a formatted list view to show a structured set of data records. It is bound to a screen array grouping form fields which define the list fields of the scrollgrid.

The screen array definition must have exactly the same number of fields as the SCROLLGRID form item. Use PHANTOM fields, if the number of record members in the program array exceeds the number of fields to be displayed in the SCROLLGRID container.

The SCROLLGRID form item declares a formatted text block, defining the dimensions and the position of the logical elements of a screen for a multi-record presentation.

A SCROLLGRID is similar to the GRID, that repeats on several "row-templates", in order to design a view for multiple-records that display with a vertical scrollbar.

Inside a SCROLLGRID, the same layout rules apply as in a GRID container.

Static labels can be used as in a regular GRID container. However, this prevents you from localizing the label text. Consider using LABEL fields with a TEXT attribute, instead of static text labels.

Front-ends support different presentation and behavior options, which can be controlled by a STYLE attribute. For more details, see Style attributes common to all elements and ScrollGrid style attributes.

Where to use a SCROLLGRID?

A SCROLLGRID form item must be defined in different ways:
  1. As a SCROLLGRID container in a LAYOUT tree.
  2. As a <SCROLLGRID > layout tag with a SCROLLGRID item definition in the ATTRIBUTES section.

Defining the scrollgrid size and layout

The global size of a SCROLLGRID element is defined by its content, and the number of record rows displayed.

When using a SCROLLGRID container, you cannot set the GRIDCHILDRENINPARENT attribute. This attribute makes sense only for a scrollgrid defined with a layout tag, within a GRID area.

By default, a scrollgrid is not resizable in height: The number of visible rows is defined by the number of row templates in the form layout. Use the WANTFIXEDPAGESIZE=NO attribute, to allow the scrollgrid to resize.

When using WANTFIXEDPAGESIZE=NO, a resizable scrollgrid is displayed with one single row, if no other element in the form layout makes the scrollgrid stretch implicitly. To force a default number of rows in stretchable scrollgrids, use the INITIALIPAGESIZE attribute.

A usual pattern on the web is to render information as a responsive tile list, using tiles displayed in pages. Each tile will flow, depending on the container size.

To render stretchable scrollgrids as a paged responsive tile list, define the customWidget presentation style attribute to pagedScrollGrid. With this attribute, each scrollgrid row will be rendered as a tile (the page size of the scrollgrid defines the number of tiles in each page):
<Style name="ScrollGrid.paged" >
    <StyleAttribute name= "customWidget" value= "pagedScrollGrid" />

For more details, see also Controlling scrollgrid rendering.