Understanding Interwindow Communication

This topic provides an overview of interwindow communication and discusses:

  • Interwindow communication process flow.

  • Interwindow communication events and messages.

  • Interwindow communication considerations and limitations.

Interwindow communication (IWC) is a frame-to-frame messaging mechanism that enables browser window objects—such as pages or pagelets—to be aware of and react to field-level data changes that occur in other browser window objects that share the same browser session. Interwindow communication enables you to publish field-level changes as they occur so that any subscribing page or pagelet becomes instantly aware of the change and then, can act on it in real time.

Interwindow communication does not depend on any specific portal template, frame, or iframe and works throughout PeopleSoft applications in many scenarios for which you require interaction between browser window objects. You can configure interwindow communication to operate between pagelets, between the page and a pagelet, and also within the same pagelet, if necessary. Although interwindow communication is ideal for use with related content and WorkCenter pages, interwindow communication is independent of both technologies. In addition, interwindow communication does not depend on Integration Broker.

In a simple example, a dashboard includes the Employees pagelet, which contains a list of employee names. The dashboard also includes an Employee Projects pagelet, which contains the project listing for a specific employee. Interwindow communication enables you to click a name in the Employees pagelet and simultaneously have the Employee Projects pagelet retrieve the project listing for the selected employee.

In a different example, interwindow communication can be used to refresh a pagelet with data that has been updated in the database. For example, the target content area of a WorkCenter displays transactions related to the benefits enrollment process. The pagelet area of the WorkCenter includes a Benefits Summary pagelet that itemizes the cost to the employee of each benefit selection. When the employee saves a benefit selection on a transaction page in the WorkCenter, standard component processing saves the data to the database. When the server processing returns, the interwindow communication publish event fires indicating that a user action has occurred. The Benefits Summary pagelet subscribing to this event performs a full refresh to retrieve the revised data from the database.

Image: Interwindow communication example: A WorkCenter page before message publication

In the following example from a performance management WorkCenter, a publication event on the transaction page causes a full pagelet refresh in the pagelet area. The WorkCenter page displays a document for approval. After clicking the Approve button, the action of clicking the Confirm button triggers the publication of an interwindow communication message.

Interwindow communication example: A WorkCenter page before message publication

Image: Interwindow communication example: The WorkCenter page after message publication

The Steps and Tasks pagelet on the left has subscribed to this interwindow communication message and performs a full refresh after receiving the published message. The Define Criteria task in the pagelet now shows that it has been completed:

Interwindow communication example: The WorkCenter page after message publication

Interwindow communication interactions occur according to this simplified process flow:

  1. The triggering event occurs (click or change).

  2. The interwindow communication message is published.

  3. Each object (pagelet or page) determines whether it is subscribed to the message.

  4. Subscriber objects only read the message.

  5. Subscriber objects only act according to the subscription definition.

Image: Interwindow communication process flow

The following diagram presents the flow of these actions and events, which comprise the publish and subscribe process of interwindow communication:

Interwindow communication process flow

The following table presents the process flow in more detail:

Actor

Step

Description

Publisher object

1. Triggering event occurs.

User clicks a button or link or changes the value of a field that is configured for publication.

Interwindow communication framework

2. Publish the message.

A simple string formatted message is sent to the top window in the browser session—for example, that would be the homepage or dashboard window.

All objects

3. Determine whether subscribed.

All objects determine whether they are subscribed to the event.

Subscriber objects only

4. Read the message.

All objects in the window that are subscribed to the event read the message.

Subscriber objects only

5. Act according to the subscription definition.

Objects in the window that are subscribed to the event do one of the following:

  • If a full refresh is set, refresh the entire object (with URL parameters if specified). Any message data is essentially lost.

  • If a partial refresh is set:

    • If an event action is defined, refresh only the field(s) specified in the subscribing message definition with the published message data and then perform that action.

    • Otherwise, refresh only the field(s) specified in the subscribing message definition with the published message data and then submit the form data.

      Important! Submitting the form data forces a trip to the application server regardless of whether the field or component is in deferred processing mode.

Note: Interwindow processes occur after any application server interactions invoked by the user's action. For example, a publication event could be defined for clicking a link, which merely retrieves data from the database, or it could be defined for clicking a Save button, which invokes component save processing to save updated data to the database. Interwindow communication fires after the server interaction returns to the browser.

Interwindow communication involves publishing and subscribing to messages.

Triggering Events

The first half of interwindow communication is a JavaScript event that triggers the publication of a message:

  • OnChange

    The user changes a value in a field on a transaction page or pagelet.

  • OnClick

    The user clicks a button or link on a transaction page or pagelet.

Message Subscriptions

The second half of interwindow communication is the consumption of the published message by subscribing objects only:

  • Full refresh

    If full refresh is set for the object, the entire object is refreshed from the database (with URL parameters if specified). Therefore, any message data is essentially lost.

  • Partial refresh

    If partial refresh is set for the object, only the data as specified in the message definition is updated, not the entire object.

    Important! In addition, by requiring that some HTML field be identified as the acted upon field, interwindow communication ensures that a server trip is invoked regardless of whether the component or field is in deferred processing mode.

Page and Pagelet Types

This table describes the types of pages and pagelets that interwindow communication supports and the type of refresh that is available to each page and pagelet type:

Page or Pagelet Type

Description

Refresh Support

Transaction pages

The standard PeopleSoft page that appears in the target content area.

  • Partial refresh.

  • Full refresh.

Component-based pagelets

A pagelet built by using Application Designer.

  • Partial refresh

  • Full refresh.

iScript or Pagelet Wizard pagelets

The PeopleCode-based pagelets built by using Pagelet Wizard or by registering an iScript.

Full refresh.

Considerations and Limitations

Note the following considerations when implementing interwindow communication:

  • The domain for interwindow communication is the entire, visible HTML page.

    This domain includes all pagelets and active transaction pages visibly displayed, but excludes any tabbed pages of the component definition that are currently not displayed (not active). Therefore, the visible HTML page can encompass multiple component and page definitions.

  • A subscribing page or pagelet must be completely loaded or it will fail to consume a published message.

  • A field that will participate in interwindow communication must have a unique HTML field ID within this domain.

    Use developer tools in the browser to determine HTML field IDs. See Identifying HTML Field IDs.

  • Component definitions for objects participating in interwindow communication must remain in deferred processing mode.

    Page definitions and field definitions can be set to either deferred or interactive mode as needed.

  • A publishing field or a subscribing field can include FieldChange PeopleCode.

  • However, a publishing field should not include FieldEdit PeopleCode, which typically includes errors and warnings.

    An interwindow communication event will not fire on a publishing field that includes FieldEdit PeopleCode.

  • If a non-visible field is required to either publish or subscribe to an interwindow communication event, change the style of the page field properties to PTTRANSPARENT (on the Record tab in Application Designer).

    Do not set the field to invisible (on the Use tab); fields set to invisible in this manner do not get generated as part of the HTML.

  • In a modal secondary window, you cannot configure a publication event on the close icon (the "X" with id="ptModClose_0") in the upper right corner of the window.

    Instead, you must configure the publication event on a button such as a Save, OK, or Cancel button within the window.