Using Calendar Portlet in Liferay

This page exists to document how to use the Jasig Calendar Portlet in Liferay. It is initially written as instructions for use with Liferay Enterprise Edition 5.2 SP3 and the trunk of the calendar portlet. Arguably, this documentation should be moved into the liferay contrib directory in source control associated with this portlet so that it can be versioned with the portlet.

Address UI issues

Fixing CSS so that the date selector UI does not escape its container

There's a problem with the CSS inherited by the portlet when used in Liferay, such that this CSS is evident:

.ui-datepicker-inline {
 border: 0 none;
 display: block;
 float: left;
}

The problem here is that float.

Adding this to the calendar.css of the Calendar Portlet overrides that float and corrects the problem.

/* Liferay-specific fix for calendar jQuery widget escaping its container */

.upcal-miniview .ui-datepicker-inline, .upcal-fullview .ui-datepicker-inline { float: none }

Configuring the portlet to not include its own copy of JQuery and JQuery UI JavaScript

In Liferay, a version of JQuery and JQuery UI is already present and it doesn't work well for the portlet to include its own copy of these libraries. Fortunately, the portlet has a configuration parameter in portlet.xml to stop including its own copy of JQuery and JQuery UI.

<!--
 Set includeJQuery to true to explicitly import jQuery and
 jQuery UI javascript libraries within the portlet.  When true,
 this setting will also cause the portlet to use jQuery's
 noConflict feature in extreme mode.

 This setting should be set to "true" for uPortal 3.1 and above,
 and false for earlier uPortal versions or for Liferay.
 -->
 <preference>
   <name>includeJQuery</name>
   <value>false</value>
 </preference>

This portlet preference is set to "true" in the default portlet.xml. You need to change the setting to "false".

Modifying the JSPs to include Fluid JavaScript

Unfortunately, the inclusion of Fluid Infusion is gated by the same preference as inclusion of JQuery and JQuery UI. While Liferay provides viable versions of JQuery and JQuery UI, it does not by default provide Fluid Infusion, so in Liferay the portlet needs to include this.

In each of the three JSP pages calendarMobileView.jsp, calendarNarrowView.jsp, and calendarWideView.jsp, change this:

<c:if test="${includeJQuery}">
    <script type="text/javascript" src="<rs:resourceURL value="/rs/jquery/1.3.2/jquery-1.3.2.min.js"/>"></script>
    <script type="text/javascript" src="<rs:resourceURL value="/rs/jqueryui/1.7.2/jquery-ui-1.7.2.min.js"/>"></script>
    <script type="text/javascript" src="<rs:resourceURL value="/rs/fluid/1.1.2/js/fluid-all-1.1.2.min.js"/>"></script>
</c:if>

to this:

<c:if test="${includeJQuery}">
    <script type="text/javascript" src="<rs:resourceURL value="/rs/jquery/1.3.2/jquery-1.3.2.min.js"/>"></script>
    <script type="text/javascript" src="<rs:resourceURL value="/rs/jqueryui/1.7.2/jquery-ui-1.7.2.min.js"/>"></script>
</c:if>

<script type="text/javascript" src="<rs:resourceURL value="/rs/fluid/1.1.2/js/fluid-all-1.1.2.min.js"/>"></script>

Switch to a compatible version of Fluid

While the instructions above will succeed in suppressing this portlet's inclusion of jQuery (since the Liferay portal already provides jQuery) and yet having the portlet include Fluid (since Liferay does not provide Fluid), alas, the version of Fluid the portlet trunk is configured to use by default is not compatible with the older version of jQuery included in Liferay 5.2 SP3.

The most recent version of Fluid that works with the version of jQuery in Liferay 5.2 SP 3 is Fluid 0.8.1.

This switch will resolve the T.ui.keyCode is undefined error message, as depicted below. The error message is due to the inclusion of incompatible versions of the jQuery and Fluid libraries.

As a general rule, try to use the latest releases of both fluid and jQuery libraries. However, Liferay 5.2 SP 3 uses jQuery 1.2.6. Fluid version 0.8.1 is the recommended Fluid version for use with jQuery 1.2.6. See the Fluid Wiki Download page for a list of past releases.

Declare dependency on Fluid 0.8.1

In pom.xml, find the resources declaration:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
    <warName>CalendarPortlet</warName>
    <webXml>${basedir}/src/main/webapp/WEB-INF/web.xml</webXml>
    <overlays>
      <overlay>
        <groupId>org.jasig.resourceserver</groupId>
        <artifactId>resource-server-content</artifactId>
        <includes>
          <include>rs/famfamfam/silk/1.3/add.png</include>
          <include>rs/famfamfam/silk/1.3/arrow_left.png</include>
          <include>rs/famfamfam/silk/1.3/arrow_right.png</include>
          <include>rs/famfamfam/silk/1.3/calendar*.png</include>
          <include>rs/famfamfam/silk/1.3/cross.png</include>
          <include>rs/famfamfam/silk/1.3/page_edit.png</include>
          <include>rs/famfamfam/silk/1.3/tick.png</include>
          <include>rs/jquery/1.3.2/</include>
          <include>rs/jqueryui/1.7.2/</include>
          <include>rs/fluid/1.1.2/</include>
        </includes>
      </overlay>
    </overlays>
  </configuration>
</plugin>

and add the additional dependency as so:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
    <warName>CalendarPortlet</warName>
    <webXml>${basedir}/src/main/webapp/WEB-INF/web.xml</webXml>
    <overlays>
      <overlay>
        <groupId>org.jasig.resourceserver</groupId>
        <artifactId>resource-server-content</artifactId>
        <includes>
          <include>rs/famfamfam/silk/1.3/add.png</include>
          <include>rs/famfamfam/silk/1.3/arrow_left.png</include>
          <include>rs/famfamfam/silk/1.3/arrow_right.png</include>
          <include>rs/famfamfam/silk/1.3/calendar*.png</include>
          <include>rs/famfamfam/silk/1.3/cross.png</include>
          <include>rs/famfamfam/silk/1.3/page_edit.png</include>
          <include>rs/famfamfam/silk/1.3/tick.png</include>
          <include>rs/jquery/1.3.2/</include>
          <include>rs/jqueryui/1.7.2/</include>
          <include>rs/fluid/1.1.2/</include>
          
          <!-- additional include for Liferay 5.2 SP3 compatibility -->
          <!-- This is the latest version of Fluid that will work with the 
               version of jQuery in Liferay 5.2 SP3. -->
          <include>rs/fluid/0.8.1/</include>
        </includes>
      </overlay>
    </overlays>
  </configuration>
</plugin>

Modify the JSPs to use this version of Fluid

In each of the three JSP pages calendarMobileView.jsp, calendarNarrowView.jsp, and calendarWideView.jsp, change this:

<script type="text/javascript" src="<rs:resourceURL value="/rs/fluid/0.8.1/js/fluid-all-1.1.2.min.js"/>"></script>

(as already modified above)

to this:


<!-- Switched to a back version compatible with Liferay 5.2 SP3's jQuery 1.2.6 -->
<script type="text/javascript" src="<rs:resourceURL value="/rs/fluid/1.1.2/js/fluid-all-0.8.1.min.js"/>"></script>

Including Fluid CSS

This portlet depends on the Fluid Skinning System (fss). Alas, Liferay 5.2 SP3 doesn't make the Fluid Skinning System CSS available, and the Resource Server version in the trunk of the portlet doesn't either, so this portlet needs to be modified to include these files.

In order for it to be able to reference these CSS files, the fss files must be included in the portlet-local resources directory.

Step 1: Update dependency on Resource Server to get a later version

In pom.xml, update this:

<properties>
    	<!-- Dependency versions -->
    	<cas.version>3.1.8</cas.version>
    	<hsqldb.version>1.8.0.7</hsqldb.version>
    	<resource-server.version>1.0.5</resource-server.version>

to declare version 1.0.6 of resource-server, rather than the 1.0.5 there currently.

<properties>
    	<!-- Dependency versions -->
    	<cas.version>3.1.8</cas.version>
    	<hsqldb.version>1.8.0.7</hsqldb.version>
    	<resource-server.version>1.0.6</resource-server.version>

You might be tempted to upgrade all the way to version 1.0.9, which is a good idea, but requires an additional exclusion to avoid conflicting Spring Framework versions in underlying dependencies.

(TODO: Document using version 1.0.9 and the necessary exclusion.)

Step 2: Use the Fluid Skinning System that will now be available

Navigate to and open the css.jsp file. This file is located in the Calendar portlet.
- Source Location: CalendarPortlet/trunk/src/main/webapp/WEB-INF/jsp/css.jsp

Before:

<jsp:directive.include file="/WEB-INF/jsp/include.jsp"/>
<link rel="stylesheet" href="<c:url value="/css/calendar.css"/>" type="text/css"></link>

After:

<jsp:directive.include file="/WEB-INF/jsp/include.jsp"/>

<!-- added for Liferay 5.2 SP3 compatibility -->
<c:set var="RESOURCE"><rs:resourceURL value="/rs"/></c:set>
<link rel="stylesheet" href="${RESOURCE}/fluid/1.1.2/fss/css/fss-layout.css" type="text/css"></link>
<link rel="stylesheet" href="${RESOURCE}/fluid/1.1.2/fss/css/fss-text.css" type="text/css"></link>

<link rel="stylesheet" href="<c:url value="/css/calendar.css"/>" type="text/css"></link>

Map roles

Enable Calendar Administration

You only need to enable calendar administration if you want some adminstrative users to be able to administer this portlet through its UI, e.g. to define default calendar configurations and their audiences. The simplest use cases of simply allowing users to add iCal feeds of their choice in the portlet do not require this administrative capability.

The Calendar Portlet uses the JSR-168 API isUserInRole() to determine whether the presently accessing user is an administrator. You'll need to map the calendar portlet's name for an administrator role to an existing or new Liferay role.

In portlet.xml you'll find this:

<!--
  Adminisrative role mapping.  This mapping is required if you
  want to use the administrative features.
 -->
<security-role-ref>
  <role-name>calendarAdmin</role-name>
  <role-link>local.2</role-link>
</security-role-ref>

Change it to

<!--
  Administrative role declaration.
  Users in this role can administer the default calendars in the portlet
  via an in-portlet UI.
  This role is declared here and is mapped in liferay-portlet.xml.
  -->
  <security-role-ref>
    <role-name>calendarAdmin</role-name>
  </security-role-ref>


  <!-- 
  Additional roles for assigning default calendars.  Any roles
  you wish to use must be declared here.  They are mapped to Liferay roles in
  liferay-portlet.xml 
  -->
  <security-role-ref>
    <role-name>everyone</role-name>
  </security-role-ref>

Option 1: Mapping to the existing Liferay portal administrator role for administering the calendar portlet

The simplest solution is to map this "calendarAdmin" JSR-168 role in the portlet to the existing Liferay administrator role.

For portlets for use with Liferay, you put this mapping in liferay-portlet.xml alongside the existing portlet.xml. Add a liferay-portlet.xml with this content:

<?xml version="1.0"?>
<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 4.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_4_2_0.dtd">
<liferay-portlet-app>
    <portlet>
        <portlet-name>calendar</portlet-name>
        <private-request-attributes>true</private-request-attributes>
    </portlet>

    <role-mapper>
        <role-name>calendarAdmin</role-name>
        <role-link>Administrator</role-link>
    </role-mapper>
    <role-mapper>
        <role-name>everyone</role-name>
        <role-link>User</role-link>
    </role-mapper>
    
</liferay-portlet-app>

More to configure in liferay-portlet.xml

(You can define all sorts of other interesting things in liferay-portlet.xml to better integrate this portlet with Liferay, like declaring the category under which you'd like it to appear when users add the application. See the Liferay product documentation for these additional features of liferay-portlet.xml. In the interest of focus, this wiki page is attempting to keep its scope down to the bare minimum you need to do to get this portlet working in Liferay.)

Option 2: Creating and mapping to a new Liferay role for administering the calendar portlet

Another solution is to create a role explicitly for this privilege of administering the calendar portlet. You'd take this route if the set of users who should be able to administer the calendar portlet is different from the set of users who should have administration capabilities over the entire portal.

This mapping (in liferay-portlet.xml) tells the portlet that the relevant Liferay role will be called "calendarAdmin":

<!--
  Administrative role mapping.  This mapping is required if you
  want to use the administrative features.
 -->
<role-mapper>
  <role-name>calendarAdmin</role-name>
  <role-link>calendarAdmin</role-link>
<role-mapper>

Of course, the role "calendarAdmin" does not exist in out of the box Liferay 5.2 SP3. You'll need to add it.

As a sufficiently privileged user in Liferay, access the Control Panel. Under Portal, select Roles. Click Add. Name your new role "calendarAdmin", give it a description if you like. The type of role is a bit complicated – for the simplest use cases, leave this as "Regular" (a universal, portal-wide role). Click "Save" to persist your new role.

Notice your new role in the list of roles that you see after saving. Click Actions->Assign Members for this new "calendarAdmin" role and add users and groups to this role who ought to be able to administer the calendar portlet.

Once you've added users to this role and configured the portlet to map its calendarAdmin checking to that role via portlet.xml (the steps described above), sufficiently privileged users should start seeing a "Calendar Administration" link in the wider focused view of the portlet. This will allow administrators to e.g. configure default calendars to appear to some users.

Enable calendar audience targeting

Part of the point of being a calendar portlet administrator is to be able to define calendar configurations that are experienced by some users. That "some users" bit is also defined by an isUserInRole() check and a role. In portlet.xml, you can see several other default roles listed:

 <!-- 
            Additional roles for assigning default calendars.  Any roles
            you wish to use must be assigned keys here. 
        -->
        <security-role-ref>
            <role-name>everyone</role-name>
            <role-link>local.0</role-link>
        </security-role-ref>
        <security-role-ref>
            <role-name>student</role-name>
            <role-link>local.1</role-link>
        </security-role-ref>
        <security-role-ref>
            <role-name>faculty</role-name>
            <role-link>local.2</role-link>
        </security-role-ref>
        <security-role-ref>
            <role-name>staff</role-name>
            <role-link>local.3</role-link>
        </security-role-ref>

You only need to retain and map those roles you're actually going to use (which should be at least once, since if it's none you probably didn't need to map the calendar admin role either since you're not administering the portlet to configure default calendar configurations pushed to particular audiences.)

For instance, if you're going to add the Blackboard calendar adapter to the portlet, you might define a role "usersWithBlackboardAccounts" and then administratively publish the Blackboard adapter's calendar configuration only to users in this role.

In Liferay, you'd define the membership of that role to be those users that you expect to have Blackboard accounts (ultimately fulfilling the role with membership in a community or a group that's e.g. synced in from LDAP, since you presumably don't want to be manually adding users to this role).

You might also create an Everyone role and map it to the Users role in Liferay (all authenticated users) if you want to reach all logged in users. And so on.

In portlet.xml:

 <!-- 
            Additional roles for assigning default calendars.  Any roles
            you wish to use must be assigned keys here. 
        -->
        <security-role-ref>
            <role-name>everyone</role-name>
        </security-role-ref>
        <security-role-ref>
            <role-name>usersWithBlackboardAccounts</role-name>
        </security-role-ref>

And in liferay-portlet.xml:

    <role-mapper>
        <role-name>everyone</role-name>
        <role-link>User</role-link>
    </role-mapper>
    <role-mapper>
      <role-name>usersWithBlackboardAccounts</role-name>
      <role-link>usersWithBlackboardAccounts</role-name>
    </role-mapper>