URL directive |
The 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 the Pega Platform displays.
The URL directive has options related to navigation, target frames, and the primary page.
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.
The pega:url JavaServer Page tag provides a functionally identical capability. See JSP Tags — URL.
Here is an example of the URL directive used with an anchor.
<A HREF="{URL pyStream=myStream PRIMARY }" >
<B>Click here to ... </B>
</A>
In the syntax presentations below:
[ and ] define optional parts of the directive. Do not type the brackets.{ and } mark the start and end of the directive.{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>
This table lists each option and its corresponding property. Each option is explained in detail below.
Include the PRIMARY keyword unless the HTML rule is in the ultimate base class @baseclass (an unusual situation).
Enter |
Or abbreviate as |
To add this parameter |
|
|
T
|
|
|
|
F
|
|
|
|
P
|
|
|
|
L |
|
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">
The TRANSID keyword implies the 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.
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.
To specify all three options, use the LONG keyword:
<A HREF="{URL "pyStream=myStream" LONG}">
<B>MyAnchorText</B></A>
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.
<a HREF="{URL pyActivity=myActivityClass.myActivity&pyPrimaryPageName=myPage}">
<b>MyAnchorText</b></a>
The clipboard page identified for pyPrimaryPageName must be a top-level page.
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>
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.
Note: Only activities that have the May Start? box on the Security tab may be started with the URL tag.
Options for the URL directive promote transaction integrity between the client browser session and the requestor state on the Pega Platform 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:
ACTION attribute with a value not specified by a URL directive, orMETHOD attribute with a value other than POST.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.