Author: thomas.heute(a)jboss.com Date: 2008-10-28 09:24:28 -0400 (Tue, 28 Oct 2008) New Revision: 12197 Added: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/alias_example.png docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/create_alias_3.png docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/parameter_example.png Removed: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/create_aliast_3.png Modified: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/wiring_example.png docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/modules/coordination.xml Log: - Finished first pass on coordination GUI. Would need a re-reading from a pair of fresh eyes. - Fixed incorrect name for third step image of alias creation. Copied: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/alias_example.png (from rev 12196, docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/alias_example.png) =================================================================== (Binary files differ) Copied: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/create_alias_3.png (from rev 12196, docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_alias_3.png) =================================================================== (Binary files differ) Deleted: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/create_aliast_3.png =================================================================== (Binary files differ) Copied: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/parameter_example.png (from rev 12196, docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/parameter_example.png) =================================================================== (Binary files differ) Modified: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/images/coordination/wiring_example.png =================================================================== (Binary files differ) Modified: docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/modules/coordination.xml =================================================================== --- docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/modules/coordination.xml 2008-10-28 13:12:36 UTC (rev 12196) +++ docs/tags/JBoss_Portal_2_7_0/referenceGuide/en/modules/coordination.xml 2008-10-28 13:24:28 UTC (rev 12197) @@ -133,29 +133,88 @@ <title>Definition</title> <para> - Explicit alias binding define a name of page scoped parameter that will apply - value to specified portlet windows public parameters. + <emphasis>Alias bindings</emphasis> are a JBoss Portal specific feature which allows users to define an + alias to a public render parameter that can be used in URLs to pass a value to all portlet windows reacting + to the aliased public parameter(s). The syntax for the URL is as follows: + <literal>{portal URL}/{page name}?{alias name}={alias value}</literal>. </para> - <programlisting><![CDATA[http://localhost:8080/portal/portal/default/Coordination+Samples?aliasBinding1=someValue]]></programlisting> + <para> + It is, for example, possible to alias public render parameters <literal>paramA</literal> and + <literal>paramC</literal> to the "<literal>alias</literal>" name so that JBoss Portal's event bus can + transmit that value to interested portlets on a given page when the requested page URL contains a value + for the appropriate URL parameter: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/alias_example.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> </sect2> - <sect2> + <sect2> <title>Configuration via XML</title> - <para>TODO</para> - <programlisting role="XML"><![CDATA[<coordination> + <para> + Explicit alias bindings can be defined in any page definition of your <literal>*-object.xml</literal> + descriptors. For example, this is how the example that we detailed above would be implemented, within a + page definition: + </para> + <programlistingco> + <areaspec> + <area id="coordination.alias.coordination" coords='2' /> + <area id="coordination.alias.bindings" coords='3' /> + <area id="coordination.alias.implicit" coords='4' /> + <area id="coordination.alias.binding" coords='5' /> + </areaspec> + <programlisting><![CDATA[... +<coordination> <bindings> <implicit-mode>FALSE</implicit-mode> <alias-binding> - <id>aliasBinding1</id> - <qname>foo</qname> + <id>alias</id> + <qname>paramA</qname> + <qname>paramC</qname> </alias-binding> - <alias-binding> - <id>aliasBinding2</id> - <qname>bar1</qname> - <qname>{urn:jboss:portal:samples:daa2}daa2</qname> - </alias-binding> </bindings> </coordination>]]></programlisting> + <calloutlist> + <callout arearefs="coordination.alias.coordination"> + <para> + Coordination configuration is done via the newly introduced <literal>&lt;coordination&gt;</literal> + element. + </para> + </callout> + <callout arearefs="coordination.alias.bindings"> + <para> + Alias bindings are defined using the <literal>&lt;bindings&gt;</literal> element. Note that this + element is also where parameter bindings are defined. + </para> + </callout> + <callout arearefs="coordination.alias.implicit"> + <para> + We specify here that we want JBoss Portal to send parameter values when an explicit bindings are + defined (<literal>&lt;implicit-mode&gt;</literal> set to <literal>FALSE</literal>). + </para> + </callout> + <callout arearefs="coordination.alias.binding"> + <para> + An alias binding definition consists of: + <itemizedlist> + <listitem> + <para>an id used to identify it</para> + </listitem> + <listitem> + <para> + a list of public render parameter names or previously defined alias or parameter binding + names + </para> + </listitem> + </itemizedlist> + In this example, we defined an alias binding named "<literal>alias</literal>" which aliases + the public render parameters <literal>paramA</literal> and <literal>paramC</literal>. + </para> + </callout> + </calloutlist> + </programlistingco> </sect2> <sect2> <title>Graphical configuration</title> @@ -190,34 +249,106 @@ <title>Definition</title> <para> - Binds JSR-286 shared parameters. With implicit binding parameters with the - same public name are shared. With explicit binding any public parameters can - share values. Windows for which such binding applies are explicitly defined. + A <emphasis>parameter binding</emphasis> allows users to specify that public render parameters with + different names are semantically equivalent so that when one such parameter is updated, all the portlets + that can handle such a parameter receive the update, regardless of the name of the parameter that got + updated. In the <emphasis>implicit</emphasis> case, portlets can only react to changes of values in + parameters whose name they know. </para> + + <para> + Consider the following example. We are deploying two portlets, <literal>Portlet A</literal> and + <literal>Portlet B</literal>, from different vendors and assign them to + <literal>Window A</literal> and <literal>Window B</literal>, respectively. Each portlet can react to a + specific public render parameter (<literal>{nsA}paramA</literal> and <literal>{nsB}paramB</literal>, + respectively). Under the <emphasis>implicit</emphasis> coordination model, these portlets wouldn't be able + to communicate even if both parameters were semantically equivalent. JBoss Portal's explicit coordination + model allows users to explicit the semantic link between both parameter names such that, when + <literal>Portlet A</literal> updates the value of <literal>{nsA}paramA</literal>, <literal>Portlet B</literal> + gets notified of the update via a change of value of <literal>{nsB}paramB</literal>: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/parameter_example.png" format="png" align="center" + valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </sect2> <sect2> <title>Configuration via XML</title> - <para>TODO</para> - <programlisting role="XML"><![CDATA[<coordination> + <para> + Explicit parameter bindings can be defined in any page definition of your <literal>*-object.xml</literal> + descriptors. For example, this is how the example that we detailed above would be implemented, within a + page definition: + </para> + <programlistingco> + <areaspec> + <area id="coordination.parameter.coordination" coords='2' /> + <area id="coordination.parameter.bindings" coords='3' /> + <area id="coordination.parameter.binding" coords='4' /> + <area id="coordination.parameter.windowcoord" coords='6' /> + </areaspec> + <programlisting><![CDATA[... +<coordination> <bindings> - <implicit-mode>FALSE</implicit-mode> <parameter-binding> - <id>parameterBinding1</id> + <id>parameterBinding</id> <window-coordination> - <window-name>SomePortletWindow1</window-name> - <qname>foo</qname> + <window-name>Window A</window-name> + <qname>{nsA}paramA</qname> </window-coordination> <window-coordination> - <window-name>SomePortletWindow2</window-name> - <qname>foo</qname> + <window-name>Window B</window-name> + <qname>{nsB}paramB</qname> </window-coordination> - <window-coordination> - <window-name>SomePortletWindow2</window-name> - <qname>{urn:jboss:portal:samples:daa1}daa1</qname> - </window-coordination> </parameter-binding> </bindings> </coordination>]]></programlisting> + <calloutlist> + <callout arearefs="coordination.parameter.coordination"> + <para> + Coordination configuration is done via the newly introduced <literal>&lt;coordination&gt;</literal> + element. + </para> + </callout> + <callout arearefs="coordination.parameter.bindings"> + <para> + Parameter bindings are defined using the <literal>&lt;bindings&gt;</literal> element. Note that this + element is also where alias bindings are defined. Note here that we don't specify a value for the + <literal>&lt;implicit-mode&gt;</literal> element, it will thus default to <literal>TRUE</literal>, + meaning that implicit binding of parameters will also be performed by JBoss Portal in addition to + the explicit binding we are defining here. + </para> + </callout> + <callout arearefs="coordination.parameter.binding"> + <para> + A parameter binding definition consists of: + <itemizedlist> + <listitem> + <para>an id used to identify it</para> + </listitem> + <listitem> + <para> + a list of <literal>&lt;window-coordination&gt;</literal> elements identifying which + parameters will be bound for which portlets + </para> + </listitem> + </itemizedlist> + In this example, we defined a parameter binding named "<literal>parameterBinding</literal>" which + specifies that whenever <literal>Window A</literal> or <literal>Window B</literal> updates the + value of the public parameter <literal>{nsA}paramA</literal> or <literal>{nsA}paramA</literal> + (respectively), the other will receive the new value for the public render parameter it knows about. + </para> + </callout> + <callout arearefs="coordination.parameter.windowcoord"> + <para> + A window / parameter name pair identifying either a public parameter to be wired. + </para> + </callout> + </calloutlist> + </programlistingco> + </sect2> <sect2> <title>Graphical configuration</title>