5.2.2.5. Injecting a portlet using Dynamic Container

The mechanism

If you want to inject a portlet to every page in a site, you might add it directly to the shared layout (sharedlayout.xml). However, in case you have more than one extension that overrides sharedlayout.xml, only the last loaded one takes effect. This leads to trouble that portlets injection cannot be solved in packaging, it will require extra tasks in deployment (like merging several layouts from different projects).

As of 4.1, the trouble is solved by the Dynamic Container feature. A shared layout and an extension get involved in how it works:

The shared layout should contain some Dynamic Container instances

To make a site ready to inject portlets, there should be some Dynamic Containers added to the shared layout. This is done by sharedlayout.xml, like this:


<container id="top-dynamic-container" template="system:/groovy/portal/webui/container/UIAddOnContainer.gtmpl">

    <name>top-dynamic-container</name>

    <factory-id>addonContainer</factory-id>

</container>

The extension project should configure a component plugin to inject portlets to a container.
So it is important that the extension project is aware of the container name. The configuration will be described later.
In the heart of the feature is the component plugin org.exoplatform.commons.addons.AddOnPluginImpl that takes care of injecting specified portlets to a specified Dynamic Container. This makes Dynamic Container a special kind of container, because the portlets that it will contain are pre-defined. In other words, the portlet drag-and-drop is not in the Dynamic Container designation.

So in this way, whenever the named container instance is put into a page, or all pages via sharedlayout.xml, the portlet injection is done automatically. An extension does not have to override the layout.

Example

In the following example, you inject the "Help" portlet (a built-in, for simplification) into all pages of the Intranet site. The Help portlet is already featured at the top right of the homepage by default, so you will add another one to the left. The source code of this example is available here for downloading.

Make a portal extension as described in Portal extension section.

Edit WEB-INF/conf/configuration.xml:


<configuration

        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"

        xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">



    <external-component-plugins>

    <target-component>org.exoplatform.commons.addons.AddOnService</target-component>

    <component-plugin>

        <name>addPlugin</name>

        <set-method>addPlugin</set-method>

        <type>org.exoplatform.commons.addons.AddOnPluginImpl</type>

        <description></description>

        <init-params>

        <value-param>

            <name>priority</name>

            <value>5</value>

        </value-param>

        <value-param>

            <name>containerName</name>

            <value>left-topNavigation-container</value>

        </value-param>

        <object-param>

            <name>help-portlet</name>

            <description></description>

            <object type="org.exoplatform.portal.config.serialize.PortletApplication">

            <field name="state">

                <object type="org.exoplatform.portal.config.model.TransientApplicationState">

                <field name="contentId">

                    <string>platformNavigation/UIHelpPlatformToolbarPortlet</string>

                </field>

                </object>

            </field>

            </object>

        </object-param>

        </init-params>

    </component-plugin>

    </external-component-plugins>

</configuration>

In which:

The container instance is identified by containerName. Find below a picture that depicts the default layout of the Intranet site.
The portlets are identified by contentId. In the example, platformNavigation is the webapp name (declared in web.xml), and UIHelpPlatformToolbarPortlet is the portlet name (declared in portlet.xml).
To inject more than one portlet, add more object-param with different names.

Default Dynamic Container instances

Here are the Dynamic Container instances in the Intranet site:

For a customized site, you can manage Dynamic Containers by customizing sharedlayout.xml. The configuration sample is given above. There are two templates of Dynamic Container:

system:/groovy/portal/webui/container/UIAddOnContainer.gtmpl
system:/groovy/portal/webui/container/UIAddOnColumnContainer.gtmpl