© 2008 ibm andreas prokoph – software architect d17: leveraging the power of html pages support...

© 2008 IBM

Andreas Prokoph – Software architect

D17: Leveraging the power of HTML pages support and the resource addressability framework in WebSphere Portal v6.1

STORY TITLE

WebSphere Portal Technical Conference U.S. 200822

Agenda

HTML Page Support

Introduction Demo Rendering Concepts Authoring Advanced Topics Limitations

Resource Addressabilty

Introduction Concepts Advanced Topics

STORY TITLE


Static HTML Pages

Goal: Simplify the creation of portal pages HTML designers can author portal pages without any JSP or

J2EE knowlege• Clear separation between the designer (page) and the

devloper (portlets) Full set of HTML, CSS, JS features can be used in a standard

way HTML pages may contain portlets as dynamic elements HTML pages fully support standard portal features such as

portal access control, personalization, portlet user data, ... HTML pages can be deployed or updated using the admin UI,

XML Access or Scripting without a server restartHTML Editor File Manager Portal Admin UI Portal HTML Page

author ... package ... (ZIP) create/update page ... view ...

STORY TITLE


Themes/Skins vs. HTML pages

Themes/Skins

Content is generated by JSPs using portal model information

Resources (images, CSS) are stored in the file system

Referencing resources requires the use of tags or APIs

HTML Pages

Content is a simple HTML file

Resources are stored together with the portal page in the portal database

Resources can be referenced directly using relative URIs

STORY TITLE


Demo

STORY TITLE


Rendering Concepts – JSP based page (1)

Theme JSP Tags that iterate the navigation model to produce the HTML markup

Skin – renders the title bar and the border of the portlet

Content area – the layout is described by a layout model and rendered via recursive JSP includes

Portlets – rendered as components via the portlet API

Theme JSP contains some HTML markup

STORY TITLE


Rendering Concepts – JSP based page (2)

The theme defines a JSP file that produces the markup of the page.

It uses JSP tags to iterate over the portal models to produce navigation elements and to include the portlets

URLs to images and other resource are generated using JSP tags

Typically only the content area may contain portlets, their layout is defined by the layout model

This model is very flexible

But it is also complicated, because J2EE expertise and a good knowledge of the portal JSP tags is required

In many cases the J2EE skills and the HTML design skill are not shared by the same person, which makes theme development complex

Themes cannot be previewed easily during development

STORY TITLE


Rendering Concepts – HTML page

Portlets – rendered as components via the portlet API

The markup of the page, CSS, JS and images are contained in a ZIP file that defines the HTML page.

STORY TITLE


Rendering Concepts – HTML page

The markup of the page, images, CSS and JS is directly rendered from static files

The index file may contain semantic HTML tags that are replaced by portlet markup dynamically

URLs to images and resources can be relative URLs without extra processing

This model allows to author and preview the page in a WYSIWYG way using standard HTML tools

No J2EE skills required to build a page, just HTML design skills

Less flexible than themes, however flexibility can be added by using JS or portlets

STORY TITLE


Embedded vs. Full Page

HTML pages can be rendered in two modes: embedded or full-page

Embedded

the HTML page only fills the content area of the page, the banner and navigation are rendered by the theme

Full-Page

the HTML page contols the complete page markup, the theme is not involved in rendering

The type of page is deduced from the HTML structure. If the HTML contains the <html> tag it is a full page, else an embedded page

Full Page

EmbeddedPage

STORY TITLE


Portlet Window Display Options

Portlets can be included in different ways

Included Markup

The portlet markup is inserted into the page during rendering, the page is served in one HTTP response

IFrame

The portlets are represented via IFrames that load asynchroneously

AJAX

Instead of the portlet markup the HTTP response contains a link to a portlet fragment feed. Javascript provided by the HTML page may use this link to fetch the content via an AJAX request

STORY TITLE


Deployment - Packaging

The resources for an HTML page are stored in the local file system and can be previewed and edited

The deployment artifact is simply the ZIP of the folder that contains the resources, including all required subfolders

Limitation:

The ZIP file must not exceed 1MB in size

Index file Stylesheet

Image folder

STORY TITLE


Deployment – Creating/Updating the page (1)

HTML pages can be created using standard portal page creation mechanisms

Admin UIXMLAccessScriptingSiteManagement

In the Admin UI there exists a new option to create/update an HTML page

Name the index file inside the ZIPUpload the ZIP file

STORY TITLE


Deployment – Creating/Updating the page (2)

Upload the file and identify the markup type and the name of the index file

The layout of the page is computed automatically by analyzing the HTML file

Specify how the portlets are rendered:

Included, AJAX or IFrame

STORY TITLE


How HTML pages are persisted

The HTML page ZIP file is stored in the portal database (in the same DB domain as the page itself)

The layout model and the content of the HTML file are tightly coupled, storing them in different places could become redundant

Backup/Restore will automatically include HTML page resource and result in a consistent backup

XMLAccess, SiteManagement and Scripting contains the HTML page resources as part of the data stream

Limitation: The size of the ZIP file must not exceed 1MBAI templates do not support HTML pages, yet

HTML files

ZIP of all static resources

images stylesheets

JS

DB

Markup datatable per page

STORY TITLE


Authoring HTML pages

Portal HTML pages can be created by any HTML editor

References are relative

Portlets are included using a semantic div tag

STORY TITLE


Semantic Tags

The HTML markup is parsed on the server at deployment time

Semantic tags are detected on the server and replaced during rendering time with dynamic markup

The tag must be a <div> tag: class attribute defines if the tag represents a portlet-window or

a portlet-container name attribute identifies this instance uniquely on the page style attribute identifies the unique name of the portlet-

definition

Example <div class="portlet-window"

name="breadcrumb„ style="portlet-definition:'wps.p.SpaBreadCrumbTrail'"></div>

<div class="portlet-container" name=„container“></div>

STORY TITLE


Semantic Tags

Portlet-Window

Represents an instance of a portlet on a page

If outside of a container, the window will always be rendered at its exact position in the markup

<dl> subtags may be used to initialize the portlet-window

Portlet-Container

Represents a spot that may dynamically contain zero or more portlet windows

Portlet windows may be added, deleted or moved using either the customizer or Drag&Drop (provided by the HTML page)

When the HTML page is created or updated, the page is parsed for portlet-windows and containers and a matching portal layout-model is created. This layout model can be accessed and modified using the standard public portal APIs

Portlet-Windows and Portlet-Containers are the only (server side) dynamic elements on an HTML page

STORY TITLE


Portlet Microformat

During rendering, the server renders the content of the portlet as well as metainformation in a well-defined portlet-microformat

CSS or JS provided by the HTML page can use this microformat to render a skin or a portlet menu

The microformat containsName and IDTitlePortlet ActionsPortlet Body

Note:The portlet actions follow the REST pattern, i.e. safe operations are represented via GET, unsafe operations via POST

STORY TITLE


Container Microformat

The container microformat identifies the container and includes the information to implement javascript based Drag&Drop

The microformat contains

Name and IDDrop handler

STORY TITLE


Implementing Drag&Drop

The actual implementation of JS based Drag&Drop is left to the HTML page

The design does not mandate any particular JS library and leaves the choice to the HTML editorThe portal DOJO library may be used as a convenient solution

The container microformat contains a dnd drop handler

The client side DnD logic invokes this handler to execute the action operation

1. Page renders container and microformats

2. JS enables DND

3. User drags a portlet and drops it onto a drop zone

4. JS receives the „drop“ event

5. JS calls the drop handler

6. Server executes the drop operation

Pro

vide

d by

the

HT

ML

page

STORY TITLE


Example Drag and Drop (DnD) Handler Code (DOJO)

STORY TITLE


Adding Navigation

Navigation can be added in multiple ways:

Absolute URLs Using friendly names or URL mappingsUseful for hardcoded linksCon: navigational state is lost

Relative POC URLsUsing the POC URI of the target, e.g. <a href=„?nm:oid:wps.content.root“>Useful for hardcoded links

Navigation Portlets (recommended)The navigation links are computed dynamically by a navigation portletThe HTML page references the navigation portlet via a semantic tag and uses CSS to style the navigationSupports flat lists and navigation hierarchies

STORY TITLE


Navigation Portlets

Out-of-the-box navigation portlets render a well-defined navigation microformat

The microformat contains TitleActions on the pageExpansion information

The HTML page can style this microformat to display list or navigation trees

ExampleRender the Quick Links

Breadcrumbtrail PortletRenders the path from a page up to the content rootThe starting point can be configured

Navigation PortletRenders a flat or hierachical portion of the navigation modelThe starting point and hierarchy depth can be configuredNote: you can use this portlet to render e.g. the QuickLinks

PageList PortletRenders arbitrary lists of pages that are provided via the POC resolution service (similar to a simple feed reader)

STORY TITLE


Localization

All resources (HTML, images) can be localized

Localized resource contain the locale as a filename suffix

index.html (default)index_de.html (German)index_en_us.html (US English)

The rendering engine determines the best available locale from the request and serves the localized resource

Resources are always addressed via their non-localized name

Example

HTML Code

<img src=„test.jpg“>

Available files

test.jpgtest_en.jpgtest_de.jpg

Accept-Locale header

[de, en]

Server resource

test_de.jpg

STORY TITLE


Referencing Resources

Resources can (and should) be referenced using relative URIs <img src=„test.jpg“>

When the browser requests the resource, the server ... ... tries to find the localized version of the resource in the ZIP .. if the ZIP does not contain the resource, the server applies a theme

fallback and tries to find the resource in the theme directory (using the default theme fallback)

resources may be shared across HTML pages by putting them into the theme

Main usecase: share large JS libraries such as DOJO

Including resources via relative URLs from other resources (e.g. images from CSS files) just works as expected

Example for a static pages that uses the portal DOJO version: <script type="text/javascript"

src="dojo/portal_dojo/dojo/dojo.js„ djConfig="parseOnLoad: true"></script>

Limitation Relative URLs must not contain a .. path element

STORY TITLE


Referencing Resources - background

The URL that renders a static page is a rich portal URL that contains navigational state [1]

Relative URLs are relative to this base URL, i.e. the resulting URL still contains state

Serving the stateless resource via the stateful URL would lead to poor caching and a performance problem

the server sends a redirect from the stateful resource URL to a stateless URL, so the resources can be cached

Both the redirect itself as well as the resulting resource are cacheable

[1] https://quickr.tap.ibm.com/lotus/mypoc?uri=dm:f49b3f8046cf3fc8acd2ee8a40c9fec3&verb=view

http:<server>/wps/portal/state/

http:<server>/wps/portal/state/image.jpg

http:<server>/wps/mypoc/spa//<pageID>/html/image.jpg

STORY TITLE


Referencing Resources – Resource Serving

The portal servlet serves the markup that makes up the page

Additional resources are served via the resource addressability framework

every resources inside the ZIP can be addressed individuallythe resource addressability framework adds caching, redirect support, etc HTML

Static Page

POC Framework

DBHTML files

resources

STORY TITLE


Resource Addressability

The resource addressability framework is used in a couple of key places for HTML pages

... make individual resources out of a ZIP addressable

... server the complete ZIP and a list of files

... upload the updated ZIP for an existing page

... implement (pluggable) Drag‘n‘Drop operations for pages

... provide a list of pages for the „PageList“ navigation portlet

the resource addressability framework is a generic framework to serve portal resources and can be extended by customers

STORY TITLE


Usecase

The Resource Addressability Framework allows to work with „resources“ in WebSphere Portal

Identify resources in a location independent way (POC URI) Find the view (e.g. a portal page) that renders a resource Download a binary representation of a resource

From the client‘s perspective:• Given the ID of a resource (e.g. from a search result) the

framework defines how the view can be addressed and how the resource can be downloaded

From the provider‘s perspective:• The framework allows to dynamically introduce resources,

views and representations for the resources, providing uniform, resource independent access points

STORY TITLE


Terminology

The term „resource“ is largely overloaded, so we call a piece of information that can be identified and accessed

Piece of Content = POC

Examples:

Documents in a document library Users Portal pages Portlets ...

STORY TITLE


Motivation

WebSphere Portal is a platform that provides an aggregated (HTML) view to pieces of content (POC)

Classically the POCs are only accessible through the aggregation layer

HTML

Piece of Content:WCM Item

Piece of Content:Document

Aggregation Layer:the „view“

Piece of Content:User Information

...Portal

STORY TITLE


Motivation

The POC framework adds an entry point to WebSphere Portal that allows to access POCs in a variety of mime-types

Customers can easily add their own POCs and leverage the POC Framework to serve them

HTML

Piece of Content:WCM Item

Piece of Content:Document

Aggregation Layer:the „view“

Piece of Content:User Information

Portal

POC Framework

ContentRepresentation

ContentUpload

STORY TITLE


What is a Piece of Content (POC)?

FeaturesUI neutral: a POC is not a UI artifact but exists as descriptive

data without a UI. There exist zero or more viewers or editors for a POC, and the POC itself can be accessed in multiple UI contexts

Identifiable: a POC can be identified uniquely by an ID. This ID must be global and unique over time (i.e. it must not be scoped to a subsystem and IDs that have been issued once must not be reassigned to different POCs). More than one POC ID may point to the same POC (although such an aliasing solution should be avoided)

ExamplesWCM documentDiscussion ThreadPortal PagePortletUser…

STORY TITLE


How is a POC identified?

A POC is identified by a URI (RFC 3986)

POCURI = <scheme>:<scheme-specific-part>

Components that expose POCs can define new schemes or reuse existing ones

The POC URI is NOT the URL to the resource itself

Interpreted by thePOC framework tohandle a POC

Identity Location

STORY TITLE


How is a POC addressed?

The URL to a POC can be constructed via string-concatenation or via a Portal-API call

/wps/[my]poc[/<vp>]?uri=<scheme>:<ssp>&mode=download (1) /wps/[my]poc[/<vp>]/<scheme>/<ssp>?mode=download (2)

Both URL flavors are equivalent, (1) is helpful for FORM submits, (2) is required if the resource contains relative URL references (e.g. images in CSS)

POC URLs are fully virtual portal aware

The [mypoc] servlet will establish a WAS security context, whereas [poc] is used for anonymous access

Example: URL to the ATOM feed for the portal content model /wps/mypoc/cm/oid:7C_48938908?mode=download

STORY TITLE


POCs can be addressed using „modes“

The [mypoc] servlet serves as the generic access point

It redirects to handler-servlets based on the URI and the mode

Per default:

mode=view dispatches to the portal servlet and displays a portal page

mode=download dispatches to a POC download servlet that produces data

mode=lookup produces an ATOM feed that describes the entry point that handles the resource

The default handling can be customized per POC URI.

STORY TITLE


POC and the REST pattern

POC services strictly follow the REST pattern in that ...

... resources are uniquely addressed via the URL ... requests for information retrieval (e.g. mode:

download, view, lookup) always use HTTP GET verbs ... requests to modify information are ONLY possible

using PUT/POST/DELETE verbs ... the HTTP status codes are REST compliant

STORY TITLE


The process of viewing content for a POC URI

The lookup handler resolves a URI to a URL the POC servlet serves as a well-defined entry point for any kind of data serving servlet

In WP the default entry point is the portal servlet

The portal servlet dispatches to ResolutionServices that update the navigational state based on the POC URI

POC servlet Lookup handlerrequest

URI URIExtensible lookup handlers compute the URL used to serve the URI

URL

URL

redirect Portal servlet

URI + stateResolution Service

Extensible resolution service finds portal page

Portal rendering

markupmarkup

delegate Resolution ServiceResolution ServiceResolution Service

Optionall delegates to addition services (e.g. portlets) for initialization

state

STORY TITLE


The process of serving content for a POC URI

The lookup handler resolves a URI to a URL the POC servlet serves as a well-defined entry point for any kind of data serving servlet

In WP the default entry point is the content handler servlet

The content handler uses extensible DataSourceFactory plug-points and serializes their DataSource objects.

POC servlet Lookup handlerrequest

URI URIExtensible lookup handlers compute the URL used to serve the URI

URL

URL

redirect

Contenthandlerservlet

URIDataSourceFactory

Extensible DS factory creates data sources per URI

DataSourceSerializer

bytesbytes

STORY TITLE


The process of modifying a POC

Modification operations are only possible on the content handler servlet (i.e. the lookup has to be done manually)

Data Sinks are coupled to URI and HTTP verb (impossible to modify a resource using GET)

URI

Contenthandlerservlet

URIDataSinkFactory

Extensible DS factory creates data sinks per URI

DataSink

bytes

content content

DataSinkThe Data Sink executes the modifcation operation

Serializer

bytes

DataSourceThe result of the operation is a Data Source

STORY TITLE


What the POC framework does for you!

Decodes URLs into URI and parameters

Initializes the portal context required to access portal APIs Virtual Portal Context User Context

Handles HTTP specifics Transfer encoding if requested (GZIP) Byte range request Caching headers Automatic redirects to circumvent the vary-header bug

Mediates between content and representation Serializes XML, characters, multipart, etc. into byte streams Content-disposition information

STORY TITLE


Currently supported serializers

ByteDataSource Lowest level, just streams bytes

CharDataSource Streams characters, used for text-based data

XmlDataSource JAXP based XML data streaming, used e.g. for feeds

MultipartDataSource Combines multiple data sources into one single multipart stream

(e.g. for performance reasons to save requests)

WebdavDataSource (experimental) Exposes POCs via the WebDAV protocol

All DataSources are fully stream based and will perform independently of the size of the data!

STORY TITLE


Example: XMLDataSource

Source getSource();

String getContentType();

Date getExpiration();

Date getCreated();

Date getLastModified();

URI getURI();

Map<String, String[]> getParameters();

Returns a JAXP Source object (i.e.

SAX, DOM or Stream)

Mime Type

Timestamps to compute the cache

headers

Identity information

STORY TITLE


Example: ATOM feed – Portal Navigation Model

/wps/mycontenthandler/!ut/p/nm/oid:wps.portal.root? mode=download&digest=Ijd6SHFqhrFcnWe3Pts88A!!

(Status-Line) HTTP/1.1 200 OK

Server WebSphere Application Server/6.1

Date Thu, 03 Jul 2008 11:54:16 GMT

Expires Fri, 04 Jul 2008 11:54:16 GMT

Cache-Control private, max-age=86400

Last-Modified Thu, 01 Jan 1970 00:00:00 GMT

Content-Location http://wps60.boeblinge...88A!!

Content-Type application/atom+xml

Content-Encoding gzip

Content-Language de-DE

Content-Length 523

Accept-Ranges bytes

X-Request-Digest Ijd6SHFqhrFcnWe3Pts88A!!

Caching support

Compression (if requested)

Fix for the vary-header bugs

STORY TITLE


Example: ATOM feed – Portal Navigation Model

STORY TITLE


Caching

HTTP Cache headers are computed automatically based on

ExpirationLast-Modified DateE-TagIdentity (Content-Location)

J2EE security context (public vs. private cache)

Content can also be cached server side in the dynacache

The „VARY-header“ bug

The response depends on the request accept-language header and the cookies (e.g. the session cookie!), so the response must contain a VARY header

many browsers do not correctly cache responses that contain such a header (or do not cache at all)

for selected browsers the POC frameworks computes a digest from the request headers and redirects the URL becomes unique and cacheable

/wps/mycontenthandler/!ut/p/nm/oid:wps.portal.root? mode=download&digest=Ijd6SHFqhrFcnWe3Pts88A!!

STORY TITLE


How to deploy a new POC handler?

Deployment model based on the Eclipse plugin frameworkPlugin.xml

The URI scheme

The type of serviceDeployed using a plugin.xml, e.g. in a WAR file or a shared library.

UR

I m

atch

ing

Ser

vice

STORY TITLE


Convenience APIs that can be used by POC data sources

SAX based ATOM API Exposes an API to build or parse an ATOM feed via JAVA

callbacks Very fast and scaleable, because no ATOM document is built Extends the standard JAXP APIs (i.e. compatible with existing

JAXP parsers, filters, XSLTs, etc) Most portal REST feeds are built upon this API

Streaming APIs Set of APIs to build or parse multipart streams Very fast and scaleable, no buffering required

Used to handle FORM uploads or to bundle multiple REST feeds into one larger multipart response (for performance reasons)

STORY TITLE


Convenience APIs that can be used by POC data sources

Server side mashup APIs

Allows to combine multiple data sources into one data source (mashup)

Chain-of-responsability pattern Transform the content of another data source

All portal APIs

STORY TITLE


Additional Information and Resources

WebSphere Portal – IBM Site

http://www-3.ibm.com/software/genservers/portal/

WebSphere Portal Business Solutions Catalog:http://catalog.lotus.com/wps/portal/portal

Websphere Portal Developer’s Zone http://www-106.ibm.com/developerworks/websphere/zones/portal/

Product Documentation and WebSphere Portal Wiki http://www-3.ibm.com/software/genservers/portal/library/

http://www-10.lotus.com/ldd/portalwiki.nsf

Education http://www-3.ibm.com/software/genservers/portal/education/

WebSphere Portal 6.0 DemoNethttp://docs.dfw.ibm.com/wp6/?DDSPageRequest=/

STORY TITLE


Please take a few minutes to fill out the session survey. Thank you

Mark your calendars!Mark your calendars!

2009 U.S. WebSphere Portal Technical Conference2009 U.S. WebSphere Portal Technical ConferenceOctober 12-15, 2009, Sheraton San Diego Hotel and MarinaOctober 12-15, 2009, Sheraton San Diego Hotel and Marina


Session ID: D17

Session: Leveraging the power of HTML pages support and the resource addressability framework in WebSphere Portal v6.1

Presenter(s): Andreas Prokoph ([email protected])

STORY TITLE


© IBM Corporation 2008 All Rights Reserved.

The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics may vary by customer.

IBM, the IBM logo, WebSphere, Lotus, Lotus Notes, Domino, Quickplace, Sametime, Workplace and Quickr are trademarks of International Business Machines Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

All references to Renovations Inc. refer to a fictitious company and are used for illustration purposes only.