Zimlet Developers Guide:Portal

From Zimbra :: Wiki

Jump to: navigation, search
Zdg-6-menu-icon-zimbra.jpg Introduction Zdg-6-menu-icon-green-flag.png Getting Started Zdg-6-menu-icon-terminal.png Dev Environment Setup Zdg-6-menu-icon-gear.png Developing Zimlets Zdg-6-menu-icon-advanced.jpg
Advanced Concepts
Application Context
Templates
Java & JSP
Portal
Zimlet Tab
Internationalization
Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets


Developer Article

Article Information

This article applies to the following ZCS versions.
  ZCS 8.0 Article  ZCS 8.0
  ZCS 7.0 Article  ZCS 7.0
  ZCS 6.0 Article  ZCS 6.0

Contents

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:

  1. Open a terminal and change to the zimbra user:
    su - zimbra
    
  2. Set the portal feature COS to TRUE:
    zmprov ma user@domain.com zimbraFeaturePortalEnabled TRUE
    
  3. 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>

Zcs-6-portal-layout.png

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".


Verified Against: Zimbra Collaboration Server 7.0 Date Created: 12/29/2009
Article ID: http://wiki.zimbra.com/index.php?title=Zimlet_Developers_Guide:Portal Date Modified: 04/11/2014
Personal tools