Using Calendar Portlet in Liferay

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>

Including Fluid CSS

Step 1: Link to fluid css resources.

• 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
• Add the code snippet depicted in figure 1 to your css.jsp file. 

<!-- INSTRUCTIONS
| The below code snippet should be placed just below the include.jsp directive
| and above the tag that links to the calendar.css file.
-->
<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>

_{Figure 1}

Step 2: Place fluid css resources in rs directory.

• Download the Fluid Skinning System (FSS) css files. For the latest version of FSS please see the Fluid Project and download Fluid Infusion.
• Once downloaded, extract the calendar_portlet_fss.zip file.
• The calendar_portlet_fss.zip file extracts to the fss directory.

The fss directory needs to be placed in the following directory: LIFERAY_PORTAL_DIR/TOMCAT_DIR/webapps/CalendarPortlet/rs/fluid/1.1.2

Resolve the T.ui.keyCode fluid bug.

• The T.ui.keyCode is undefined error message, as depicted in Figure 2, is due to the inclusion of incompatible versions of the jQuery and fluid libraries.
• As a general rule, try to utilize the latest releases of both fluid and jQuery libraries.
• If your portal is running jQuery 1.2.6, it is recommended that you leverage fluid version 0.8.1. Please see the Fluid Wiki Download page for a list of past releases.
• Any additional versions of the fluid library added to the Calendar portlet should be placed in the following directory (see Figure 3 for example): LIFERAY_PORTAL_DIR/TOMCAT_DIR/webapps/CalendarPortlet/rs/fluid
  
  
  <sub>Figure 2
  
  
  Figure 3</sub>

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:

<!--
  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>

The simplest solution is probably to create a role explicitly for this privilege of administering the calendar portlet. This mapping tells the portlet and Liferay that the relevant Liferay role will be called "calendarAdmin":

<!--
  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>calendarAdmin</role-link>
</security-role-ref>

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.

 <!-- 
            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>Users</role-link>
        </security-role-ref>
        <security-role-ref>
            <role-name>usersWithBlackboardAccounts</role-name>
            <role-link>usersWithBlackboardAccounts</role-link>
        </security-role-ref>