ShowTable of Contents
Table of Contents |
Previous Page |
Next Page
Web 2.0 is a term that has many aspects. Of course one aspect is the technology that can be used to generate the next generation of web based application and services. In addition, Web 2.0 encompasses new approaches to IT such as services as a product and cloud computing. It also covers business models and trends that are being used to gain competitive advantage such as self-established communities, user contribution and allowing users to take control and customize applications.
How do Web 1 0 and Web 2 0 sites differ
In the Web 1.0 scenario, the web master runs the site and the human users consume it. The Web site provides information and services, although the amount of information/content is relatively small. The information flows in only one direction and is organized into a fixed taxonomy.
Conversely, in the Web 2.0 scenario the information flow is bidirectional. The Web site provides content and applications, but now the users collectively contribute to the Web site in addition to consuming it. They do this by creating, editing and rating content. This results in a much larger amount of information and content that is categorized with flexible tagging. Users of the Webs site are not limited to humans; other applications can also be consumers.
Separating user interface from services
A traditional J2EE Web 1.0 application follows a pattern of request from the browser with a full page response from the server:
Since browsers became capable of making asynchronous HTTP requests, the pattern for Web 2.0 applications has changed. The browser makes requests to one or more services and the Web page can be updated partially with the result of each service.
Providing fine grained services like this brings the possibility to create new breeds of application such as mashups.
Web 2 0 technologies
At a technical level, the services are often created leveraging technologies such as REST (Representational state transfer), JSON (JavaScript Object Notation), and consumed by Ajax (Asynchronous JavaScript and XML) applications. These concepts are well documented elsewhere and are not specific to Portal so are only briefly summarized below:
- REST - a server side architectural model that relies on the semantics of the HTTP protocol to provide access to services. This makes such services very easy to consume in browsers (or other clients) and hence they are very popular in the context of Web 2.0 applications using Ajax. REST provides a resource-oriented approach to services, as opposed to a Remote Procedure Call (RPC) centric approach. For example, all resources are addressable through relative URLs, for example /riverblend/employees or /riverblend/employees/Michael.
- JSON - often the payload returned by a REST service when being consumed by a Web browser. The service may emit alternative payloads for different clients such as XML, RSS or ATOM. JSON is the native format of JavaScript that makes it very easy to consume in Ajax applications. The JSON payload can be directly assigned to a JavaScript object providing easy access to its data structure. Compare this to calling a Web service from a browser. While this is technically possible, it is much more difficult for the browser to manage the XML response as constant navigation of that XML document object model would be required.
- Ajax - a programming pattern for creating richer and more responsive Web pages. It is often used to build Web clients in a Service Oriented Architecture allowing the browser to directly access services deployed to any kind of server. Ajax is built upon existing open technologies and standards such as JavaScript and XML and does not require any proprietary browser plugins. Because more computation is done in the browser, an Ajax application can reduce the load on the server. A key feature of Ajax is the ability to make an asynchronous request from the browser, and update part of the page with new markup when the call returns.
- Dojo - an Open Source DHTML toolkit written in JavaScript. It is very useful for developing Ajax applications with rich user interfaces as it simplifies JavaScript development and provides reusable user interface widgets. Dojo is used in WebSphere Portal to provide Web 2.0 features. It is an IBM supported toolkit for creating custom portlets that require Web 2.0 features.
Some of these technologies will be explored in more detail in the case study later in this chapter that demonstrates how to develop portlets with Web 2.0 features.
Considerations for using Web 2 0 with Portal
When a page is updated with an Ajax request, the URL in the browser toolbar is unaffected. This can cause problems for standard Web browser features that rely on the URL to rebuild the page. For example, back and forward buttons, bookmarking, reverse proxy caching and crawlability could all be affected if an Ajax request had modified the page. These problems are valid for both Web and Portal applications. However, in Portal, the problem is even more prevalent due to the fact that a Portal page is an aggregation of several applications (usually portlets).
The URL for a Portal page includes information about navigational state. The navigational state includes information about the entire page (page selection, theme template, and so on) and information about all portlets including their rendering parameters. Therefore if a single portlet used Ajax to update its view, all links held in that portlet and all other portlets would conceptually need to be updated to encapsulate the changed view. One way to tackle this problem is to use a Portal aware JavaScript library that can manage URLs. This feature will be explained in detail later, but for now let’s summarize how it can be used to address the challenges introduced in this section:
| Capability | Portal Web 1.0 | Portal Web 2.0 |
| Bookmarking | A user can create a browser bookmark from any link on a page. Each link contains the latest navigational state of all portal artifacts visited so far. | This can be supported with a special "Bookmark this page" link. A user would have to select this link which asynchronously invokes a server side method to return a URL that is ‘bookmarkable’. |
| Browser Back/Forward/Reload | A user can navigate using the browsers back, forward and reload button with the expected behavior (for example, like static html pages). | Javascript Frameworks such as Dojo support back and forward button in a limited fashion. They enable back and forward events to be captured by the portlet which can maintain its own history of URLs. However this will not be reflected in the browser history as would be expected in Web 1.0. |
| Browser and Reverse Proxy Caching | The full portal page is cached in a reverse proxy or browser cache. The page expiration is calculated by Portal to be the shortest expiration of all artifacts on the page. | Using the Portal JavaScript API, each artifact on the page is loaded on demand from within the browser. Therefore, the reverse proxy and browser cache hold each artifact individually gaining the maximum benefit from caching. If an artifact never expires it will not be loaded again with follow-on requests. The caching potential is actually increased with Web 2.0 compared with Web 1.0 where the whole page would expire after the portlet with the shortest caching time had expired. |
| Crawlability | The markup that is returned from a portlet is analyzed by the search engine. The best practice is to return special markup with ‘normalized URLs’ when a portlet is accessed by a search engine (see the search chapter of this wiki). | Depending on the extent of Ajax usage, this could be tricky to achieve as current internet search engines do not understand JavaScript.
If the Portal simply renders a 'bootstrap' page that then loads each portlet with Ajax, the search engine will not understand this and the portlet content will not be crawled. This limitation should be considered when comparing Portal's server side and client side aggregation themes (discussed later). |
WebSphere Portal Web 2 0 features
WebSphere Portal leverages the Web 2.0 technologies mentioned in the previous section to provide new out of the box Web 2.0 features and capabilities. The following topics will be expanded upon in this section.
- Portal REST Services
- Client Side Aggregation (CSA) Theme
- Ajax Proxy
- Semantic Tagging with Live Text API
- Google Gadgets
- Lotus Mashups
- Client side feed consumption
Portal REST services
Portal provides a rich catalog of REST services to facilitate remote access to core portal data. They separate the portal user interface from the portal data.
The REST services are all public APIs and can be accessed from Portal applications running within the WebSphere Portal framework and Web-based applications, external to the Portal. GET, POST, PUT and DELETE HTTP methods are supported via a URL addressable interface.
- Content Model - Allows you to obtain and modify the content topology and the properties of content nodes such as pages, labels, and content URL’s.
- Layout Model - Allows you to obtain and modify the layout of a page, that is, the topology of layout elements of a page, and the properties of layout elements, such as layout containers and layout controls.
- Navigation Model - Allows you to obtain the navigation topology only, as the navigation model is implied by the structure of the content model.
- Portlet Model - Allows you to obtain, create, update, and delete portlets.
When accessing a REST service to get information or to modify a portal resource, the response and in these cases also the request works by means of a feed. A feed contains information about one or more portal resources in a specific format as exposed by portal models.
In order to obtain a feed that contains certain portal resources, send an HTTP GET request to the following URL.
/wps/[my]contenthandler[/<vpmapping>]?[uri=<model-uri>]+[&mode=<verb>]?[&name=<value>]
- contenthandler - The name of the servlet for unauthenticated access. This is the equivalent to /wps/portal/, where anonymous access is allowed.
- mycontenthandler - The name of the servlet for authenticated access. This is the equivalent to /wps/myportal/, where only authenticated acess is allowed
- vpmapping - The optional name of the URL mapping to a virtual portal. If no mapping is given, the default virtual portal is assumed, otherwise the ID of the addressed virtual portal is associated with the current thread.
- model-uri - The identification of the addressed resource, as described further below. The uri parameter can appear only once.
- page-oid - This is the portal object ID of a content page. When you address portlet model resources, this is required for portlet windows, but it must not occur for any other portlet model resource identification.
- navigationnode-oid - This is the object ID of a navigation model node.
- layoutnode-oid - This is the object ID of a layout model node.
- portlet-oid - This is the object ID of a layout control, portlet window, portlet entity, or portlet definition.
- oid - This is the serialized string that represents a portal object ID. This is URI-escaped with UTF-8 encoding. The character @ is also escaped by using %40. You can also use unique names instead of object IDs. Unique names also have to be URI-escaped, and the @ character must be escaped. Note that every object ID has the defined scheme 'oid:'.
- verb - An optional specification for the mode of access. By default mode=download is assumed.
- value - An arbitrary set of parameters. These include additional query parameters. For details refer to the topics further below.
If modifying an existing portal resource it is recommended to send an HTTP GET request and first retrieve that portal resource. The response will be an existing XML feed of a page which can then be edited and used as a template for changes. It will also come in handy if there is a need to backup to a previous version.
To obtain a feed of the layout node with the object id '_7_0830M4HTFF0SHFCQ_2BV' on the content page with the object id '_6_0830M4HTFF0SHFCQ_4D', send an HTTP GET request to the following URL:
/wps/mycontenthandler?uri=lm:oid:_7_0830M4HTFF0SHFCQ_2BV@oid:_6_0830M4HTFF0SHFCQ_4D
Client side aggregation themes
Client side aggregation (CSA) is the new aggregation model that provides an improved user experience through faster response and performance. Themes that are CSA enabled are rendered from JavaScript and XSLT transformations that are executed on the client. CSA considers portlets as fragments that are reloaded individually. There are two main advantages for using a CSA enabled Portal theme:
- Improved user experience by eliminating full page refreshes. Only individual portlets are refreshed as users navigate a page.
- Improved server-side performance and scalability.
- Reduced Server-side processing - rendering workload is off-loaded to the browser.
- Reduced bandwidth requirements between the server and browser.
- Improved HTTP caching - all artifacts can be cached independently.
- Reduced client side processing - fragmented reloads, fewer full-page reloads
The PortalWeb2 theme should be used as the starting point for all CSA themes. Make a backup copy of this first and then gradually adopt the existing PortalWeb2 theme. Portal themes are located in the following directory:
<was_profile_root>/installedApps/<cell_name>/wps.ear/wps.war/themes/
The PortalWeb2 theme directory structure is described in the figure above. The CSA theme makes heavy use of the dojo APIs; therefore it is packaged separately, under the dojo directory to keep the main complexity outside of the PortalWeb2 theme.
The CSA theme should always support the server side aggregation (SSA) framework. Not every portlet will work with CSA due to JavaScript conflicts, non-standard coding practices, or insufficient browser capabilities.
SSA mode can be enforced via:
- A portlet initialization parameter in portlet.xml
- com.ibm.wps.web2.renderMode=force_SSA
- Page parameter / meta data in edit page properties
- RenderMode = force_ssa
- Portlet blacklist (../themes/PortalWeb2/js/portletsForServerSideOnly.js)
- Add the portlet definition UID (defined in portlet.xml) to the list
Portal versus PortalWeb2 theme
The CSA enabled theme is not much different from the SSA theme; a few files were added or modified. When a CSA theme is rendered, a skeleton HTML document containing placeholders is rendered first. A JavaScript bootstrap function gets called after the skeleton finishes loading. This bootstrap process calls the CSA framework to initiate the CSA rendering process that replaces the placeholders with HTML markup.
The modified files are as follows:
- head_extras.jspf - Initializes CSA and initiates bootstrap
- js.jsp - Loads the CSA specific libraries such as dojo
- status_bar.jspf - Defines HTML anchor for the status bar
The new files and folders are as follows:
- xsl folder - Contains XSL templates producing the widget markup
- CSAProperties.jspf - Loads resource bundle strings needed by CSA
- head_themePolicy.jspf - Stores current theme policy in a javascript variable
Ajax proxy
The Ajax Proxy is a server side component that acts as a http forwarding proxy, which can be used to control access and route requests to different domains. It allows security administrators to control portlet access to external domains.
To prevent cross site scripting in such Web applications, browsers introduced the so called same-origin policy. This policy prevents client side scripts, in particular JavaScript, from loading content from an origin that has a different protocol, domain name, or port.
The proxy configuration can be set as global or application specific.
- A global proxy configuration applies to every application deployed on the portal, regardless if the application has its own proxy configuration file. In large deployments with many deployed portlets, using only the global proxy configuration creates less administration overhead. In such environments, application specific configurations can create more administration overhead due to the fact that a security administrator needs to maintain multiple proxy-config.xml files spread across different WAR and EAR files.
- In the application specific proxy model, each portal application packages its own proxy configuration file. The portal application proxy takes precedence over the global proxy configuration.
The application specific proxy configuration is specified in a proxy-config.xml file, that must be placed in the WEB-INF directory of the portlet WAR file.
The global proxy configuration is also in a proxy-config.xml file. This file is located within the WEB-INF directory of the wp.config.proxy.war file in an EAR called AJAX Proxy Configration.ear. See below:
<profile_root>/installedApps/<cell_name>/Ajax Proxy Configuration.ear/wp.proxy.config.war/WEB-INF/proxy-config.xml
To enable the global proxy configuration specify the following configuration setting in the portal Config Service.
proxy.enforce.global.config = true
The following link details the process of modifying the ConfigService:
http://publib.boulder.ibm.com/infocenter/wpexpdoc/v6r1/index.jsp?topic=/com.ibm.wp.exp.doc_v6101/admin/adsetcfg.html
To update the global proxy configuration, redeploy the enterprise application archive that contains the modified proxy-config.xml file and restart it. You do not need to restart the entire portal server.
When a request is received by the Ajax Proxy, the proxy locates a corresponding policy url. The asterisk (*) in the above example denotes that requests for any target URL is accepted. However, only GET and HEAD HTTP requests are allowed.
In the configuration above, GET, HEAD, POST, and PUT HTTP requests are allowed solely for the
http://www-01.ibm.com/software/lotus/ URL and sub-paths below it.
Meanwhile for
http://www.cnn.com/, a user must be authenticated, and only GET and HEAD requests are allowed. In addition, only the specified cookies and mime-types will be accepted by the proxy.
How the Ajax proxy works
- A user accesses a portal page with a portlet on it that requires markup from an external datasource.
- Portlet renders through on a portal page.
- The JavaScript code from the portlet application attempts to access an external site (for example: www.cnn.com) through a well defined URL pattern.
- The Ajax proxy applies its security check.
- If the domain is a trusted domain then the request is forwarded to the target server at the target domain.
- When the request is returned from the target domain, it gets passed through the server back to the browser.
Semantic tagging with Live Text API
Live Text provides elements embedded in portal pages that become active in the browser and are enhanced with additional functionality by JavaScript libraries. For example, if you include portal user IDs in your portlet output and mark them as live text, users can click on these IDs in the browser and see a person’s information card or a context menu that allows them to send an e-mail to the person, initiate a chat, view their blog, or make use of many other extensible menu-option features.
Live text has the following advantages:
- Live Text triggers can be declared by any HTML fragment on a page, including portlets, theme components or simple HTML clippings.
- Adopt new portal content within your company more easily, as it is now easier to handle portal tags. For example, you can write tags and make them available centrally, and UI developers can reuse these tags for in their portlets for various purposes.
- Content editors can add meaningful live text elements to portlets without requiring portlet development knowledge.
- Embed content from other sources, for example, from a HTTP or .NET server.
The figure above is an example of semantic tagging. Clicking on a live text enabled name above renders a person card with a menu of actions.
Google Gadgets
IBM Portlet for Google Gadgets is a JSR 168 portlet that enables WebSphere Portal users to integrate Google Gadgets for Web pages with their portal pages. Google Gadgets for Web pages are remotely accessible services that provide access to online content and applications designed to be aggregated into the context of a Wweb page. These include language translators, maps, YouTube videos, and Wikipedia. A full listing of the 15,000+ available gadgets can be found here:
http://www.google.com/ig/directory?synd=open
The Google Gadget portlet has been updated to facilitate inter-portlet communication. Data can be exchanged between the IBM Portlet for Google Gadget portlet instances and other portlets. This feature enables other portlets on a page to interact with the selected gadget(s). The gadget portlet reacts in response to an event triggered in a different portlet. For example, a user clicks on the name of a city in a portlet application. The portlet application, sends, transparent to the end-user, the city information to a Weather Google Gadget portlet. The weather gadget then automatically shows the current conditions for that city.
The figure above is a picture of the Google Gadget selection interface within WebSphere Portal.
Lotus Mashups
A Mashup is a lightweight web application created by combining information or capabilities from multiple existing sources to deliver new functions and insights. IBM Mashup Center is a lightweight mashup platform, supporting line of business assembly of simple, flexible, and dynamic web applications with the management, security and governance capabilities IT requires.
Below is a list of advantages of using Lotus Mashup Center
- Assemble applications by reusing existing services
- Unlock Enterprise, Web, Personal and Departmental Information
- Create interactive widgets that encapsulate existing services
- Discover and share mashups, widgets, and feeds
- Transform and mix information into new feeds
- Explore different combinations to uncover new insights
The figure below is an example of a business application created using IBM Mashup Center.
Lotus Mashups integration into Portal
IBM Lotus Mashup Center is a platform for rapidly creating, sharing, and discovering reusable assets called widgets. Mashups consist of one or more widgets. Widgets can run within the context of WebSphere Portal using any of the following deployment options.
- Deploy widget to WebSphere Portal via a pre-built, reusable JSR 168/286 portlet. This portlet is available on the WebSphere Portal Business Solution catalog here:
http://www-01.ibm.com/software/brandcatalog/portal/portal/details?catalog.label=1WP1001PI
The WebSphere Portal Widget Portlet provides customizable, personalized, and managed access to widgets that are compliant with the iWidget Specification, thus extending the existing capabilities of WebSphere Portal to provide flexible integration with web components, independent of their technology. With the IBM WebSphere Portal Widget Portlet, users can leverage widgets from Lotus Mashup Center on their portal pages side by side with portlets, Google Gadgets or other web components, enabling the creation of portal-based mashups tailored to the situational requirements of an enterprise.
The Widget Portlet provides the following widget integration capabilities. A widget can be added to Portal by:
- Pointing at a URL
- Browsing the Lotus Mashups Toolbox
- Browsing the Mashup Center Catalog
The screenshot above displays this interface as seen in WebSphere Portal.
- Deploy a widget locally to WebSphere Portal
If a widget is implemented as a J2EE components, which are typically Web archive (WAR) files containing components like servlets, portlets, HTML pages and others, they can be deployed to WebSphere Portal. e following steps list the procedure to deploy a widget from Lotus Mashup Center and install it natively on WebSphere Portal.
- A portal administrator downloads the widget from the IBM Lotus Mashup Center catalog as a WAR file.
- A portal administrator deploys the WAR file using the WebSphere Application Server administration interface.
- A portal administrator uses the Widget Portlet to integrate the locally deployed widget as a portlet.
- Display widgets and mashups in any web page (Portal or non-Portal)
With a few simple clicks widgets and mashups created in IBM Mashup center can be displayed in any web page. In this scenario the widget or mashup still resides on the Mashup server. The hosting web page the knows to call the Mashup server through a script tag added to the web page source.
The figure above from Mashup Center shows how a user can create the one-line script to be inserted into a web page where the mashup or widget is to be displayed.
Widgets in the Mashup Center toolbox can also be embedded into web pages with this same technique.
- Promote Mashups to WebSphere Portal. (future capability)
In early 2010, users will be able to install their Mashups on WebSphere Portal from IBM Mashup Center with the click of a button. It will no longer be necessary to manually export the Mashup as a WAR file. This high-level process is described in the figure below.
Ajax portlet development
Portlets are reusable Web modules that can be developed separately providing access to Web-based content, applications, and other resources. Portlets are intended to be assembled into a larger portal page, with multiple instances of the same portlet displaying different data for each user. Portlets can use different technologies (DHTML, IFrames, Plugins or even Applets) and leverage Ajax/Rich Internet Application (RIA) techniques and libraries directly, or encapsulated in frameworks.
Portal Ajax scenarios
In a portal, Ajax is typically used to enhance the user experience with two scenarios:
1. Data retrieval
In this scenario, the browser client makes an asynchronous request to load data using a data encapsulating protocol such as XML or JSON. JavaScript is used to processes the data and update a view component. This update is displayed without reloading the whole page. Examples of this scenario are:
- Typeahead feature - A user enters text into a text field and receives a list of alternatives about the entered text.
- Refreshing stock quotes - A portlet displays the latest stock quotes every five minutes.
2. Markup Retrieval
As an alternative to loading data, the client can load markup (e.g. HTML) and apply it directly to DOM elements of the current page.
An example of this scenario:
- A link or button is clicked on the page that triggers an asynchronous request to load markup from the server. The markup is received and is used to directly replace the current view of a DOM element.
Approaches to AJAX portlet development
Ajax support in portlets differs depending on which Java Portlet Specification level being used:
- JSR 168 - Ajax is supported and the most common use cases use external servlets to provide a data source for serving markup or data.
- JSR 286 - Introduces a new feature called resource serving that enables portlets to serve independent markup within the portlet context using resource requests.
At each specification level, there are alternative design patterns that can be considered.
JSR 168 portlets
Ajax support in JSR 168 is provided through a servlet implementation. In this scenario, the portlet WAR file packages one portlet and one servlet. The servlet acts as a proxy that connects the portlet to an external data source. This servlet is needed because there is no way to address the portlet directly to retrieve fragments of data or markup. The servlet is packaged in the same WAR file so the servlet and portlet can exchange data using the HTTP session (application scope). For example, in response to an asynchronous browser request, the servlet might access an email id in session, and return an email message.
This Ajax scenario can be used to update backend data or clean server-side caches if necessary. However this scenario has some limitations:
- The Ajax call cannot use portlet APIs or affect the portlet state.
- View changes are typically lost in case of a full page refresh.
- Implementation of the servlet could be complex, particularly if it is used to connect to several different data sources.
- The servlet actually needs to act like a HTTP proxy which requires handling of cookies, redirects, request /response headers etc.
Be aware that more that one portlet instance can coexist in the same page so avoid conflicts in library versions, callback functions, variable names and avoid loading JavaScript libraries more than once. Some techniques to achieve this will be demonstrated in the case study.
The simplest approach for Ajax handling is to use Portal's Dojo implementation which is included in the default themes. WebSphere Portal contains an instance of the IBM Dojo Toolkit, a JavaScript library based on the Dojo toolkit (
http://dojotoolkit.org). The bundled Dojo is packaged in the
/installedApps/node_name/wps.ear/wps.war/themes/dojo/portal_dojo directory. It is intended to be usable by both IBM and non-IBM components. Dojo is used in Portal’s themes so in order not to adversely affect them, it is important to refer to the guidelines in the Portal InfoCenter and adhere to best practices on how to use Dojo in portlets. More information on this can be found at:
http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/topic/com.ibm.wp.ent.doc_v6101/dev/dojo_overview.html
JSR 268 portlets
This version of the portlet standard introduced resource serving, a key capability for Ajax development. This enables portlets to serve resources, for example, markup or data, from within the portlet context using resource requests. This means a separate servlet is no longer required and encourages a better programming model.
The new callback interface is triggered by resource URLs and the portlet has a new method: serveResource(ResourceRequest, ResourceResponse). Resource serving allows portlets to render stand-alone content with no portal page aggregation, no theme content and give the portlet full control of the entire output while maintaining access to portal APIs and state data, such as the portlet session.
Resource serving can be used to implement scenarios like generating binary content (PDF, SVG, and so on) from a portlet, to be displayed in pop-up windows. For other Ajax use cases, resource serving portlets have a way to return XML, JSON, HTML fragments or any other content.
The main advantages over the servlet scenario are:
- Ajax requests can now be handled inside the portlet where there is access to Portal API, session, and so on.
- Current state (navigational state, preferences, portlet session) can be accessed.
- Updates can be made to the portlet preferences or session via a POST request.
However there are some limitations to resource serving as it is not possible for the serveResource method to update navigational state or send events to other portlets. We will see how to overcome these limitations in the next section concerning the Portal client side programming model.
Client side portlet programming model
While most portlet Ajax scenarios can probably be addressed using JSR286 resource serving, the most flexible Ajax support requires coordination between portlet and Portal. To achieve this, Portal provides an Ajax library for portlets that allows server side features to be updated from the client. This includes a mechanism to update portlet preferences, navigational state or send events. Thus changes made in the client with Ajax are retained even if the user clicks outside the current portlet.
Accessing the API
This is a short summary of the main JavaScript API classes and methods. You can find a full copy of the API documentation at: http://download.boulder.ibm.com/ibmdl/pub/software/dw/wes/0608_wp6javadoc/portal_61js.zip
ibm.portal.portlet.PortletWindow
This object is the entry point to the API providing JS functions access to the outlined functionality and defining useful constants for portlet modes, window states, response status and errors.
ibm.portal.portlet.XMLPortletRequest
This object provides XMLHTTPRequest functionality for portlets.
ibm.portal.portlet.PortletState
Allows portlets to work with the render parameters, portlet mode and window state (navigational state) of the portlet window.
Changes are persisted when calling setPortletState() on the PortletWindow object.
ibm.portal.portlet.PortletPreferences
Allows portlets to work with the configuration data (persistent state) of the portlet. Modifiable and read-only preferences are distinguished according to the portlet mode. Changes are persisted when calling setPortletPreferences() on the PortletWindow object.
Ajax portal tooling
Rational Application Developer v7.5 contains Portal tooling to support Web 2.0 features:
- JSR 286 support for creating portlets that perform resource serving
- Client-side programming model support. The new portlet wizard provides an option to import and initialize the client side programming libraries.
- Client-side click-to-action support. Automatic code generation is available to enable cooperation between portlets using client-side click-to-action.
- Person tagging support. Automatic code generation is available to create the Person menu, and extend the Person menu by writing JavaScript actions.
- Ajax proxy tooling is available to enable and configure this HTTP proxy for portlet projects.
Portal Web 2 0 case study
In this section some of the portlet development scenarios described previously will be demonstrated:
Case study scenario
The River Bend coffee company now offers a ‘Farmers Market’ facility where customers can learn about the origins of their coffee products, and add individual coffees to a custom blend. The facility is aimed at both ethical coffee buyers who wish to support certain famers, or coffee connoisseurs who wish to create custom blends.
Applying the PortalWeb2 theme to an existing Portal page or portlet
In this scenario, the difference between server side and client side aggregation will be demonstrated. In the attachments to this wiki page you will find a Web module that can be imported into Portal. It contains two portlets that provide a basic realization of the case study scenario.
After importing the Web module, the portlets should be added to a page with the portal theme "Portal" that provides traditional server side aggregation. A wire should then be created to enable the inter-portlet communication. The wire is added by selecting from the drop down lists, clicking the "+" button, then clicking Done:
These portlets provide typical Web 1.0 functions:
- Users can page through the fifteen available coffee products from three different farmers.
- Products can be added to the shopping basket.
- The farmer’s name can be clicked to display more detailed information in the farmer details portlet. This uses JSR286 events to perform the inter-portlet communication.
Note that the farmer details portlet intentionally takes a few seconds to respond to simulate a backend call that causes a ‘white screen’ effect. This could be reduced by moving the pause to the processEvent method instead of doView. However, the time taken to load the page where the user cannot perform any functions is the same.
All these functions result in a full round trip to the server with a page refresh. Note that as the navigational state is managed by the server, the render parameters always maintain information about which page is currently being viewed. The same page is always displayed, for example after adding a product to the basket. This is a subtle but important feature we will strive to maintain when discussing addition of Web 2.0 features in the case study.
The full page refresh of the Web 1.0 portlets does not provide a very satisfying user experience as the user sees a blank screen after paging, or viewing farmer details. In addition, with every operation the full page refresh means the server must render all portlets even if only one has changed.
Portal’s Web 2.0 theme can provide a simple way to introduce Web 2.0 features without requiring any code changes to existing portlets. Change the Portal theme for the page containing the two portlets:
Now the user experience is improved as a click on the farmer name will result in the farmer details portlet updating its view independently of the coffee list portlet:
Also note that after adding a product to the basket or refreshing the page, the list of products does not default to the first page but shows the previously displayed page. This is due to an important feature of the Portal Web 2.0 theme that uses the Portal JavaScript library to automatically update navigational state. The portlet maintains a paging offset value as a hidden parameter in its form. The portlet stores this as a render parameter when the form is submitted during the action phase. This render parameter is then used to shift the starting page of the products during the rendering phase. After clicking the paging links, even though there is no page refresh to update the render parameter with the new page offset, the Portal Web 2.0 theme does this automatically.
Using client side Click to Action semantic tags and JSR286 Resource Serving with Server Side Aggregation
In this scenario, Portal’s semantic tags will be used to provide client side ‘click to action’ function, even when using a server side aggregation theme. In the attachments to this wiki page you will find a web module that can be imported into Portal. It contains an evolution of the two case study portlets. Replace the existing portlets by clicking Administration->Portlet Management->Web Modules. Search for the web module and click the update icon (the icon with arrows):
Modify the page on which the portlets are deployed to use the default Portal theme:
First let’s check the modified behavior of the portlets before investigating the code updates. The portlets were tested with IE7 and Firefox 3.5 on Portal 6.1.0.2 + APAR PK91594 (and its prerequisites, PK84631 & PK84603). At the time of writing the portlets will not work with Portal 6.1.5 until APAR PM02564 becomes available
Note how the farmer names are now click to action (C2A) sources and hovering over them causes a menu to pop up. The JSR286 events code used in the previous case study example has now been removed. C2A does not require portlets to be wired.
When clicking the C2A source, there is just one available action, although more could be configured. The action is to show details for each farmer. This triggers a client side C2A event, which sends the farmer’s name to the details portlet. A full page refresh is not made and the farmer’s name can be seen immediately:
Next a spinning icon appears under the farmer’s name, and the remaining details are queries are loaded using an Ajax request using JSR286 resource serving. After a moment the farmer details appear, again without a full page refresh:
Client side click to action
When the portlets were created using Rational Application Developer, the Add Web 2.0 features box was checked. This added a couple of new declarations to the JSP of a generated sample portlet that provide access to the Portal JavaScript API.
<portlet-client-model:init>
<portlet-client-model:require module="ibm.portal.xml.*"/>
<portlet-client-model:require module="ibm.portal.portlet.*"/>
</portlet-client-model:init>
The Click to Action source and targets are very easy to add using Rational Application Developer portlet tooling. Simply drag a Client Side Click to Action Source/Target Property from the Portlet palette, or use the Insert menu. The source or target can simply be dropped onto a field in the JSP editor and a wizard is used to gather information:
The JSP is modified like this:
The source property has been replaced with the <div> element below which uses ‘micro formatting’ (a special class name) that Portal uses to identify the source property (c2a:anchor) and cause it to appear underlined. In addition there are some further <span> elements which are not visible to the user due to the applied style. However, they are used by Portal to perform client side C2A so must be left in place.
The Rational Application Developer portlet tooling can be used in a similar way to define a C2A target on the target portlet. This will generate markup similar to this:
On the target portlet’s JSP, a form is defined which contains an input element. The C2A framework uses Ajax to update the value of the input element with the value defined in the source portlet. Once the value is in place, the C2A framework triggers a form submit.
If the form’s ‘action’ pointed to a server side resource (for example, a portlet action URL), server side logic could be triggered to update the view. In this case, we want to use JavaScript to trigger an Ajax request to update the view. Therefore the form action is "javascript:void(0);" and the onsubmit JavaScript handler is used to trigger a function. Also note that entire form is hidden from view with style="visibility: hidden". In this scenario we want to receive the C2A value and be notified of this by the form’s onsubmit event, but we do not want to show a form with an input box. Instead, the JavaScript will access the C2A value directly from the Document Object Model (DOM). The next section describes this in more detail.
JSR 286 resource serving with Ajax
The farmer details are updated in the view using JSR resource serving. The portlet now references a custom JavaScript file in directory _FarmerDetails/js that uses Dojo to declare a JavaScript object acting as the client side controller.
The following code from FarmersDetailsPortletView.jsp imports the JavaScript file:
<script language="JavaScript" src="<%=renderResponse.encodeURL(renderRequest.getContextPath()+"/_FarmersDetails/js/FarmerDetailsController.js")%>"></script>
There are some important concepts to note when using JavaScript in a portlet. The script statement loads the JavaScript file using the renderRequest object to get the context path for the current portlet, and renderRequest is used to encode the entire URL. The FarmerDetailsController.js contains a Dojo JavaScript object that begins like this:
Take note of how the typeof keyword is used to avoid declaring the same JavaScript object more than once. That could happen if the same portlet was placed on a page twice, or if multiple portlets shared common JavaScript files.
Next, an instance of the Controller class is created in the JSP:
Each variable name is prefixed with <portlet:namespace/> that returns a unique namespace for each portlet. This ensures no JavaScript naming collisions if the page contains multiple portlets.
When the C2A framework has populated the target portlet’s input field, the surrounding form is submitted. This triggers the JavaScript method getFarmerDetails on the Controller object, (see listing above).
At a high level, this function performs the following actions:
- Accesses the DOM to copy the hidden C2A target value (the farmer’s name), from a hidden INPUT to a DIV.
- Makes visible another DIV that contains the “Loading farmer details” text, and spinning progress icon.
- Prepares a String of POST parameters, i.e. the farmer’s name which will be posted to the portlet’s serveResource method using Ajax.
- Calls the sendPortletResourceRequest function to perform the Ajax POST request, providing a callback function.
- When the serveResource has returned its markup, the browser invokes the callback function which updates the DOM with the returned HTML.
The sendPortletResourceRequest function uses Dojo to access the JavaScript XMLHttpRequest object which is used to make asynchronous requests. The Portal JavaScript API also provides an object named XMLPortletRequest which is a wrapper for the XMLHttpRequest. However, the XMLPortletRequest object should not be used to make requests to a resource URL. The XMLPortletRequest should only be used to makes requests to Action or Render URLs.
The sendPortletResourceRequest function looks like this:
This function uses Dojo to create an XMLHttpRequest which can be used to address the portlet using Ajax. The open function is called that opens an HTTP connection to the resourceUrl originally generated in the JSP. The true parameter indicates the request should be made asynchronously.
Next, the HTTP headers are set to identify the type of the POST parameters and finally the parameters are sent with request.send. This triggers the serveResource method on the portlet which can retrieve the POST parameters and return appropriate markup or data.
With every change of state, the browser calls the inner function referenced by the request.onreadystatechange variable. When the relevant status is met, this indicates the portlet’s serveResource has returned and the data is available to the browser. The callback method then updates the UI to hide the spinning icon and populate a DIV with the returned markup.
Finally, let’s inspect the serveResource method on the target portlet:
It inspects a ‘resourceID’ of the resource request. This is similar to the action name of an Action URL; a means of differentiating requests. Next the farmer’s name is retrieved and this is used to look up a Farmer object and create a HTML table String that is written back to the client.
Also notice that the appropriate Farmer object is also written to the session - this is to facilitate browser refresh. In the JSP, if a Farmer object is found in the session, it is used to output the details. Imagine a scenario where the user triggers a C2A event to initially show farmer details and subsequently presses the browser refresh button. If the Farmer was not stored to the session the details portlet would be blank as only the C2A event triggers the Ajax request to populate the empty portlet. To solve this problem, the information is retrieved from the session and displayed until a further C2A event is received in which case it is replaced.
Table of Contents | Previous Page | Next Page