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

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 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 Also allow portlets to continue to use AJAX using portlet specific solutions Continue using resource URLs and operate within the limitations of WSRP 1.0 or WSRP 2.0 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 markup/script 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 then 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 markup/script 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 then 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 in the markup returned via a previous getMarkup request that also generated a URL 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 portlet’s markup. When the portlet’s markup is of 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. [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 …

15. Rewritten Markup Consumer supplies the function to cause the form to be submitted. …

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 } Markup Example function updateMarkup(markup) { // The first child is the markup as CDATA document.getElementById(‘message’).innerHTML = data.firstChild.nodeValue; }

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