PeopleTools | Calling a modal page in classic and fluid
A. Definition of Modal Page
A modal page is any page that opens in the form of a ‘pop-up’ window, overlaying the previous page that the user happened to be looking at. The word ‘modal’ indicates that the user must deal with the modal page first, before returning to the main page. Typically a modal page might be used to enter additional details on the component, or when the user needs to confirm whether a delete or an associated update needs to take place.
A modal page might not always be necessary. The requirement could possibly be met by the ‘MessageBox’ function (refer to the related tip below). If however you have a more complex requirement that cannot be met by ‘MessageBox’, you will need to set up a new secondary page in App Designer and then call that page directly from PeopleCode.
The traditional command used for calling a modal page is ‘DoModal’. This will be discussed in the next section. However, fluid has introduced a new series of functions designed for fluid alone. In section C below we will look at one of the fluid functions: ‘DoModalPopup’.
B. Defining a Modal Page
To access a modal page, you first need to create the page in App Designer. This follows the same approach for a normal page, except that the page must be marked as a ‘Secondary Page’. To do this, go into the Page properties, followed by the ‘Use’ tab. Then set the ‘Page Type’ equal to ‘Secondary Page’:
Typically, you also want the modal page to display a set of buttons, such ‘OK’ and ‘Cancel’ or just ‘Close’ on its own. With these buttons included, you can then write PeopleCode to check which button was pressed, and process the response accordingly. To specify the buttons, select the appropriate checkbox in the ‘Use’ tab of the page properties:
If the modal page is intended to work as a standalone page, such as when you want to ask the user a question, no further set-up work is required. If however you want the fields of the modal page to be available to the original calling component – perhaps as part of some validation on save – a secondary page ‘control’ needs to be added to the main page.
To do this, open the main page in App Designer. Go to the ‘Insert’ menu and select ‘Secondary Page’:
Click on any blank space in the page. This will insert a small little square ‘box’:
Double click on the box to access the properties for the secondary page control. Specify the name of the Secondary Page:
Save the page. The secondary page is now seen as part of the calling component.
C. Non-PeopleCode Approach
If you have a fairly basic modal page – one that requires no set-up and no additional processing on exit of the page – you may not need to write any PeopleCode at all. If you’ve set up a hyperlink or a push-button to call the modal page, the properties of the hyperlink/push-button allow you to call the modal page directly:
This saves you the bother of writing any PeopleCode, although the obvious downside is that the solution lacks flexibility. You cannot add any additional code.
D. Classic Approach
The traditional way of calling a modal page is via the ‘DoModal’ function. This accepts the following four parameters:
(i) Secondary page name
(ii) Page title
(iii) ‘X’ position of the page (top left corner), as measured in pixels from the top left-hand corner of the browser window (use -1 for centring the page)
(iv) ‘Y’ position of the page (top right corner), as measured in pixels from the top right-hand corner of the browser window (use -1 for centring the page)
Here’s an example of the command being called:
&returnCD = DoModal(Page.PAGE_NAME, "", - 1, - 1);
If the modal page also includes buttons – such as OK and Cancel – the ‘return code’ value can be checked to see which button the user pressed:
If &returnCD = 1 Then /* User pressed OK */ Else /* User pressed Cancel */ End-If;
E. Fluid Approach
The Fluid approach follows the same approach as classic, but the ‘DoModalPopup’ function allows you to pass a more detailed set of parameters:
(i) Format String – refer below for further details
(ii) Label text used for the ‘Cancel’ button
(iii) Display Only indicator (True for display-only)
(iv) Cache Indicator (True to indicator that modal page should be cached as part of the calling page)
(v) Secondary Page Name
(vi) Page Title
(vii) “X” position of the page (similar to ‘DoModal’)
(viii) “Y” position of the page (similar to ‘DoModal’)
The format string (parameter 1 above) is a list of specific display parameters. If there is more than one parameter, each parameter must be separated by a semicolon. Refer to PeopleBooks for a full list of the formats available, but here are some typical values:
- bFullScreen@1 : display the modal window as a full screen
- bCenter@1 : display the modal window in the centre of the page
- bAutoClose@1 : automatically close the modal window if the user clicks anywhere outside of the window
- sWidth@100px : set the modal window width to 100 pixels
- sHeight@100px : set the modal window height to 100 pixels
Here’s an example of ‘DoModalPopup’ being called:
&returnCD = DoModalPopup("bFullScreen@1;bAutoClose@1",
"Cancel", False, False, Page.PAGE_NAME, "Modal Page Title",
- 1, - 1);
The return code can be processed in the same way as ‘DoModal’.
See Also:
Tip 041 : MessageBox Function