Proposal to Address AJAX Use Cases in WSRP

Subbu AllamarajuBEA Systems Inc

WSRP F2F Meeting, May 2006

Agenda

Goals

Proposal

Pros and Cons

Open Items

Primary Goals

Support three-phase lifecycle for portlets serving AJAX requests

Process updates via performBlockingInteraction

Return and consume events

Return markup or data via getMarkup

Support state changes

Be able to cause window state/mode changes

Be able to return new navigational state, and/or shared state

Influence Other Portlets

Allow other portlets to receive events fired during AJAX requests, and update their own state and markup

Allow Consumer to Update its State

State stored in URLs

Secondary Goals

Let implementations choose the technologySpec to stay agnostic of browser limitations

Let Consumers and not portlets choose a flavor or XHR or an alternative

Also allow portlets to continue to use AJAX using portlet specific solutions

Use resource URLs and operate within WSRP 1.0 or 2.0 limitations

Specify as little as requiredAllow producers to provide value-added features

Portlet programming models (such as JSR286)

IDEs to design/generate UI

Allow consumers to provide value-added features

Browser-side coordination

Widgets and other eye-candy

Overview of the Proposal

PortletDescription Type

[O] boolean usesFragmentURLs

usesFragmentURLs

A flag indicating whether the Portlet generates markup containing fragment URLs. Fragment URLs are used to support technologies such as AJAX to cause refresh the entire or part of the portlet’s markup. Consumers not supporting such technologies may not aggregate portlets returning a value of true for this flag.

RegistrationData Type

[O] boolean fragmentURLsSupported

fragmentURLsSupported

A flag that tells the Producer whether the Consumer support fragment URLs. Fragment URLs are used to support technologies such as AJAX to cause refresh the entire or part of the portlet’s markup. Consumers not supporting such technologies SHOULD return a value of false for this flag.

wsrp-urlType = fragmentBlockingInteraction

Activation of the URL will result in an invocation of performBlockingInteraction on the Portlet that generated the markup. The Consumer is responsible for supplying the necessary means to cause submission of this URL to the Consumer by the user agent.

If activation of this URL results in rendering the portlet either via a getMarkup request of via cached markup, the Consumer MUST provide necessary means in the aggregated page to cause an invocation of the callback function specified by the wsrp-fragmentCallback parameter. If activation of this URL causes a getMarkup request, the portlet MUST generate markup of content type text/xml or a textual content type. Examples of valid content types include text/xml, text/html, text/plain.

All form parameters, submitted as query string parameters using the HTTP GET method, that are not used to encode parameters defined by this specification MUST be passed to performBlockingInteraction as formParameters.

When this parameter is specified, the URL MUST also include the wsrp-fragmentCallback parameter.

wsrp-urlType = fragmentRender

Activation of the URL will result in an invocation of getMarkup. In response, the portlet MUST generate markup of content type text/xml or a textual content type. Examples of valid content types include text/xml, text/html, text/plain.

The Consumer MUST provide necessary means in the aggregated page to cause an invocation of the callback function specified by the wsrp-fragmentCallback parameter. The Consumer is responsible for supplying the necessary means to cause submission of this URL to the Consumer by the user agent.

This mechanism permits a Portlet's markup to contain URLs, which do not involve changes to local state, to avoid the overhead of two-step processing by directly invoking getMarkup. The URL MAY specify a the wsrp-navigationalState or wsrp-navigationParameters portlet URL parameters, whose value the Consumer MUST supply in the navigationalState and navigationParameters fields of the MarkupParams structure, respectively. If there is no such portlet URL parameter, the Consumer MUST NOT supply a value for this the respective .

When this parameter is specified, the URL MUST also include the wsrp-fragmentCallback parameter.

URL Parameter: wsrp-fragmentCallback

This parameter provides the name of an ECMAScript[1] function. The Portlet or the Producer is responsible for providing the named function(s) in the markup returned via the getMarkup if that markup includes URL(s) of type fragmentBlockingInteraction or fragmentRender. The function definition MUST include one parameter.

When a URL of type fragmentBlockingInteraction or fragmentRender is activated, the Consumer is responsible for invoking this callback function with an XML element named “wsrp-fragment” containing the markup returned by the portlet.

When the portlet’s markup is of type text/xml, the wsrp-fragment element contains the markup as its only child element. When the portlet’s markup is textual, the wsrp-fragment element contains the markup as a CDATA element as its only child. Note that Consumers MAY alter/filter the contents of the portlet’s markup based on Consumers’ security policies.

[1] http://www.ecma-international.org/publications/standards/Ecma-262.htm

fragmentBlockingActionTemplate

Activation of the URL will result in an invocation of performBlockingInteraction. The Consumer MUST integrate placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrp-navigationParameters, wsrp-interactionState, wsrp-mode, wsrp-windowState, and wsrp-fragmentCallback in its template and SHOULD integrate placeholders for the other portlet URL

secureFragmentBlockingActionTemplate

secureFragmentBlockingActionTemplate is equivalent to fragmentBlockingActionTemplate, but using secure communication.

fragmentRenderTemplate

Activation of the URL will result in an invocation of getMarkup. The Consumer MUST integrate placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrp-navigationParameters, wsrp-mode, wsrp-windowState and wsrp-fragmentCallback in its template.

secureFragmentRenderTemplate

secureFragmentRenderTemplate is equivalent to fragmentRenderTemplate, but using secure communication.

fragmentDefaultTemplate

This is the template whose value is to be used as the default value for any non-secure fragment template whose value is not supplied. Consumers not supplying all the other non-secure fragment templates MUST set a value for this template. Since this may become the value for an action oriented template, the Consumer SHOULD integrate placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrp-navigationParameters, wsrp-interactionState, wsrp-mode, wsrp-windowState, and wsrp-fragmentCallback inthis template.

secureFragmentDefaultTemplate

This is the template whose value is to be used as the default value for any secure fragment template (i.e. those with names beginning with "secure") whose value is not supplied. Consumers not supplying all the other secure fragment templates MUST set a value for this template. Since this may become the value for an action oriented fragment template, the Consumer SHOULD integrate placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrp-interactionState, wsrp-mode, wsrp-windowState and wsrp-fragmentCallback in this template.

Example: URL in the Markup

Cause a performBlockingInteraction request using AJAX, and pass the response supplied callback function

<form action=“wsrp-rewrite?wsrp-urlType=fragmentBlockingAction&amp;wsrp-fragmentCallback=updateData&amp;wsrp-interactionState=someState/wsrp-rewrite” method=“POST”>

…

</form>

Rewritten Markup

Consumer supplies the function to cause the form to be submitted.

<form action=“javascript:pbia(‘http://consumer.com/portal?type=fragment&amp;wsrp-interactionState=someState’, ‘updateData’); method=“POST”>

…

</form>

Example: Callback Function in the Markup

Data Examplefunction updateData(data){ var items = data.getElementsByTagName(‘item’); for(var i = 0; I < items.length; i++) { // Process each item }}

Markup Examplefunction updateMarkup(markup){ // The first child is the markup as CDATA document.getElementById(‘message’).innerHTML = data.firstChild.nodeValue;}

Proposal Summary

ProsSupports all use casesFeature is optional

Support indicated at discovery time

Consumer can use appropriate scripting technologyMay be browser specific

Portlets can continue to use their own AJAX solutionsUse WSRP 1.0 style or WSRP 2.0 style resources

ConsPortlet can’t use arbitrary AJAX toolkit to cause getMarkup, performBlockingAction, or handleEvents

Some Known AJAX Pitfalls for WSRP

Async requests and state management

Users may submit too many async requests in succession

Consumer/browser state may become inconsistent

Caching

Consumers need to better at caching fragments independently of portlets – penalty is higher due to increased number of requests

Known caching issues in old versions of Firefox, and current IE

Error handling

Prevent portlet’s script from disrupting aggregation

Portlet-level issues

Back-button and history management - Needs developer attention

Status management – keep users informed of the status of requests

Open Issues

Is there a need to specify the name of the container element for the callback?What if the consumer wants to cause a full page refresh upon detecting a state change?

The consumer will have to first pass on the data to the callback, and then cause a browser refresh or a redirect. From the portlet’s view, this is just a render/refresh.