Proposal to Address AJAX Use Cases in WSRP

1. Proposal to Address AJAX Use Cases in WSRP WSRP F2F Meeting, May 2006 Subbu Allamaraju BEA Systems Inc

2. Agenda • Goals • Proposal • Pros and Cons • Open Items

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

4. Secondary Goals • Let implementations choose the technology • Spec 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 required • Allow 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

5. Overview of the Proposal

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

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

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

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

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

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

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

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

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

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

16. Example: Callback Function in the Markup • Data Example function updateData(data) { var items = data.getElementsByTagName(‘item’); for(var i = 0; I < items.length; i++) { // Process each item } } • MarkupExample function updateMarkup(markup) { // The first child is the markup as CDATA document.getElementById(‘message’).innerHTML = data.firstChild.nodeValue; }

17. Proposal Summary • Pros • Supports all use cases • Feature is optional • Support indicated at discovery time • Consumer can use appropriate scripting technology • May be browser specific • Portlets can continue to use their own AJAX solutions • Use WSRP 1.0 style or WSRP 2.0 style resources • Cons • Portlet can’t use arbitrary AJAX toolkit to cause getMarkup, performBlockingAction, or handleEvents

18. 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 get 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

19. 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. • What is the expected behavior when a portlet returns a redirect URL • Should the Consumer send redirect headers to the browser? • XHR will follow redirect, but redirect response will be dispatched to the consumer’s script, which may not be able to understand the response. • Alternative – consumer does a GET on the redirect URL, captures the response, ands aggregate it with consumer’s updates, and then sends it to the browser • Updates from pbia/handleEvents • Mode and window state changes – what is meaning of such a change when the request is for a fragment? • Preferred title from markup – what is the meaning?