Zimlet Developers Guide:Portal
Zimlet Developers Guide: Portal
|
You are looking at legacy Zimlet documentation. For Zimbra Modern UI Zimlet development go to: https://wiki.zimbra.com/wiki/DevelopersGuide#Zimlet_Development_Guide. |
Enabling the Portal Feature
The Zimbra portal feature creates a Home tab in the Zimbra Web Client that can be used as a portal landing-page. This portal page can be configured to display zimlets as "portlets".
The portal feature can be enabled by setting the zimbraFeaturePortalEnabled CoS to TRUE using the zmprov command. Additionally, you can set the portal name to be used. To enable portal for a specific user:
- Open a terminal and change to the zimbra user:
su - zimbra
- Set the portal feature COS to TRUE:
zmprov ma user@domain.com zimbraFeaturePortalEnabled TRUE
- Set the portal for the user to id "example":
zmprov ma user@domain.com zimbraPortalName example
Portal Files
A portal consists primarily of a manifest.xml file that configures the portal "id" and defines which zimlets are used in the portal. The manifest also includes the base HTML layout for the portal page. The manifest file should be located in a directory name that matches the portal id and placed in the {zcs-install-dir}/jetty/webapps/zimbra/portals/{portal-id} directory.
An example portal (where id="example") is provided at:
{zcs-install-dir}/jetty/webapps/zimbra/portals/example/manifest.xml
Portal Layout
The portal manifest.xml specifies the portlets and their associated zimlet (along with any portlet properties) to load. In the image below, three portlets are shown (with panel names "panel_1 - 2 - 3" respectively. The manifest.xml would define the panel_2 portlet as:
<portlets>
...
<portlet zimlet="com_zimbra_html">
<panel id="panel_2" />
<property name="url">/zimbra/portals/example/jsppage.jsp</property>
<property name="type">inline</property>
</portlet>
...
</portlets>
The portal manifest.xml defines the layout for the portal page. In the following layout, two portlets (panel_1 and panel_2) are displayed on the first row of the table. The portlet panel_3 is displayed on the second row and spans two cells:
<html><![CDATA[
<h2>Portal Page Layout</h2>
<table border=0 cellpadding=0 cellspacing=0 width=100% height=100%>
<tr valign="top">
<td>
<h3>Portlet Panel #1</h3>
<div id='panel_1'></div>
</td>
<td>
<h3>Portlet Panel #2</h3>
<div id='panel_2'></div>
</td>
</tr>
<tr valign=top>
<td colspan="2">
<h3>Portlet Panel #3</h3>
<div id='panel_3'></div>
</td>
</tr>
</table>
]]></html>
Portal Manifest File Reference
The following provides a reference for the elements in the Portal Manifest File.
<portal>
The <portal> element is the enclosing element in the Manifest File. The <portal> element has the following attributes:
| Attribute | Required / Optional | Range of Values | Default Value | Description |
| id | Required | A valid portal id. | N/A | The id attribute is the portal id (or "portal name") and is a required attribute. This must be the same as the directory name for the portal. For example, {zcs-install-dir}/jetty/webapps/zimbra/portals/{portal-id}/manifest.xml.
|
The following table describes the elements you can define within a <portal> element.
| Order | Element | Required / Optional | Description |
| 1 | portlets | Required (1 allowed) | The element that describes the portlets to be used with the portal. See <portlets> for more information. |
| 2 | html | Required (1 allowed) | Describes the portal layout. See <html> for more information. |
Example:
<portal id="example"> <portlets> ... define your <portlet> elements ... </portlets> <html><![CDATA[ ... define your HTML portal page layout ... ]]></html> </portal>
<portlets>
This element defines the list of portlets used with the portal.
The following table describes the elements you can define within a <portlets> element.
| Order | Element | Required / Optional | Description |
| 1 | portlet | Required (1 or more allowed) | The element that describes the portlets to be used with the portal. See <portlet> for more information. |
Example:
<portlets>
<portlet zimlet="com_zimbra_html">
<panel id="portlet_panel_id_1" />
<property name="url">/zimbra/portals/example/htmlpage.html</property>
<property name="refresh">30000</property>
</portlet>
<portlet zimlet="com_zimbra_html">
<panel id="portlet_panel_id_2" />
<property name="url">/zimbra/portals/example/jsppage.jsp</property>
<property name="refresh">30000</property>
</portlet>
<portlet zimlet="com_zimbra_html">
<panel id="portlet_panel_id_3" />
<property name="url">/zimbra/portals/example/mypage.html</property>
<property name="refresh">30000</property>
</portlet>
</portlets>
<portlet>
This element defines the zimlet, panel and properties (if applicable) for the portal. The <portlet> element has the following attributes:
| Attribute | Required / Optional | Range of Values | Default Value | Description |
| zimlet | Required | A valid zimlet name. | N/A | The name of the zimlet to use as this portlet. |
The following table describes the elements you can define within a <portlet> element.
| Order | Element | Required / Optional | Description |
| 1 | panel | Required (1 allowed) | Defines the panel for the portal. See <panel> for more information. |
| 2 | property | Optional (0 or more allowed) | Properties for the zimlet. See <property> for more information. |
Example:
<portlet zimlet="com_zimbra_html"> <panel id="portlet_panel_id_1" /> <property name="url">/zimbra/portals/example/dynamic.jsp</property> <property name="refresh">30000</property> </portlet>
<panel>
This element defines the panel for the portlet. The <panel> element has the following attributes:
| Attribute | Required / Optional | Range of Values | Default Value | Description |
| id | Required | A valid id. | N/A | The id of the panel for this portlet. This id is used in the HTML layout for the portal page to designate where the portal displays. |
Example:
<panel id="portlet_panel_id_1" />
<property>
The <property> element is used to define properties to pass to the zimlet. The content of the element is the value of the parameter.
The <property> element has the following attributes:
| Attribute | Required / Optional | Range of Values | Default Value | Description |
| name | Required | A attribute name | N/A | Specifies the property name |
Example:
<property name="myprop">thisismyprop</property>
<html>
The <html> element wraps the HTML code for the portal page layout.
<html><![CDATA[
... insert your HTML code ...
]]></html>
Portal Zimlets
The following zimlets are provided to help display simple portlets on your portal page:
| Portlet | Description |
| com_zimbra_html | This portlet loads the content of the specified URL into the portal page. |
com_zimbra_html
| Property | Required / Optional | Default Value | Description |
| url | Required | N/A | The URL of the page to load. This can be a page located on the Zimbra server (for example, a JSP page or an HTML page) or can located external from Zimbra.
Note: if you plan to load pages external from Zimbra as "inline", you will need to configure the Proxy Servlet. See Proxy Servlet Setup for more information on configuring allows domains. |
| refresh | Optional | N/A | The refresh interval for the portlet (in milliseconds). |
| type | Optional | inline, iframe | Designates whether to load the URL content "inline" in the page or as an "iframe". Defaults to "inline". |
