Back ForwardURL directive

 About directives

  Show all 

Advanced featureThe URL directive provides a means to include a URL into the output HTML produced by stream processing.

You can use the URL directive to avoid synchronization problems that can arise if a user clicks a browser's Explorer's Back button rather than using navigation provided in Process Commander displays.

The URL directive has options related to navigation, target frames, and the primary page. COLEA/CLINB 11/8/02 removed CONTEXT option

Whenever you insert an anchor or a submit button into your HTML, you can use the URL directive. If you use the URL directive with a submit button, work with the FORM tag as well.

JSP tag Equivalent

The pega:url JavaServer Page tag provides a functionally identical capability. See JSP Tags — URL.

Example

Here is an example of the URL directive used with an anchor.

<A HREF="{URL pyStream=myStream  PRIMARY }" >
    <B>Click here to ... </B>
</A>

  Complete syntax

In the syntax presentations below:

{URL [action-specification] [options separated by spaces]}

Use quote marks as shown in the examples below.

The action-specification is either pyStream=myStream or pyActivity=myActivityClass.myActivityName.

When using the URL directive in a FORM tag, you can enter the action specification in either the form tag, the button tag, or the anchor tag. If you have more than one action specification, enter it in the button tag or the anchor tag, rather than in the form tag.

{URL [options separated by spaces]

Enter the action-specification in the anchor or submit button.

<A HREF="{URL pyStream=myStream PRIMARY}">
<B>MyAnchorText</B></A>

      Options

This table lists each option and its corresponding property. Each option is explained in detail below.

NoteInclude the PRIMARY keyword unless the HTML rule is in the ultimate base class @baseclass (an unusual situation). COLEA 10/31/02

Enter

Or abbreviate as

To add this parameter

TRANSID

T

pzTransactionId

FRAME

F

pzFromFrame

PRIMARY

P

pzPrimaryPageName

LONG

L

Add all three properties

           State synchronization (TRANSID option)

unclear Used with a form and a SUBMIT button, the TRANSID option of the URL directive can be useful to maintain synchronization between the servers state and the user's browser state. Ideally, such synchronization works even when a user clicks the Back icon in the browser window.

The TRANSID keyword causes the pzTransactionID parameter value to be included in the URL.

When the browser state changes as the result of a user submitting an HTML stream, the pzTransactionID parameter stores the server state as it corresponds to the current browser stream, tracking where the user has been, and where the user is. In some situations, it is important that the browser state and the server state correspond accurately.

In situations where the server state data is not relevant, you can omit the TRANSID keyword.

Use this syntax to specify the TRANSID option:

<FORM = action = "{URL "" TRANSID PRIMARY}">my form HTML
<INPUT TYPE=Submit Name="pyStream=myStream">

NoteThe TRANSID keyword implies the FRAME keyword.

           Target frame (FRAME Keyword)

Add the FRAME keyword to include the pzFromFrame property in the URL. Use this option if the target frame for the anchor is not the STANDARD frame, but is the current default frame. (The second parameter of the Show-HTML method determines the target frame for the HTML.)

<A HREF="{URL "pyStream=myStream" FRAME}">
<B>MyAnchorText</B></A>

The pzFromFrame property provides the default value for the pyTargetFrame parameter, the target frame used by the stream. If omitted, the system uses the STANDARD frame,

To add an explicit target frame, see below.

           Called activity's primary page (PRIMARY keyword)

Add the PRIMARY keyword to the URL directive to instruct the system to include the value of the pzPrimaryPageName property in the URL when the user clicks an anchor or submit button.

Use this option to tell the system to use the default primary page as the primary page when a user clicks the anchor. If the activity the anchor calls expects a primary page, use the PRIMARY keyword or enter an explicit primary page using the pyPrimaryPageName property.

For example, an anchor that calls an activity to delete a page must indicate what page to delete. By contrast, an anchor that calls an activity that sets up its own primary page does not require the information.

           Specify all options

To specify all three options, use the LONG keyword:

<A HREF="{URL "pyStream=myStream" LONG}">
<B>MyAnchorText</B></A>

Appending parameters and property-value pairs explicitly

You can append property-value pairs by property name to an anchor. To add property-value pairs, use an ampersand (&) character and enter the property value pair.

For example, you can cause an anchor to explicitly assign a primary page, using the pyPrimaryPageName parameter. COLEA 11/1/02

<A HREF="{URL pyActivity=myActivityClass.myActivity&pyPrimaryPageName=myPage}"><B>MyAnchorText</B></A>

Note The clipboard page identified for pyPrimaryPageName must be a top-level page. RACIE 9/23/04 Q-1032

For another example, you can add an explicit target frame using the pyTargetFrame parameter.

<A HREF="{URL pyStream=myStream&pyTargetFrame=myLeftFrame}"><B>MyAnchorText</B></A>

  Submit buttons

To use the URL directive with a Submit button, type the URL directive in the ACTION attribute of the Form tag like this:

<FORM action="{URL "" PRIMARY TRANSID FRAME}">

Reference the pyActivity or pyStream in the submit button.

<INPUT TYPE="Submit" NAME="pyActivity=Add">

When a user clicks the  Submit   button, the URL in the FORM tag is used.

NoteOnly activities that have the May Start? box on the Security tab may be started with the URL tag.

  Advanced uses

Suppressing options

OLSOK 1/22/02 Options for the URL directive promote transaction integrity between the client browser session and the requestor state on the Process Commander server.

In most HTML forms, values for all of the options of the URL directive (TRANSID, FRAME, PRIMARY) are usually provided by hidden input fields such as:

<INPUT TYPE="HIDDEN" >

which the system adds immediately following a FORM tag.

The system does not add these inputs if the FORM tag specifies either:

Starting a new Thread

R-8914 03-04 MIRAT Execution of the URL directive can start execution of a new Thread for the current requestor. (A Thread is a context of clipboard user pages; it is not related to the UNIX thread.) Using the Property-Set method or a Java directive, set the name of a new Thread as the value of the pxThread.pyThreadUse property before the URL directive executes. The default Thread is named STANDARD; you can use any other alphabetic text can be used for the new thread name. VAGUE

See the Pega Developer Network article PDNPRKB-10979 How to use the URL directive to configure transactional HTML forms for more information on synchronizing user input with database transactions.

Up Directives