Revision History

Date	Version	Description	Author
4/16/2002	0.0	Initial Draft	David Taieb
4/17/2002	0.1	Initial Changes	Gino Filicetti
5/9/2002	0.2	Changes based on 5/8/2002 concall	David Taieb
6/5/2002	0.3	Rewriting scenarios	David Taieb
6/19/2002	0.4	Changes based on calls after 5/8/2002	Chris Braun

Table of Contents

1. Goals of this document 1

2. Visual Themes 1

2.1 Problem Description 1

2.2 CSS classes: 1

2.2.1 Links (Anchor) 1

2.2.2 Fonts 1

2.2.3 Messaging 1

2.2.4 Tables 2

2.2.5 Sections 2

2.2.6 Forms 2

2.2.7 Menus 2

2.2.8 Portlet 3

2.2.9 Colors 3

2.2.10 Other 4

3. Markup Fragment Rules 4

3.1 Problem description 4

3.2 HTML 5

3.2.1 HTML validation rules 5

3.3 XHTML Basic 5

3.3.1 XHTML Basic Validation rules 5

3.4 Other Markups 5

3.4.1 cHTML 5

3.4.2 WML 5

3.4.3 Others (VoiceXML,…) 5

3.5 Markup Fragment decomposition 5

4. Secure/Proxy resources: 6

4.1 Problem Description 6

4.2 Proxy 6

4.3 Caching 6

4.4 Resource Adaptation 6

5. URL Rewriting 6

5.1 Problem Description 6

5.2 Rewriting scenarios 7

5.2.1 Using a prefix sent by the aggregator 7

5.2.2 Using a predefined prefix 7

5.2.3 At the aggregator side 7

5.2.4 At the producer side (with URL prefix sent by the aggregator) 7

5.2.5 Discussion about the 4 URL rewriting scenarios: 7

5.3 URL Types 8

5.3.1 Fully Qualified 8

5.3.2 Relative URLs 8

5.3.3 Action URLs 8

5.3.4 Proxy URLs 8

5.3.5 Actions to other WSRP portlets 8

5.4 Mechanism used to demarcate URLs 8

5.4.1 Preliminary Proposal Scenario 2, Action URL 8

5.4.2 Preliminary Proposal Scenario 4, Action URL 9

5.4.3 Preliminary Proposal Scenario 2, Proxy URL 9

5.4.4 Preliminary Proposal Scenario 4, Proxy URL 9

6. Namespacing/Prefixing 10

6.1 Problem Description 10

6.2 Name tags 10

6.3 JavaScript methods and variables 10

6.3.1 Prefixing: 10

Is there any reason to treat them any differently from Named attributes? 10

6.3.2 Cross portlet JavaScript methods and variables: 10

1. ~~Goals of this document~~ 1

2. ~~Visual Themes~~ 1

~~2.1~~ Problem Description 1

~~2.2~~ CSS classes: 1

3. ~~Markup Fragment Rules~~ 2

~~3.1~~ ~~Problem description~~ 2

~~3.2~~ ~~HTML~~ 2

~~3.2.1~~ ~~HTML validation rules~~ 2

~~Disallowed~~ 2

~~Discouraged~~ 2

~~3.3~~ ~~XHTML Basic~~ 2

~~3.3.1~~ ~~XHTML Basic Validation rules~~ 2

~~Disallowed~~ 2

~~Discouraged~~ 2

~~3.4~~ ~~Other Markups~~ 3

~~3.5~~ ~~Markup Fragment decomposition~~ 3

4. ~~Secure resources:~~ 3

~~4.1~~ ~~Problem Description~~ 3

~~4.2~~ ~~Proxy~~ 3

~~4.3~~ ~~Caching the resource~~ 3

5. ~~URL Rewriting~~ 3

~~5.1~~ ~~Problem Description~~ 3

~~5.2~~ ~~Rewriting scenarios~~ 3

~~5.2.1~~ ~~Using a prefix sent by the aggregator~~ 3

~~5.2.2~~ ~~Using a predefined prefix~~ 3

~~5.2.3~~ ~~At the aggregator side~~ 4

~~5.2.4~~ ~~At the producer side (with URL prefix sent by the aggregator)~~ 4

~~5.2.5~~ ~~Discussion about the 4 URL rewriting scenarios:~~ 4

~~5.3~~ ~~Mechanism used to demarcate URLs~~ 4

6. ~~Namespacing/Prefixing~~ 5

~~6.1~~ ~~Problem Description~~ 5

~~6.2~~ ~~Named attributes~~ 5

~~6.3~~ ~~JavaScript methods and variables~~ 5

~~6.3.1~~ ~~Prefixing:~~ 5

~~Is there any reason to treat them any differently from Named attributes?~~ 5

~~6.3.2~~ ~~Cross portlet JavaScript methods and variables:~~ 5

WSRP Markup/Style Document

1. Goals of this document

To define standard mechanisms to allow common look and feel across aggregated portlets

To specify the rules that define valid markup fragments for all the markup languages allowed. These include by order of priority: HTML, XHTML, Other (WML, cHTML, VoiceXML, …)

To define standard mechanisms for URL rewriting and namespace encoding. These problems are also of interest to the interface subcommittee and therefore the two efforts will stay in sync.

2. Visual Themes

2.1 Problem Description

As WSRP services are consumed, we need a mechanism to provide a way for the portlets to adapt to the containing consumer environment.~~consistent look and feel across all the aggregated portlets.~~

· Consider eliminating the portlet classes all together in favor of using section classes instead. Are there use cases that would support keeping a higher level class that wraps all of the portlet's content?

· Can we remove wsia-portlet-background? Should be able to use the wsia- portal's style attributes for this, correct?

· Is there a possibility that the portal redefines stylesheets for single portlets in a mode dependent way. That way we could omit the background-edit and background-config styles]

2.2.9 Colors

Proposed	Description
.wsia-color1...wsia-color16
.wsia-background-color1...wsia-background-color16
.wsia-border-color1...wsia-border-color16

Comments:

· Use Case: Data needs multiple colors (more the two) in order to represent itself. For example: Sales figures can be represented by geographic region where each region has a specific color associated with it.

2.2.10 Other

Classification	Proposed By	Class Proposed	Description
Position	WSUI	Wsui-right Wsui-left Wsui-top Wsui-bottom Wsui-shape ([CL: what is this style for?])	This describes the position of an element
Media properties	WSUI	Wsui-media format	Probably for Audio and Video streaming of content
Background properties	WSUI	Wsui-backgroung color Wsui-background pic	Logo? Or Uniform background color
Margins	WSUI	Wsui-left margin Wsui-right margin Wsui-top margin Wsui-bottom margin
Spacing	WSUI	Wsui-space_between_row (of text)	spacing
Unclassified	WSUI	.wsui-block-bgcolor .wsui-page-title

Comments:

· Not sure what the position classes are used for. Can't the section class indicate position information as a style rule?

· Can we get more detail on media formats. A simple use-case would be good. Does this relate to the CSS media types screen, aural, print, etc? If so does this need to be defined as part of the wsia appendix or should this be left up to the implementation style sheet?

· What does wsui-block-bgcolor represent?

· Does a portlet need page title? Do we have a use case where a portlet would need this?

· Generally would like to here from WSUI as to what these classes provide.

3. Markup Fragment Rules

3.1 Problem description

Because markup fragments, produced by each remote portlet, are aggregated by the consumer portal into a single page, some rules and limitations are needed to make sure of the coherence of the resulting page to be displayed to the end user.

The markup validation rules might also depend on the type of aggregation environment used to embed the output of the portlets: Tables vs. framesets (or may be a combination of both?) (If we allow multiple choices, is this a property that’s needed to be propagated to the producer?).

By order of priority, we’ll define validation rules to the following markup languages :

· -HTML: most commonly used markup language

· -XHTML Basic: becoming a standard for cellular phones. We should also consider impacts of XHTML derived markups like XHTML Mobile profile, etc…

· -cHTML, WML, VoiceXML, etc…

~~Another~~ Another problem is that markup fragments are eventually embedded into markup tag containers (like table cells for instances), this greatly reduce the possibility for the remote portlet to expose tags (or other items like JavaScript methods/variables) that must appears in a global scope. One possible solution is for the aggregator to request separately any global markup that must occurs outside the content of the portlet and the portlet content itself.

3.2 HTML

Because disallowed tags might potentially have an impact on other portlets or even break the whole aggregated page, its inclusion will invalidate the whole markup fragment which will be replaced by an error message.

3.2.1 HTML validation rules

Disallowed	Discouraged
Base	link
Body	meta
Frame	style
Frameset
Head
Html
title

3.3 XHTML Basic

3.3.1 XHTML Basic Validation rules

Disallowed	Discouraged
base	link
body	meta
Head
html
title

Comments:

· Shouldn’t style be added as a discouraged tag for XHTML?

3.4 Other Markups

These markups will not be the focus of the initial WSRP release.

3.4.1 cHTML

3.4.2 WML

3.4.3 Others (VoiceXML,…)…

3.5 Markup Fragment decomposition

Proposition to decompose the markup output into 3 sections like header, body and footer: we should have an extensible set of sections names, WSRP will define a standard base set that will be extensible (in future releases of WSRP and privately by the consumer) and it would be up to the consumer whether to support them or not. This group is opened to any suggestion as to what this base set should be composed of.
This standard base set should depend on the content type (some section might make sense for a markup language but not for others).

The issue with this is that if portlet’s are allowed to add markup to the containing page then the consumer must wait for all portlets markups to be returned before rendering.

Some tags that the portlet may want to access in the head of the containing page are:

· Link

· Meta

· Style

HTML 4.0 and XHTML specs explicitly deny the use of these tags outside of the head. However, most browsers support this any way. We should address this issue with the XHTM and HTML spec groups.

Another tag worth addressing is the xforms:model tag. This tag is also currently explicitly required by the current xforms spec to be within the head tag. Since this spec is not final it is likely that the spec will be changed to allow the use of the xforms:model tag anywhere within the document as long as it occurs before its use.

We should consider only allowing the portlet access to its own markup for this release. Another possibility is to define an extensible mechanism by which consumers can allow access to other areas of a containing document.

4. Secure/Proxy resources:

4.1 Problem Description

The client might not always have direct access to resources (like java applets, images, etc…) embedded in the portlet because of network topology reason for instance.. Therefore, after the link URI is being rewritten to point to the aggregator, the aggregator must provide a transparent mechanism that ensures availability of the resource by acting as a proxy between the user and portlet. The aggregator might also decide to proxy a cached version of the resource.

~~Question: How does the portlet indicates that a resource needs to be proxied (especially for these URL that are dynamically generated using JavaScript).~~

4.2 Proxy

The aggregator proxies the request from the client to the remote portlet and proxies back the resource to the client.

Note: we need to make sure that security, privacy and access control are not compromised during the proxying process.

4.3 Caching the resource

The aggregator caches the resource from the remote portlet and directly serves it to the client. The producer should be able to decide if the resource can be cached.

Question: what standard do we apply for determining that a cached resource has expired?

4.4 Resource Adaptation

The aggregator may want to replace URLs and namespaces that are provided by the producer using predefined tokens.

5. URL Rewriting

5.1 Problem Description

URLs embedded in markup fragment cannot be direct links to the original producer but must be encoded so that they are intercepted by the aggregator and re-routed back to original producer. Because the same portlet can be instantiated more than once in a same page, encoded URL will have to allow aggregator to track the portlet instance to which the request is intended for.

The producer and the Consumer will work together to maximize efficiency of URL encoding and routing of requests.

5.2 Rewriting scenarios

5.2.1 Using a prefix sent by the aggregator

The Aggregator sends a prefix with the request that the producer will use to do the URL boundary demarcation. The aggregator then parses the markup looking for the prefix it provided.

5.2.2 Using a predefined prefix

All portlets use a predefined prefix, which is part of the specification, to do the URL boundary demarcation. The aggregator then parses the markup looking for the well known prefix.

5.2.3 At the aggregator side

The aggregator automatically parses markup and heuristically determines URL boundaries and does the necessary rewriting automatically.

5.2.4 At the producer side (with URL prefix sent by the aggregator)

The aggregator sends the URL prefix to use to the remote portlet, allowing it to do the rewriting itself on all the necessary URL. The markup sent back to the aggregator is then ready for immediate inclusion in the page, with no parsing necessary.

Note : We could consider a variation of this scenario where the remote portlet can choose not to rewrite all the URLs and will use the same algorithm as in 5.2.2 to demarcate the URL. It is then up to the aggregator to identify and rewrite all the remaining URLs using the prefix used by the producer. This is essentially a combination of 5.2.2 and 5.2.4.

5.2.5 Discussion about the 4 URL rewriting scenarios:

Scenario	Pros	Cons	Recommendation
5.2.1	Text based parsing at the aggregator side easy to implement and very efficient~~efficiation~~.	Parsing at the aggregator side as well as prefix inclusion at the producer side can cause a performance problem.	5.2.2 deemed superior
5.2.2	Text based parsing at the aggregator side easy to implement and very efficient~~ation~~. Because the prefix is known in advance, the producer needn’t do any processing at run time.	Requires ~~Parsing~~ parsing at the aggregator side which .complicates the consumer. ~~Uniqueness problem for JavaScript functions and variables when two instances of the same portlet coexist in the same page.~~	Recommended
5.2.3	If it works, it would require no work from the producer making the system very generic and truly plug and play	Extremely complicated to implement The URL rewriting algorithm would have to be markup agnostic Error prone	Poor
5.2.4	No rewriting at the aggregator side	As we can’t assume what makes up a URL, and how it should be encoded (.NET vs. J2EE), implementation can be difficult. Static content cannot take part in URL rewriting	Recommended

Note: If we decide that a combination of 5.2.2 and 5.2.4 will be supported then we need to define the algorithm in which the consumer will decide which scenario to use and when to use it.

5.3 URL Types

5.3.1 Fully Qualified

These URLs are not rewritten by the consumer. The URL is simply a link to a resource somewhere on the net. The spec does not need to be concerned with these URLs.

5.3.2 Relative URLs

URLs need to be rewritten by the consumer. A base URL needs to be supplied by the producer so that the consumer can correctly determine the fully qualified URL. May work in combination with 5.3.4.

5.3.3 Action URLs

URLs that specify that a action needs to be performed by the portlet. The URL needs to be rewritten so that the Consumer can intercept the request and formulate a soap request back to the producer.

5.3.4 Proxy URLs

Some resource may need to be proxied by the consumer. The proxy URL tells the consumer that a resource is to be served by its resource server (proxy). The resource may be cached by the proxy server if the producer indicates that this is okay.

5.3.5 Actions to other WSRP portlets

Need more discussion.

5.35.4 Mechanism used to demarcate URLs

The producer uses an escape sequence that contains all the parts of the URLs followed optionally by some parameters. The aggregator then searches this sequence and reconstructs the URL using the correct URL prefix.

Advantages: this method is parsing efficient and should be easy to implement.

We should provide a mechanism that will allow for actions to be blocking. If an entity tells the consumer that an action is blocking then the consumer should wait for the completion of the entity action before continuing the rendering process. This specifically relates to WSRP interfaces, so it should be up to that committee to define the process. We will need to define the URL mechanism which will enable this.

We will probably need separate tokens for action URLs and proxy URLs.

TODO: The URL Rewriting syntax and semantics need to be defined in more detail.

~~TODO:~~ ~~more~~ ~~details~~

5.4.1 Preliminary Proposal Scenario 2, Action URL

All portlets use a predefined prefix, which is part of the specification, to do the URL boundary demarcation. The aggregator then parses the markup looking for the well known tokens.

A. Entity's URL: {StartToken}{urlType = action}{actionName}{EndToken}
B. Consumer rewrites URL: Stores Entity's URL, and generates the final URL to reference the action
C. End-User browser sees: http://Consumer.com?WSIA_urlref=5
D. Post to Consumer: Consumer does a lookup and calls Producer

E. Soap invocation to Producer: performAction(entityHandle, ..., actionName, ...)

5.4.2 Preliminary Proposal Scenario 4, Action URL

The Consumer sends URL info to use to the remote portlet,
allowing it to do correct URL writing itself. The markup sent back to the
Consumer is then ready for immediate inclusion in the page, with no parsing
necessary.

A. Consumer sets Entity property: ActionURL = http://Consumer.com?WSIA_entity=7,WSIA_actionName={actionName}{params}

B. Entity's URL: http://Consumer.com?WSIA_entity=7,WSIA_actionName=DoTransaction,parm1=foo
C. Consumer passes URL as is:

D. End-User browser sees: http://Consumer.com?WSIA_entity=7,WSIA_actionName=DoTransaction,parm1=foo
E. Post to Consumer: Consumer does a lookup of the entity and calls Producer
F. Soap invocation to Producer: performAction(entityHandle, ..., DoTransaction, ...)

5.4.3 Preliminary Proposal Scenario 2, Proxy URL

All portlets use a predefined prefix, which is part of the specification, to do the URL boundary demarcation. The aggregator then parses the markup looking for the well known prefix.

A. Entity's URL: {StartToken}{urlType = proxy}{images/ok.gif}{EndToken}

B. Consumer rewrites URL

Case 1: The Consumer acts as a proxy URL, stores entity's URL, and generates URL to reference the resource. The base URL for the resource has been discovered from metadata or the self description.

C. End-User browser sees: http://ConsumerProxyServer.com?WSIA_resourceref=12
D. Request from Client: Consumer does a lookup and serves the resource.

Case 2: The Consumer does not act as a proxy. Prefixes the URL with the service's base URL (see above). This is essentially a way for the portlet to use a relative reference to a base URI.

C. End-User browser sees: http://Producer.com/images/ok.gif
D. Request from Client: The client directly accesses the resource

5.4.4 Preliminary Proposal Scenario 4, Proxy URL

The Consumer sends URL info to use to the remote portlet, allowing it to do correct URL writing itself. The markup sent back to the Consumer is then ready for immediate inclusion in the page, with no parsing necessary.

A. Consumer sets Entity Property: ProxyURL = http://Consumer.com?WSIA_entity=7,WSIA_proxy={resource}
B. Entity's URL: http://Consumer.com?WSIA_entity=7,WSIA_proxy=images/ok.gif
C. Consumer passes URL: The base URL for the resource has been discovered from metadata or the self description and is stored by the Consumer.

D. End-User browser sees: http://Consumer.com?WSIA_entity=7,WSIA_proxy=images/ok.gif

E. Post to Consumer: Consumer uses the entity reference to lookup Producer, builds the correct URL & serves the resource. ~~about the algorith~~m

Notes:

Actual URLs seen on the consumer side should be implementation specific we should not specify how the consumer should generate URLs or how the action/proxy processing is implemented.

6. Name-spacing/Prefixing

6.1 Problem Description

Aggregating multiple portlet from different sources can potentially result in naming conflicts for various types of elements: named attributes, JavaScript functions and variables, etc.

c…This problem is similar to URL Rewriting. We should consider using similar mechanisms for both situations.

6.2 Namedd attributestags

Namedd ~~attributes~~ tags identify (uniquely or not) items in the markup fragment. For examples, named ~~attributes~~ tags in HTML are represented using the “name” or “id” attribute and more often than not are referenced by the application and therefore should be encoded to ensure portlet integrity. The uniqueness of the encoded attribute will have to also be preserved for each instance of the same remote portlet running on the page.

As the only criteria for encoding the named ~~attribute~~ tag is uniqueness (as opposed to URL rewriting where the encoded URL must be redirected to the aggregator itself), do we need information from the consumer?

6.3 JavaScript methods and variables

6.3.11.1.1 Prefixing:

6.3.1

Is there any reason to treat them any differently from Named attributes?

6.3.2 Cross portlet JavaScript methods and variables:

To provide a mechanism to expose to all aggregated portlets, JavaScript methods / variables declared from a particular portlet. A global page level namespace for example? This can probably be left open, if a portlet fails to namespace its JavaScript then other portlets can call the functions. To be safe most JS functions should be name-spaced.

Examples of global JavaScript method/variable use : data query between portlets, data writing between portlets~~, etc…~~ , and code reuse.

	~~WSUI~~	~~IBM WPS~~
~~Links~~		A ~~A:visited~~ ~~A:hover~~
~~Fonts~~	~~wsui-font~~ ~~wsui-font-small~~ ~~wsui-font-large~~ ~~wsui-dim~~ ~~wsui-dim-small~~ ~~wsui-error~~ ~~wsui-error-small~~ ~~wsui-ok~~ ~~wsui-ok-small~~ ~~wusi-form-label~~	~~.portletText~~ ~~.portletSmText~~ ~~.portletTinyText~~ ~~.buttonText~~ ~~.fieldErrorText~~
~~Tables~~	~~wsui-table~~ ~~wsui-table-row-header~~ ~~wsui-table-row-sectionheader~~ ~~wsui-table-row-odd~~ ~~wsui-table-row-even~~	~~.tableHead~~ ~~.tableText~~ ~~.tableShdRow~~
~~Sections~~	~~wsui-section-title~~ ~~wsui-trail~~ ~~wsui-trail-current~~	~~.portletTitle~~ ~~.portletTitleCust~~
~~General~~	~~wsui-page-title~~ ~~wsui-block-bgcolor~~	UL ~~.portletColorBack~~ ~~.portletHead~~ ~~.portletBody~~ ~~.portletBack~~
~~Menus~~	~~wsui-menu~~ ~~wsui-menu-current~~

Proposed	Description
.wsia-font
.wsia-font-dim
.wsia-font-positive
.wsia-font-negative

Proposed	Description
.wsia-msg-status	Display status messages
.wsia-msg-info	Help/info messages
.wsia-msg-error	Errors
.wsia-msg-alert	Warnings
.wsia-msg-success	Successful completion

Proposed	Description
.wsia-section
.wsia-section-header
.wsia-section-body
.wsia-section-alternate
.wsia-section-selected
.wsia-section-subheader
.wsia-section-footer
.wsia-section-background
.wsia-section-text

Proposed	Description
.wsia-form-label
.wsia-form-field
.wsia-form-button
.wsia-icon-label	Text that appears besides a context dependent action icon.
.wsia-dlg-icon-label	Text that appears besides a “standard” icon (e.g. Ok, or Cancel)
.wsia-form-field-label	Text for a separator of fields (e.g. checkboxes, etc.)
.wsia-form-field	Text for a field (not input field, e.g. checkboxes, etc)

Proposed	Description
.wsia-menu

.wsia-menu-item-selected
.wsia-menu-item-hover
.wsia-menu-item-hover-selected
.wsia-menu-item-background	Menu item background color - highlighted and non-highlighted
.wsia-menu-cascade-item
.wsia-menu-cascade-item-selected
.wsia-menu-item-selected-background
.wsia-menu-description-background	Description box background color and font.
.wsia-menu-description
.wsia-menu-caption
.wsia-menu-caption-background

Proposed	Description
.wsia-portlet
.wsia-portlet-head
.wsia-portlet-body
.wsia-portlet-background
.wsia-portlet-background-edit	Allow for different backgrounds in edit and config mode.
.wsia-portlet-background-config	Do we need to redefine all styles mode dependent?