PAGE item type

Defines the content of a folder page.

PAGE item basics

A PAGE form item type groups other form elements together, to define a folder page of a parent FOLDER form item.

Defining an PAGE

A PAGE form item can only be a child of a FOLDER form item.

By default, PAGE form items are used to group elements for decoration only.

Note: Use the TABINDEX attribute of form fields inside the folder page, to define which field gets the focus when a folder page is selected.

The TEXT attributes defines the label of the folder page. Consider using localized strings for this attribute.

The IMAGE attribute can be used to specify which image to use as an icon.

Controlling forms using folder pages

To control a form with folder pages, use a DIALOG instruction block, where each sub-dialog controls a specific folder page. A given sub-dialog may control several folder pages, but in this case, it will not be possible to detect page selection within BEFORE INPUT, BEFORE DISPLAY or BEFORE CONSTRUCT triggers in DIALOG/END DIALOG.

When a folder page is selected by the user, and the focus is in the context of that folder, the focus is set to the field with the lowest TABINDEX in the selected folder PAGE. The dialog code can then detect which page was selected by using BEFORE INPUT, BEFORE DISPLAY or BEFORE CONSTRUCT of the corresponding sub-dialog block:
DIALOG ...
    INPUT BY NAME rec.* ...
       BEFORE INPUT -- focus goes to a field of this sub-dialog/folder page
           ...

If the focus is not in the context of the folder, the user can still select a folder tab to show up one of its pages, but the focus is not set to an element of that page: The focus remains in the current field, unless the user explicitly clicks or tabs to a field of the displayed page. This allows to view folder pages while entering data in another dialog, without leaving the current field, which would produce input validation and AFTER FIELD / AFTER INPUT blocks execution.

To bring a folder page to the top by program, if the target folder page has at least one focusable field, use the NEXT FIELD instruction to give the focus to one of the active fields of the page. If the folder page has no focusable element, use the ui.Form.ensureFieldVisible() or the ui.Form.ensureElementVisible() method. For more details, see Giving the focus to a form element.

When a FOLDER PAGE contains another FOLDER container, it defines a sub-folder. When a user selects the tab of the parent folder page containing the sub-folder, it is possible to show a given sub-folder page, by calling the ui.Form.ensureFieldVisible() or ui.Form.ensureElementVisible() method, in the BEFORE INPUT, BEFORE DISPLAY or BEFORE CONSTRUCT of the sub-dialog controlling the parent folder page (the focus will stay in the current field of the parent folder page because this is not a NEXT FIELD):
DIALOG ...
    -- Sub-dialog controlling the parent folder page
    INPUT BY NAME rec_customer.* ...
       BEFORE INPUT -- focus goes to a field of this sub-dialog/folder page
           -- Show the main page of the sub-folder with orders info
           CALL DIALOG.getForm().ensureFieldVisible("orders.order_num")
       ...
    END INPUT
    -- Sub-dialog controlling sub-folder main page
    INPUT BY NAME rec_orders.* ...
       ...

A folder PAGE can define an ACTION attribute, to bind an ON ACTION action handler, and detect that the folder page is selected. This may be used in some rare cases, for example when no form item can get the focus implicetly.

Note: The ACTION attribute on folder pages was initially provided before multiple dialogs were introduced, to control the folder pages with a set of singular dialogs. With this solution, the code must exit the current singular dialog when the page action fires, and restart the singular dialog controlling the target folder page. This practice is now strongly discouraged and should be replaced by a DIALOG statement.

Avoid NEXT FIELD usage in the ON ACTION block of a folder page action: Use the default focus management, based on TABINDEX attributes to control which element must get the focus when a folder page is selected.

Where to use a PAGE

A PAGE form item can be defined in different ways:
  1. As a PAGE container in a LAYOUT tree, within a grid-based layout.
  2. As a PAGE stack item, inside a STACK container, within a stack-based layout.