PAGE item type

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.

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.

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.

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.

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