Page-New method

Use the Page-New method to create a page on the clipboard. The new page may be a top-level page or an embedded page.

You can identify a data transform to initialize the newly created page. The data transform can set values for one or more properties.

CAUTION:
Except in rare cases, identify in the Step Page field the name of the page to be created by this method. If the Step Page field of the step is blank, this method clears the primary page of the current activity and may change its class. This often is undesirable.

Use the Apply-DataTransform method, not the Page-New method, to apply a data transform to an existing page.

Parameters

Identify the name of the page in the Step Page column of the step. Choose a valid page name. See Understanding page names and reserved pages.

This method has three parameters:

Parameter Description
Data Transform Optional. Enter the second key part of a data transform to apply to the new page. Identify a data transform with an Applies To class that is the same as, or a superclass of, the class of the new page.
PageList Optional. To save the name of the new page as the final element in a list, identify a Value List property (not a Page List property). Use the notation pagename.propertyname.

The system appends the name of the new page as the value of the last element of the Value List property.

NewClass

Optional. Identify a class — in most cases concrete class — for the new page. Enter the keyword $NONE to create a classless page.

If left blank, the system creates the new page using the class of the page specified in the Step Page column of the activity step being executed. (It retrieves the class of this page from the array entered in the Pages & Classes tab of the Activity form.)

If the Step Page field is also blank, the system creates the new page of the class that is the first key part of the current activity.

The following keywords mean different things in other parts of PRPC. Using them as a page name is not recommended: param, local, primary, steppage, mysteppage, top, parent, or current.

The following names and patterns are not valid: pxNode, pxRequestor, pxThread, locate* prompt*, $*, px*, pz*, or py*.

To avoid potential confusion, don't use Declare_ as the initial portion of a page name. By convention, such names indicate data pages.

Results

The system creates a new page as specified, using the name in the Step Page column of the step. Next, it finds the data transform using rule resolution and applies it to initialize the contents of the new page.

The page name may identify a Data Page rule that has a Page Type (on the Definition tab) of Read-Only. If appropriate conditions are met, the Data Page rule is executed and creates a clipboard page within the User Pages group. That page can thereafter be updated, saved, and processed like other user pages.

CAUTION:
Page names are unique within the clipboard. If another page with the new name is already present, the system replaces the contents of new page with the contents of the existing page that has the same name.

Checking the method status

This method updates the pxMethodStatus property. See How to Test method results using a transition.

To avoid overwriting an existing page

You may want the activity to check whether a page with a certain name exists before you open a new page.

In the activity step's precondition, enter the following:

= @PageExists("myPage", tools)

where myPage is the name of the clipboard page.

Restrictions

This method cannot be used in a step that involves iteration. This method cannot be used to create a data page.