14 Wiring Pages and Components

Use component wiring to create more complex relationships between a page and its components, synchronizing the content of a page with its components, or the content of one component to another.

Permissions:

To perform the tasks in this chapter, you must be a portal manager or a portal member with the portal-level permission Basic Services: Edit Page Access, Structure, and Content (standard permissions) or Pages: Edit Pages (advanced permissions).

For more information about permissions, see About Roles and Permissions for a Portal.

Topics:

• About Page and Component Wiring

• Wiring Events to Component Parameters

• Wiring Components and Page Parameters

• Passing Parameter Values Through the Page URL

About Page and Component Wiring

Note:

In this chapter, component refers collectively to ADF components (such as buttons), web development components (such as hyperlinks), task flows, and portlets.

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 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. 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 input is submitted. The page or fragment that requires the information can then subscribe to the various events and receive the information through the event.

Component wiring 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. This is known as contextual event wiring (events within the current context trigger the action of the event handler).

To clarify what happens when an event occurs, it helps to think of one component as the producer and the other component as the consumer. The producer component provides the data (referred to as 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 so on. How a consumer component uses the payload is specified in an event handler that was defined when the consumer component was created.

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. The following built-in WebCenter Portal task flows are pre-configured for event wiring:

• the Content Manager task flow is a consumer

• the Data Visualization task flow is both a consumer and producer when properly configured to a REST URL

The page editor provides tools for wiring pages and components through the page Parameters tab and component Parameters dialogs. You can wire pages and components together in the following ways:

• Wire events in a producer task flow or portlet to parameters in a consumer task flow (see Wiring Events to Component Parameters).

• Pass values from a page parameter to a component on that page (see Wiring Components and Page Parameters).

• Pass values to page components by specifying parameter values in the page's URL (see Passing Parameter Values Through the Page URL).

Wiring Events to Component Parameters

An event defined on a producer component has associated payload values that can be used to set the parameter values in consumer task flow or portlet components. As soon as the event is triggered, the associated parameter values are dynamically passed to the consumer task flow or portlet and can be exposed as needed.

As described in About Page and Component Wiring, application developers define component events and event handlers.

To wire an event (in a producer component) to a parameter in a consumer task flow or portlet:

1. Navigate to the page containing the producer component(s), and open it in the page editor (see Opening a Page in the Page Editor). Figure 14-1 illustrates a Data Visualization task flow producer component (list) and consumer component (pie chart) in the sample AviIntranet portal.

   Figure 14-1 Producer and Consumer Components

   

2. If the consumer task flow or portlet is not already on the page, add it.

   See Adding Components to a Page.

3. Click the View Actions menu icon on the consumer task flow or portlet, and select Parameters.

   Figure 14-2 View Actions Menu on a Consumer Task Flow

   

4. In the Parameters dialog, the settings you see are available only when there is a producer and consumer task flow on the page. For each parameter defined for the consumer task flow or portlet that you want to wire to an event:

   1. Click the Value field icon and select Event.

   2. Click the Event list, and select the event that is associated with the payload value that you want to pass to the parameter. The Event list shows all of the events that are defined for all components on the page.

   3. To specify that the consumer task flow or portlet "listens" for the event from only one producer component, click the from list and select the associated producer component. Otherwise, leave from with the default value of Any Component to allow the parameter to be set when any producer component on the page triggers the specified event.

   4. Click the payload list, and select an event payload value. This selection becomes the input value for the associated parameter, passed dynamically when the event triggers.

   For example, the event of selecting a row in a Data Visualization task flow (producer) triggers a DPRowSelection event that updates a consumer task flow. In this case, the consumer task flow is a pie chart, which refreshes with data associated with the selected row.

   Figure 14-3 Parameters Dialog for a Consumer Task Flow

   

5. Click OK and Save.

6. Test your wiring by triggering the event and observing the results in the consumer task flow or portlet.

Wiring Components and Page Parameters

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

• About Wiring Components and Page Parameters

• Creating Page Parameters

• Consuming Page Parameters

About Wiring Components and Page Parameters

Page parameters and page variables 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 the page editor at application runtime.

• Page variables contain output values that are produced by portlets. Page variables are created at application design time.

Creating Page Parameters

Use the Parameters tab in the page editor to create page parameters.

To create a new page parameter, refer to Adding or Modifying Page Parameters.

Consuming Page Parameters

You can configure a task flow component to consume page parameters.

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 Creating Page Parameters.

To consume a page parameter (wiring a task flow to a page parameter):

1. Navigate to the relevant page, and open it in the page editor (see Opening a Page in the Page Editor).
2. Click the View Actions menu icon on the consumer task flow, and select Parameters.
3. In the Parameters dialog, click the icon next to the property that takes the parameter value, then select Expression Builder to open the Expression Editor.

   Figure 14-4 The Expression Editor

   
   Description of "Figure 14-4 The Expression Editor"
4. Select Choose a value.
5. Under Choose a value, select Page Parameter from the first list, and the name of the relevant page parameter from the second.
6. Click OK to exit the Expression Editor.
7. Click OK to save your changes and exit the Parameters dialog.

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

8. Click Save.

Passing Parameter Values Through the Page URL

You can provide Expression Language (EL) expressions in place of other types of values to component parameters. 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. 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:

1. Go to the page that contains a component to which you want to pass values through the page URL.
2. Edit the relevant component's properties.
3. Open the EL Editor for the Parameter or Display Option to which you want to pass a value.
4. Under Type a value or expression, enter #{param.val}.
5. Save your changes.
6. 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.