DoModal function

Syntax

DoModal(Page.page_name, title, xpos, ypos, [level, scroll_path, target_row])

In which scrollpath is: 

[Record.level1_recname, level1_row, [Record.level2_recname, level2_row, ]] Record.target_recname

To prevent ambiguous references, you can also use Scroll. scrollname, in which scrollname is the same as the scroll level’s primary record name.

Description

Use the DoModal function to display a secondary page in a modal, secondary window with a child relationship to the parent window. This means that the user must dismiss the secondary window before continuing work in the page from which the secondary window was called. DoModal can display a single page modally. To display an entire component modally, use DoModalComponent.

Important:

The DoModal and DoModalComponent functions support fluid-to-fluid, or classic-to-classic parent/child relationships only. See Fluid User Interface Developer’s Guide: Transfer and Modal Functions for more information on which functions are available for which purposes.

Alternatively, you can specify a secondary page in a command push button definition without using PeopleCode. This may be preferable for performance reasons.

Any variable declared as a component variable will still be defined after calling the DoModal function. If you call DoModal without specifying a level number or any record parameters, the function uses the current context as the parent. See Application Designer Developer’s Guide: Using Secondary Pages.

When you use the DoModal function in component PreBuild or PostBuild PeopleCode event, do not use browser refresh to reload a page because the browser will throw an error.

Parameters

Parameter Description

page_name

The name of the secondary page.

title

The text that displays in the caption of the secondary page.

xpos

The pixel coordinates of the top left corner of the secondary page, offset from the top left corner of the parent page (the default of -1, -1 means centered).

ypos

The pixel coordinates of the top right corner of the secondary page, offset from the top right corner of the parent page (the default of -1, -1 means centered).

level

Specifies the level of the scroll level on the parent page that contains the row corresponding to level 0 on the secondary page.

scroll_path

A construction that specifies a scroll level in the component buffer.

target_row

The row number of the row in the parent page corresponding to the level 0 row in the secondary page.

Returns

Returns a number 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 EndModal function in a PeopleCode program. In either case, the return value of DoModal is one of the following:

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

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

Example

DoModal(Page.EDUCATION_DTL, MsgGetText(1000, 167, "Education Details - %1", EDUCATN.DEGREE), - 1, - 1, 1, Record.EDUCATN, CurrentRowNumber());

Restrictions on Use in PeopleCode Events

Control does not return to the line after DoModal until after the user has dismissed the secondary page. This interruption of processing makes DoModal a “think-time” function, which means that it shouldn’t be used in any of the following PeopleCode events:

  • SavePreChange.

  • SavePostChange.

  • Workflow.

  • RowSelect.

  • Any PeopleCode event that executes as a result of a ScrollSelect, ScrollSelectNew, RowScrollSelect, or RowScrollSelectNew function call.

  • Any PeopleCode event that executes as a result of a Rowset classes Select method or SelectNew method.

  • You should not use DoModal or any other think-time function in FieldChange when the field is associated with an edit box, long edit box, or drop-down list box. Use FieldEdit instead.

    However, DoModal can be used in FieldChange when the field is associated with a push button, radio button, check box, or hyperlink.

In addition, you can't use DoModal in the SearchInit event.

See PeopleCode Developer’s Guide: Think-Time Functions.

Restrictions on Use With a Component Interface

This function is ignored (has no effect) when used by a PeopleCode program that’s been called by a component interface.

Considerations for the DoModal Function and Catching Exceptions

Using the DoModal function inside a try-catch block does not catch PeopleCode exceptions thrown in the new component. Starting a new component starts a brand new PeopleCode evaluation context. Exceptions are only caught for exceptions thrown within the current component.

In the following code example, the catch statement only catches exceptions thrown in the code prior to the DoModal, but not any exceptions that are thrown within the new component: 

/* Set up transaction */
If %CompIntfcName = "" Then
   try
      &oTrans = &g_ERMS_TransactionCollection.GetTransactionByName(RB_EM_⇒
WRK.DESCR);
      &sSearchPage = &oTrans.SearchPage;
      &sSearchRecord = &oTrans.SearchRecord;
      &sSearchTitle = &oTrans.GetSearchPageTitle();
      If Not All(&sSearchPage, &sSearchRecord, &sSearchTitle) Then
         Error (MsgGetText(17834, 8081, "Message Not Found"));
      End-If;
      &c_ERMS_SearchTransaction = &oTrans;
      /* Attempt to transfer to hidden search page with configurable filter */
      &nModalReturn = DoModal(@("Page." | &sSearchPage), &sSearchTitle, - 1, - 1);
   catch Exception &e
      Error (MsgGetText(17834, 8082, "Message Not Found"));
   end-try;

Related Topics