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/1.1.2/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 the latest version as of this writing, 1.0.9, 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.9</resource-server.version>
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:
<!-- 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>
Option 1: Mapping to the existin Liferay portal administrator role for administering the calendar portlet
The simplest solution is to map to the existing Liferay administrator role.
<!-- 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>Administrator</role-link> </security-role-ref>
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 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>