peoplecodeapi

DoModalComponentPopup

Mon 01 January 2018

Syntax 

DoModalComponentPopup(modal_options, Cancel_button_ID, title, MenuName.menuname, BarName.BARNAME, ItemName.MENUITEM_NAME, Page.COMPONENT_ITEM_NAME, action, Record.SHARED_RECORD_NAME [, keylist])

In which keylist is a list of field references in the form: 

[RECORD_NAME.]field1 [, [recordname.]field2]. . .

Or in which keylist is a list of field references in the form: 

&RecordObject1 [, &RecordObject2]. . .

Description

Use the DoModalComponentPopup function in fluid applications only. Use DoModalComponentPopup to display a secondary fluid component in a modal, secondary window, which means that the user must dismiss the secondary window before continuing work in the page from which the secondary window was called. The secondary component launches modally from within an originating component. After the secondary component is displayed, the user can’t proceed with changes to the originating component until either accepting or canceling the secondary component.

Secondary components can be displayed in any of the following action modes: Add, Update/Display, Update/Display All, Correction. A secondary component can be launched from any component, including another secondary component. You can also use DoModalComponentPopup from a secondary page.

The originating component and the secondary component share data, including search keys, using a shared work record or the values in the fieldlist parameter. If valid search keys are provided in the shared work record and populated with valid values before launching the secondary component, the search is conducted using the provided search key values. If the fieldlist parameter isn't used and no search keys are provided, or if search key fields contain invalid values, the user accesses the secondary component using a search dialog box.

Note: The user may see a different title for a search page if they enter the search page using this function versus from the regular navigation.

In the component_item_name parameter, make sure to pass the component item name for the page, not the page name.

Image: Determining the component item name

The component item name is specified in the component definition, in the Item Name column on the row corresponding to the specific page, as shown here. In this example, the PERSONAL_DATA page name appears twice: once with an item name of PERSONAL_DATA_1, and once with the item name of PERSONAL_DATA_2.

Determining the component item name

Parameters

Field or Control

Definition

modal_options

Specifies custom modal options as a String value. See for more information.

Cancel_button_ID

Specifies the field ID of the cancel button as a string value.

title

Specifies a string value to be displayed in the caption of the secondary page.

MenuName. MENUNAME

Name of the menu through which the secondary component is accessed.

BarName. BARNAME

Name of the menu bar through which the secondary component is accessed.

ItemName. MENUITEM_NAME

Name of the menu item through which the secondary component is accessed.

Page. COMPONENT_ITEM_NAME

The component item name of the page to be displayed on top of the secondary component when it displays.The component item name is specified in the component definition.

action

String representing the action mode in which to start up the component. You can use either a character value (passed in as a string) or a constant. See below.

If only one action mode is allowed for the component, that action mode is used. If more than one action mode is allowed, the user can select which mode to come up in.

Record. SHARED_RECORD_NAME

The record name of the shared work record (preceded by the reserved word Record ). This record must include:

  • Fields that are search keys in the secondary component search record; if search key fields are not provided, or if they are invalid, the user accesses the secondary component using the search dialog box.

  • Other fields to pass to the secondary component.

  • Fields to get back from the secondary component after it has finished processing.

keylist

An optional list of field specifications used to select a unique row at level zero in the page you are transferring to, by matching keys in the page you are transferring from. It can also be an already instantiated record object. If a record object is specified, any field of that record object that is also a field of the search record for the destination component is added to keylist . The keys in fieldlist must uniquely identify a row in the "to" page search record. If a unique row is not identified, the search dialog box appears.

If the keylist parameter is not supplied then the destination components' search key must be found as part of the source component's level 0 record buffer.

The values for the action parameter can be as follows:

Numeric Value

Constant Value

Description

A

%Action_Add

Add

U

%Action_UpdateDisplay

Update/Display

L

%Action_UpdateDisplayAll

Update/Display All

C

%Action_Correction

Correction

E

%Action_DataEntry

Data Entry

P

%Action_Prompt

Prompt

Returns

Returns a Boolean that indicates how the secondary page was terminated. A secondary page can be terminated by the user clicking a built-in OK or Cancel button, or by a call to the EndModalComponent function in a PeopleCode program. In either case, the return value of DoModalComponentPopup is one of the following:

  • True if the user clicked OK in the secondary page, or if 1 was passed in the EndModal function call that terminated the secondary page.

  • False if the user clicked Cancel in the secondary page, or if 0 was passed in the EndModal function call that terminated the secondary page.