Monday, September 15, 2008

Portlet coordination

Portlet coordination is a new set of features brought by the Portlet 2.0 specification (aka JSR-286).
You can now define what is called "Public (or shared) render parameters" and events. The specification only defines the portlet *container* and not how portlets behave in a portal. It is up to the portal vendor to define how those shared render parameters and events will be bound.

In JBoss Portal we treat Shared render parameters in a similar way as events. We named "Event wiring" a link between an event to publish and an event to consume and "Parameter binding" the link between parameters. An event and a shared parameters are defined by a qualified name in a portal.

Implicit coordination
The most natural way it to bind (or wire) shared parameters (or events) that defined the same qname on the same page. This is the default behavior in JBoss Portal, and we call that "implicit binding" (or "implicit wiring" for events).

Here is a schema to understand, the portlets 1, 2, 3 define a render parameter called "urn:other:zip" while the portlet 4, 5, 6 define a render parameter called "urn:jboss:zipcode".
With the default behavior "implicit binding" any portlet modifying or accessing a render parameter with share the same value

Explicit coordination
This is a natural and common use case, but there are time when you don't want that behavior, let's say you don't want them to share the same value and somehow want to isolate all those windows. You can turn off the implicit binding by either modifying the *-object.xml descriptor or through the GUI.
Here we turned off the implicit binding and kept the implicit wiring.
Now all our windows have their public render parameters isolated.

Now we may want something in the middle, not all magically bound, neither all separated, even better, we bought the portlet represented in blue that has a shared render parameter which also represent a zipcode like ours. We do not want to make modification to that acquisition we simply want to tell the portal that we want to bind the zipcodes of windows 1 4 and 5. On top of that we want to bind 2 and 3. This can also be done wither through the descriptor file or though the admin portlet.
We now have the following scenario, without changing any code.

Voila ! We now have a way to "explicitely" define how shared render parameters are bound and it works in a similar way for event wiring.
Of course a nice addition to this would be the possibility to transform a render parameter or event payload on the fly (say the portlet you bought defines an render parameter string that represents an address, the format will probably be slightly different from the one you made yourself, we would need a class in between to do the transformation back and forth). We'll see how this feature get popular and how we can put that in the roadmap, but contributions are always welcome :)
Last but not least we've also added the notion of aliases for render parameters. Say you have the two shared render parameters "urn:jboss:zipcode" and "urn:other:zip", you know they are similar (it's just a string that contains a zipcode), you can group them in an alias. That alias name can be used to pass a value as a request parameter of the portal.
You can define the alias in the object descriptor or through the admin portlet, in the XML it would look like:


Now by passing a request parameter to the page, the windows will get an initial value equals to the parameter you passed. Say your page URL is you can pass a render parameters to your portlets by querying:, it's also what we call a page parameter.

I hope that I was able to give a not too long overview of implicit/explicit coordination, more details are available in the reference guide.

No comments: