11 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 11.5, "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.

Oracle 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:

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.

11.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 Oracle Composer. Select a component and view its events support on the Events tab of the Component Properties dialog (Figure 11-1).

Figure 11-1 Events Tab in the Component Properties Dialog

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

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

11.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:

11.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 WebCenter Spaces application. To bring custom task flows into WebCenter Spaces, you must first portletize them, so that they can be consumed by WebCenter 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 event triggering and parameter passing are supported in a custom task flow, any wiring you undertake is done in Oracle Composer's Component Properties dialog. The events and parameters that you configure vary according to the functionality that developers build into custom task flows.

In a custom WebCenter application, open Oracle Composer in the manner designed for that application.

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 check box.

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 Oracle Composer to save your changes (Figure 11-4).

In a custom WebCenter application, open Oracle Composer in the manner designed for that application.

Click the Edit icon on the portlet that produces the payload to be consumed.

The Component Properties dialog opens.

Click the Display Options tab to bring it forward.

Copy the value in the Id field, and click OK.

You use this value later to ensure that changes in this portlet cause the consumer portlet to refresh.

Click the Edit icon on the portlet that consumes the payload provided by the producer portlet.

The Component Properties dialog opens.

Click the Display Options tab to bring it forward.

In the Partial Triggers field, paste the portlet ID you copied earlier and click Apply.

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.

Events associated with the producer portlet contain the same ID that you pasted into the Partial Triggers field.

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 Oracle Composer to save your changes (Figure 11-7).

11.2.3 Wiring a UI Component to a UI Component

Log in, and go to the page on which to wire two user interface (UI) components to each other.

Open Oracle Composer in the manner designed for your WebCenter application.

Click the Edit icon on the UI component 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 UI component 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 check box.

Select the type of value to use to deliver the payload from the producer UI component to the consumer UI component whenever the event occurs.

Choose from:

Constant—Select Constant, and enter a constant or EL expression value to pass to the consumer UI component.

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 Oracle Composer to save your changes (Figure 11-9).

In a custom WebCenter application, open Oracle Composer in the manner designed for that application.

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 check box.

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 Oracle Composer to save your changes (Figure 11-12).

In a custom WebCenter application, open Oracle Composer in the manner designed for that application.

In the task flow header, click the Edit icon.

The Component Properties dialog opens.

Click the Display Options tab to bring it forward.

Copy the value in the Id field and click OK.

You use this value later to ensure that changes in this task flow cause the portlet to refresh.

Click the Edit icon on the portlet that consumes the payload provided by the producer task flow.

The Component Properties dialog opens.

Click the Display Options tab to bring it forward.

In the Partial Triggers field, enter the task flow ID you copied earlier and click Apply.

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

The event contains the same ID that you pasted into the Partial Triggers field.

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 Oracle Composer to save your changes (Figure 11-15).

In a custom WebCenter application, open Oracle Composer in the manner designed for that application.

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 check box.

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 Oracle Composer to save your changes (Figure 11-18).

11.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 Oracle Composer at application runtime. Page variables contain output values that are produced by portlets. Page variables are created at application design time.

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 Oracle Composer to save your changes (Figure 11-25).

11.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.

11.4.1 What You Should Know About the Parameter Form and Display Portlets

The Parameter Form and Parameter Display portlets provide a quick and easy way to pass values between components. They are provided by the WSRP Tools producer.

Note:

The Parameter Form and Parameter Display portlets are available in your application only if your application administrator has registered the WSRP Tools producer with the application. If you cannot see these portlets, contact your administrator (for more information, see Section 2.8, "Contacting Your Application Administrator").

The Parameter Form portlet (Figure 11-28) has three output parameters that are set when values are submitted in the form inside the portlet. The parameters can then be used to drive the content of other portlets. You can customize the Parameter Form portlet to determine how many of the three fields are displayed on the form, depending on how many parameters you require.

Figure 11-28 Parameter Form Portlet

The Parameter Display portlet (Figure 11-29) enables you to quickly test the wiring from the Parameter Form portlet. However, typically you use the values passed from the Parameter Form portlet to drive the content of some other portlet—for example, to pass a ZIP code to a weather portlet, or a stock symbol to a stock ticker portlet.

Figure 11-29 Parameter Display Portlet

11.4.2 Adding the Parameter Form and Display Portlets to a Page

The Parameter Form and Parameter Display portlets are available in your application only if your application administrator has registered the WSRP Tools producer with the application. If you cannot see these portlets, contact your administrator (for more information, see Section 2.8, "Contacting Your Application Administrator").

11.4.3 Customizing the Parameter Form Portlet

You can customize the Parameter Form portlet to give it a more meaningful title and to determine the number of fields displayed (up to a maximum of three).

Figure 11-30 shows a Parameter Form portlet that has been customized to display a single field that is used to provide a zip code that can be passed into a weather portlet.

Figure 11-30 Customized Parameter Form Portlet

To customize the Parameter Form portlet:

Log in, and go to the page that contains the Parameter Form portlet.

From the portlet's Actions menu, select Customize.

In the Title field, enter a title to describe what the portlet is for.

In the Parameter 1 Prompt field, enter text to describe what data you want users to enter into the field.

You can clear one or both of these fields if you do not want them to display in the portlet.

Click OK.

11.4.4 Wiring the Parameter Form and Display Portlets

You can pass the values set in the Parameter Form portlet to the Parameter Display portlet to see how the wiring works. Typically, however, you use the Parameter Form portlet to pass data to some other portlet.

To wire the Parameter Form and Parameter Display portlets:

Log in, and go to the page that contains the Parameter Form and Parameter Display portlets.

In WebCenter Spaces, select Edit Page from the Page Actions menu.

In a custom application, open Oracle Composer in the manner designed for that application.

In the Parameter Form portlet header, click the Edit icon.

The Component Properties dialog opens.

Click the Display Options tab to bring it forward.

Make note of and copy the value in the Id field, and click OK (Figure 11-31).

You use this value later to specify page variables and to ensure that changes in this portlet cause the Parameter Display portlet to refresh.