19 Wiring Pages, Task Flows, Portlets, and UI Components

Often a page needs information from a component on the page, or a region needs information from another region. While you can pass parameters through the page URL to obtain that information, doing so makes sense only when the parameters are well-known and the inputs are accessible to the page through Expression Language (EL). For more information, see Section 19.4, "Passing Parameter Values Through the Page URL."

Consider the case where you have a task flow with multiple page fragments that contain various interesting values that could be used as input on a page in the flow. For example, consider a page devoted to the display of information specific to the company that a user specifies in an input form. If you were to use parameters to pass the value, the task flow must surface output parameters for the union of each of the interesting values on each and every fragment. This is where component wiring becomes useful. Instead, for each fragment that contains the needed information, you can use component wiring to define a contextual event that is raised when the page is submitted. The page or fragment that requires the information can then subscribe to the various events and receive the information through the event.

Composer provides tools for wiring pages and components through its Page Properties and Component Properties dialogs. This chapter describes the use of these tools in the following sections:

Section 19.1, "What You Should Know About Parameter and Event Wiring"
Section 19.2, "Wiring One Component to Another"
Section 19.3, "Wiring Components and Page Parameters"
Section 19.4, "Passing Parameter Values Through the Page URL"

Note:

If you navigate away from a page while editing it, unsaved changes are lost.

Audience

This chapter is intended for advanced users who have experience with and knowledge of component wiring. Interested users include those who want to create more complex relationships between a page and its components and between the components themselves.

19.1 What You Should Know About Parameter and Event Wiring

You can use parameters and events to pass values from one component to another, or from a page to a component on that page. Additionally, you can pass values to page components by specifying them in the page's URL.

Note:

In this chapter, component refers collectively to UI components, such as buttons; layout components, such as hyperlinks; task flows; and portlets.

Value passing is useful for synchronizing the content of a page with its components, or the content of one component to another. For example, you can wire a Parameter Form portlet so that the event of clicking its OK button triggers the passing of its user-entered values to another component on the page. One way to apply this model is to pass a user-entered name to a task flow or portlet that displays details relevant to that name.

To clarify what it going on in a parameter passing scenario, it helps to think of one component as the producer and the other component as the consumer. The producer component provides the payload that the consumer component consumes. For example, a form portlet is typically a producer. Its payload is the data that users enter into the form. An event defined on the producer triggers the passing of the producer's payload to the consumer. Consumer components use the payload in various ways. For example, as a display string, a master in a master-detail relationship, and the like. How a consumer component uses the payload is specified in an event handler that was defined when the consumer component was created.

The heavy lifting required to produce meaningful parameter and event wiring is performed mostly at application and component design time. When developers build applications and components, they specify events and event maps in page definition files. Consequently, for runtime wiring to work, the components you want to wire must provide support for wiring through elements that were built-in at design time.

Note:

Runtime refers to the time when users run the application in a real-world environment. Contrast this with design time, which refers to the time developers build the application.

Runtime wiring creates a relationship between a producer event and a consumer event handler. You can create these relationships in Composer. Select a component and view its events support on the Events tab of the Component Properties dialog (Figure 19-1).

Figure 19-1 Events Tab in the Component Properties Dialog

Events tab in the Component Properties dialog box

Once you select and enable an event and an event handler (see the Action section in Figure 19-1), you can define the type of payload to deliver when the event is triggered.

Composer additionally provides an opportunity to create page parameters on the Parameters tab of the Page Properties dialog (Figure 19-2).

Figure 19-2 Parameters Tab in the Page Properties Dialog

Parameters tab in Page Properties dialog box

Use the Parameters tab to create new page parameters and to revise existing page parameters. Create parameters that consume value types, including constants, EL expressions, page parameters, and page definition variables

You can easily configure page components to consume page parameters, and you can pass values to those parameters through the page URL.

19.2 Wiring One Component to Another

Components with built-in events and event handlers can be wired to each other to enable the passing of values from a producer component to a consumer component. This section describes how to set up such wiring. It includes the following subsections:

Section 19.2.1, "Wiring a Task Flow to a Task Flow"
Section 19.2.2, "Wiring a Portlet to a Portlet"
Section 19.2.3, "Wiring a Portlet to a Task Flow"
Section 19.2.4, "Wiring a Task Flow to a Portlet"
Section 19.2.5, "Wiring a UI Component to a Task Flow"

19.2.1 Wiring a Task Flow to a Task Flow

In addition to seeded services and task flows, you can bring custom task flows into the Oracle WebCenter Portal: Spaces application. To bring custom task flows into Spaces, you must first portletize them, so that they can be consumed by Spaces across a portlet bridge.

Note:

When you work with contextual event wiring across a portlet bridge and no payload or a null payload is propagated across the wire from the producer portlet to the consumer, such payloads are delivered as an empty string. If the consumer portlet is required to differentiate between an empty string and null, you can encode the null in the producer portlet payload. The consumer portlet consequently looks for this custom encoding to detect the null payload.

Custom task flows may support events and may include the capability of parameter passing. Events and parameter passing could enable one custom task flow to pass values to other custom task flows on the same page. For example, you could wire custom task flows so that when a user clicks a particular document, an event is raised that triggers parameter passing to the other custom task flows on the page. The passed parameters could cause the other custom task flows to rerender with content relevant to the clicked document.

When a custom task flow is portletized, any portlet events or public render parameters raised by the portletized task flow are automatically delivered to other portletized task flows that declare support for those events or parameters. You can also manually wire portletized custom task flows using Composer's Component Properties dialog. The events and parameters that you configure vary according to the functionality that developers build into custom task flows. The steps provided in this section describe how to perform this manual mapping.

Creating and portletizing custom task flows and using the portlet bridge are all discussed in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal. For information about consuming custom task flows and other custom components in Spaces, see Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

To manually wire a task flow to a task flow:

Navigate to the relevant page, and enter page edit mode.

Tip:
One way to enter page edit mode is to press Ctrl-Shift-E.
Click the Edit icon on the task flow that consumes the payload provided by the producer task flow.

The Component Properties dialog opens.
Click the Events tab to bring it forward, and, from the Events pane, select an event associated with the producer task flow.

The Events pane lists all of the events that can be raised from any component on the page. An asterisk (*) on an event indicates that an action is handling it.
In the Actions pane, select the action to execute when the event occurs.

The Actions pane lists all of the event handlers associated with the consumer task flow that are supported by the selected producer task flow. Only those actions that can be invoked for the event that is selected in the Events pane are shown. An asterisk (*) on an action indicates that it is handling an event.
Select Enable Action to enable the selected event and action.

An asterisk (*) appears next to the selected event and action. Value options appear below the checkbox.
From the displayed value options, select the type of value to use to deliver the payload from the producer task flow to the consumer task flow whenever the event occurs.

Choose from:
- Constant—Select Constant, and enter a constant or EL expression value to pass to the consumer task flow.
- EventData—Select to pass the variable ${payLoad}, which delivers whatever payload is specified by the producer task flow.
  
  Note:
  The value for ${payLoad} is specified when the task flow is created.
Click Save at the top right of Composer to save your changes.
Click Close to exit Composer.
Test your wiring by triggering the event.

19.2.2 Wiring a Portlet to a Portlet

When a portlet is added to a page, it is automatically configured to listen to public render parameters and portlet events generated on the page and respond accordingly. This means that in many cases portlets are automatically wired, as long as the name of the public render parameter or publishing event on the producer side matches that of the public render parameter or processing event on the consumer side, or if an appropriate alias has been created to associate parameters or events.

When portlets have not been designed to explicitly work together, you can manually wire portlets as described in the steps below.

Note:

You cannot turn off automatic parameter and event listening in the Spaces UI. If you do want to turn off this feature for a particular portlet you must:

Export the space that consumes the portlet.
In JDeveloper, open the page definition for the page that contains the portlet.

Edit the portlet binding to set the listenForAutoDeliveredPortletEvents and listenForAutoDeliveredParameterChanges attributes to false:

<portlet id="p2_1"
         ...
         listenForAutoDeliveredPortletEvents="false"
         listenForAutoDeliveredParameterChanges="false"
         ...
/>

Import the space back into Spaces.

To manually wire a portlet to a portlet:

Navigate to the relevant page, and enter page edit mode.

Tip:
One way to enter page edit mode is to press Ctrl-Shift-E.
Click the Edit icon on the portlet that consumes the payload provided by the producer portlet.

The Component Properties dialog opens.
Click the Events tab to bring it forward, and select an event associated with the producer portlet.

The Events pane lists all of the events that can be raised from any component on the page. An asterisk (*) on an event indicates that an action is handling it.
In the Actions pane, select the action to execute when the event occurs.

The Actions pane lists all of the event handlers associated with the consumer portlet that are supported by the selected producer portlet. Only those actions that can be invoked for the event that is selected in the Events pane are shown. An asterisk (*) on an action indicates that it is handling an event.
Select Enable Action to enable the selected event and action.

An asterisk (*) appears next to the selected event and action.
Provide values for the portlet parameters that now display at the bottom of the Events tab.

Select Constant, and enter a composite data value, for example:
```
${payLoad.ora_wsrp_navigparam_Parameter1}
```
Note:
The parameter names and values were specified when the portlet was created.
Click Save at the top right of Composer to save your changes.
Click Close to exit Composer.
Test your wiring by triggering the event.

19.2.3 Wiring a Portlet to a Task Flow

In this scenario, the portlet is the producer, providing the event payload, and the task flow is the consumer of that payload.

To wire a portlet to a task flow:

Navigate to the relevant page, and enter page edit mode.

Tip:
One way to enter page edit mode is to press Ctrl-Shift-E.
Click the Edit icon on the task flow that consumes the payload provided by the producer portlet.

The Component Properties dialog opens.
Click the Events tab to bring it forward, and select an event associated with the producer portlet from the Events pane.

The Events pane lists all of the events that can be raised from any component on the page. An asterisk (*) on an event indicates that an action is handling it.
In the Actions pane, select the action to execute when the event occurs.

The Actions pane lists all of the event handlers associated with the consumer task flow that are supported by the selected producer portlet. Only those actions that can be invoked for the event that is selected in the Events pane are shown. An asterisk (*) on an action indicates that it is handling an event.
Select Enable Action to enable the selected event and action.

An asterisk (*) appears next to the selected event and action. Value options appear below the checkbox.
Select Constant, and enter a composite data value for a parameter associated with the producer portlet.

For example:
```
${payLoad.ora_wsrp_navigparam_Parameter1}
```
Click Save at the top right of Composer to save your changes.
Click Close to exit Composer.
Test your wiring by triggering the event.

19.2.4 Wiring a Task Flow to a Portlet

In this scenario, the task flow is the producer, providing the event payload, and the portlet is the consumer of that payload.

To wire a task flow to a portlet:

Navigate to the relevant page, and enter page edit mode.

Tip:
One way to enter page edit mode is to press Ctrl-Shift-E.
Click the Edit icon on the portlet that consumes the payload provided by the producer task flow.

The Component Properties dialog opens.
Click the Events tab to bring it forward, and select an event associated with the producer task flow in the Events pane.

The Events pane lists all of the events that can be raised from any component on the page. An asterisk (*) on an event indicates that an action is handling it.
In the Actions pane, select the action to execute when the event occurs.

The Actions pane lists all of the event handlers associated with the consumer portlet that are supported by the selected producer task flow. Only those actions that can be invoked for the event that is selected in the Events pane are shown. An asterisk (*) on an action indicates that it is handling an event.
Select Enable Action to enable the selected event and action.

An asterisk (*) appears next to the selected event and action.
Provide values for the portlet parameters that now appear at the bottom of the Events tab.

Select Constant, and enter a composite data value, for example:
```
${payLoad.ora_wsrp_navigparam_Parameter1}
```
Note:
The parameter names and values were specified when the portlet was created.
Click Save at the top right of Composer to save your changes.
Click Close to exit Composer.
Test your wiring by triggering the event.

19.2.5 Wiring a UI Component to a Task Flow

In this scenario, the UI component is the producer of the payload, and the task flow is the consumer of the payload.

To wire a UI component to a task flow:

Navigate to the relevant page, and enter page edit mode.

Tip:
One way to enter page edit mode is to press Ctrl-Shift-E.
Click the Edit icon on the task flow that consumes the payload provided by the producer UI component.

The Component Properties dialog opens.
Click the Events tab to bring it forward, and select an event associated with the producer UI component in the Events pane.

The Events pane lists all of the events that can be raised from any component on the page. An asterisk (*) on an event indicates that an action is handling it.
In the Actions pane, select the action to execute when the event occurs.

The Actions pane lists all of the event handlers associated with the consumer task flow that are supported by the selected producer UI Component. Only those actions that can be invoked for the event that is selected in the Events pane are shown. An asterisk (*) on an action indicates that it is handling an event.
Select Enable Action to enable the selected event and action.

An asterisk (*) appears next to the selected event and action. Value options appear below the checkbox.
Select the type of value to use to deliver the payload from the producer UI component to the consumer task flow whenever the event occurs.

Choose from:
- Constant—Select Constant, and enter a constant or EL expression value to pass to the consumer task flow.
- EventData—Select to pass the variable ${payLoad}, which delivers whatever payload is specified by the producer UI component.
  
  Note:
  The value for ${payLoad} was specified when the UI component was created.
Click Save at the top right of Composer to save your changes.
Click Close to exit Composer.
Test your wiring by triggering the event.

19.3 Wiring Components and Page Parameters

Page parameters and page variables are central to the process of creating enterprise mashups. They enable communication between components and the pages that contain them.

For example, imagine a page that contains stock ticker and stock news components. You want the ticker and the news components to both consume the same parameter value so that they both show information for the same company. Page parameters and page variables are part of a simple mechanism for setting this up.

Page parameters provide a means of storing values for passing to page components that have been configured to consume them. Create page parameters through Composer at application runtime. Page variables contain output values that are produced by portlets. Page variables are created at application design time.

This section describes how to create and consume page parameters in the following subsections:

Section 19.3.1, "Creating Page Parameters"
Section 19.3.2, "Consuming Page Parameters"

19.3.1 Creating Page Parameters

Use the Parameters tab in the Composer Page Properties dialog to create page parameters.

To create page parameters:

Navigate to the relevant page, and enter page edit mode.

Tip:
One way to enter page edit mode is to press Ctrl-Shift-E.
Click Page Properties at the top left of Composer to open the Page Properties dialog (Figure 19-3).

Figure 19-3 Page Properties Dialog
Click the Parameters tab to bring it forward, and then click the Add a page parameter link.

The Add a Page Parameter dialog opens (Figure 19-4).

Figure 19-4 Add a Page Parameter Dialog
Enter a name for the new parameter, and then click Add Parameter.

The parameter displays on the Parameters tab with a value entry field and an Edit icon for opening the Expressions Editor (Figure 19-5).

Figure 19-5 A New Parameter on the Parameters Tab
Open the EL Editor and select from prebuilt values under Choose a value or enter a value manually under Type a value or expression.

For example, enter any of the following types of values:
- Constant—Enter a specific, fixed value.
- Page Parameter—Enter a page parameter to enable the page to take values through its URL.
- EL Expression—Enter an EL expression to enable the page to take a value expressed through Expression Language (EL). For information about EL, see Appendix B, "Expression Language Expressions."
  
  This option can provide a much more dynamic response. For example, the page could set a page parameter based on a component on the page. In this case, you would want the other components on the page to be refreshed whenever this value changed.
Click Save at the top right of Composer to save your changes.
As desired, repeat these steps to continue adding page parameters.
Click Close to exit Composer.

19.3.2 Consuming Page Parameters

In addition to wiring components to each other, you can wire them to page parameters. Page parameters are user-constructed name/value pairs for use in passing values to page components, such as task flows, portlets, and UI components.

You can create page parameters and configure task flows and portlets to consume them. This section describes how to wire a task flow with a page parameter.

Note:

Before you can take the steps outlined in this section, you must create a page parameter and provide it with a value. For more information, see Section 19.3.1, "Creating Page Parameters."

To wire a task flow to a page parameter:

Navigate to the relevant page, and enter page edit mode.

Tip:
One way to enter page edit mode is to press Ctrl-Shift-E.
Click the Edit icon on the task flow to be wired to a page parameter.

The Component Properties dialog opens.
Click the Parameters tab to bring it forward.
Click the Edit icon next to the property that takes the parameter value.

An editor opens, which you can use to provide the name of the page parameter.
Select Choose a value.
Under Choose a value, select Page Parameter from the first list, and the name of the relevant page parameter from the second.
Click OK to exit the editor.
Click OK to save your changes and exit the Component Properties dialog.

The task flow is refreshed, now displaying the result of the value passed through the page parameter.

19.4 Passing Parameter Values Through the Page URL

You can provide Expression Language (EL) expressions in lieu of other types of values to component parameters. This is discussed in Appendix B, "Expression Language Expressions." You can take this capability one step further by passing parameter values with your page URLs.

This section provides one scenario, which you can use as a model for other parameter passing situations.

To pass parameter values through a page URL:

Go to the page that contains a component to which you want to pass values through the page URL.
Edit the relevant component's properties.
Open the EL Editor for the Parameter or Display Option to which you want to pass a value.
Under Type a value or expression, enter #{param.val}.
Save your changes.
To pass a value to the parameter, append the following to your page URL:
```
?val=value
```
Where value represents the value you want to pass, for example, true, medium, or Default.