Jivespace Community Blog

Customization Part 2: Upgrading Themes and FTL files

communities@jivesoftware.com — Fri, 27 Jun 2008 03:37:27 GMT

This post is the second in a series of blog posts about customizing for Clearspace 2.x. The first post covered general information about Customizations in Clearspace 2.x. This post continues the series with more information about upgrading themes and FreeMarker template (FTL) files.

Each new version of Clearspace includes changes to FTL files and version 2 is no exception. Typically these changes are needed to support new or enhanced features. The FTL changelog included with a Clearspace release provides a list of the FTL files that were changed from the previous version. However, changes in version 2 have pretty much touched every template. In most cases these changes require a simple search-and-replace to fix. But some changes are more substantial.

The information on upgrading themes suggests an incremental process for making your changes that could save you some aggravation.

The following list suggests the tips and best practices for upgrading your templates.

When you've overridden existing Clearspace templates (as in a theme), start with new version 2 FTL files that correspond to the version 1 files in your theme. Then, working from your customized version of the version 1 template, transfer your changes to to the version 2 template. Updating the new templates might help you avoid accidentally transferring code from version 1 that no longer works on version 2. This is especially important given that FreeMarker errors are difficult to debug; errors don't show up until run time. Weaving your version 1 changes into the version 2 templates will make the process more systematic.As you copy your changes into the version 2 template, keep in mind the changed items described below.
The version 1 pages whose templates were community.ftl and main.ftl -- community pages and the home page -- can be easily customized with widgets in version 2. Before you set out to upgrade these pages, take a look at how much of your customization work could be accomplished by using widgets on the version 2 templates. Using widgets might reduce the amount of customization you need to do and greatly reduce any work in future upgrades.
If you've overridden community.ftl and want to upgrade it, note that the template has been split into multiple FTL files. This was done to divide logically what was a very large template.
Replace WebWork directives with their Struts counterparts. Clearspace version 2 replaces WebWork conventions with Struts. This is pretty much just search-and-replace work to replace @ww. (for WebWork) with @s (for Struts) . The following example shows how to update the url directive. Notice that the updated code also omits the includeParams='none' attribute; in Struts 2, which Clearspace version 2 uses, none is the default value for includeParams.Version 1 (supporting WebWork):

<style type="text/css" media="screen">
    @import "<@ww.url value='/styles/jive-blog.css' includeParams='none'/>";
</style>

Version 2 (supporting Struts):

<style type="text/css" media="screen">
    @import "<@s.url value='/styles/jive-blog.css'/>";
</style>

Update calls to APIs that have been consolidated and simplified. Pay attention to the places in a template where code calls methods directly (although, as a best practice, you should avoid calling methods in FTL code and use actions instead). Here's an example in which you'd replace a call to a JiveGlobals methods with a call to JiveResourceResolver:Version 1 (using JiveGlobals ):

<@ww.text name="doc.viewer.more_recent_ver.text">
    <@ww.param><a href="></a>"></@ww.param>
    <@ww.param></a></@ww.param>
</@ww.text>

Version 2 (using JiveResourceResolver ):

<@s.text name="doc.viewer.more_recent_ver.text">
    <@s.param><a href="></a>"></@s.param>
    <@s.param></a></@s.param>
</@s.text>

Here's another example where the change was from another class and method, but again to JiveResourceResolver:
Version 1 (using CommunityUtils ):

<a href="></a>?view=documents" 
    class="jive-link-more"><@ww.text name="doc.main.brdcrmb.documents.link" /></a>

Version 2 (using JiveResourceResolver ):

<a href="></a>?view=documents" 
    class="jive-link-more"><@s.text name="doc.main.brdcrmb.documents.link" /></a>

Update community references to container references. One twist on the API changes means that both projects and communities (also known as "spaces") are represented conceptually as containers. In the version 2 API, the Community and Project interfaces both inherit from JiveContainer. To disambiguate between the projects and communities, you'll need to pass a container type with your action calls. The actual disambiguation is handled by Clearspace, however, when it intercepts the call before passing it to the action. The net effect is that the action itself receives only the container ID parameter, not the container type. Here's an FTL example:Version 1 (specifying a community by passing its community ID)

<@ww.action name="community-breadcrumb" executeResult="true" ignoreContextParams="true">
    <@ww.param name="communityID" value="${community.ID?c}" />
</@ww.action>

Version 2 (specifying a community by passing both its type and its ID)

<@s.action name="community-breadcrumb" executeResult="true" ignoreContextParams="true">
    <@s.param name="containerType" value="${container.objectType?c}" />
    <@s.param name="container" value="${container.ID?c}" />
</@s.action>

Update code that handles content. This includes code that gets content for display as wiki markup, HTML, and so on. Among the API changes were several designed to streamline and add structure to how you handle content. For example, in version 1, to get content as wiki markup you would have called methods of the message or document or comment itself. In version 2, you pass the content object to a method inherited from JiveActionSupport. These methods include renderToText, renderToHtml, renderSubjectToHtml, and so on. Here's an example using convertToWikiSyntax:Version 1 (using content object method)

<textarea id="comment-body-edit-${comment.ID?c}" name="body" rows="10"
    style="width:100%;font-family:verdana,arial,helvetica,sans-serif;font-size:8pt;"
    class="jive-comment-textarea">${comment.unfilteredBody!?html}</textarea>

Version 2 (using JiveActionSupport method)

<textarea id="comment-body-edit-${comment.ID?c}" name="body" rows="10"
    style="width:100%;font-family:verdana,arial,helvetica,sans-serif;font-size:8pt;"
    class="jive-comment-textarea">${action.convertToWikiSyntax(comment)!?html}</textarea>

Removed and Renamed FTL Files

Version 1 FTL File	Version 2 Change
community-document-picker.ftl	Renamed to container-document-picker.ftl
community-thread-picker.ftl	Renamed to container-thread-picker.ftl
import-callback-communitynntp.ftl	Removed.
import-directory-error.ftl	Removed.
import-directory-updatetags.ftl	Removed.
import-directory.ftl	Removed.
datepicker.ftl	Renamed to datetimepicker.ftl

Upgrading Themes

Nearly all of your work upgrading themes will focus on upgrading FreeMarker template (FTL) files. The way you build and deploy themes is unchanged from version 1.

But wait -- there's more. Having said that, the best practice recommendation in version 2 is to use widget-customized pages wherever possible as an alternative to custom FTLs. You can use widgets in more places than in version 1; check out the section on upgrading widgets for more.

Here's why you should use widgets:

You can do with widgets much of what you'd do with custom FTL markup. In addition, you can write logic in Java behind the your widget UI.
Building widgets to support new features is a good deal tidier than adding new FTL files. While custom FTL files override default FTL files, widgets are encapsulated by the plugin deployment model -- essentially sandboxed.
When it's time to upgrade Clearspace, the work needed to upgrade FTL files you've customized would likely be a good deal greater than what's needed to upgrade a widget.

Suggested Upgrade Process

Use the following steps as a systematic way to upgrade your themes.

Consider which custom FTLs in your themes can be replaced by customizing the page with widgets.
Use jive.devMode Jive property for debugging. By default, Clearspace hides FreeMarker errors in themes. With dev mode on, you'll see them.
Disable themes while upgrading them.
Enable your custom FTL files one at a time. Debugging incrementally will make the process smoother.

The information above along with more details can be found in the Upgrading Extensions to 2.0 documentation.

Theming in Clearspace 2.0

communities@jivesoftware.com — Mon, 12 May 2008 16:58:01 GMT

As you know, we changed a few things in our underlying architecture for Clearspace 2.0, including some changes in the Freemarker templates as a result of moving from Webwork to Struts along with some other changes. In this video, Matt Walker, Professional Services Engineer at Jive Software, talks about the process of upgrading existing themes along with plenty of best practices to make your themes more easily upgradeable in the future.

Matt also did an earlier screencast as an Introduction to Skinning Clearspace, which you might also want to watch along with this video.

You can also download the Quicktime version (Caution: file is ~200MB), or you can watch a larger version online, which will improve readability of embedded screenshots (recommended).

The entire presentation is also attached below as a PDF file.

Creating Dynamic Template Content in Clearspace

communities@jivesoftware.com — Fri, 08 Feb 2008 17:51:35 GMT

Jive's Rick Palmer, Professional Services Engineer, takes about 5 minutes to explain how to insert dynamic content into your Clearspace FreeMarker templates. The slide below provides more details.

Or you can download the Quicktime Movie (Caution! 122MB)

Introduction to Skinning Clearspace

communities@jivesoftware.com — Thu, 17 Jan 2008 19:28:35 GMT

Learn the basics of customizing your Clearspace theme in this introduction to skinning Clearspace with Matt Walker, professional services engineer (and juggler!) at Jive Software.

Or you can download the Quicktime version (Caution! ~100MB file)

You can also learn more about customizing Clearspace by visiting our documentation space!

The Switch to Freemarker

nick@jivesoftware.com — Fri, 20 Jul 2007 16:20:00 GMT

Where are all the JSP's? That is a question we have been hearing a lot lately, after deciding that the view layer of Clearspace would be built on an open alternative to JSP, Freemarker. What is Freemarker? Freemarker is simply a "template engine"; a generic tool to generate text output based on tempaltes. The next question that usually follows: Why?

Common problems with JSP

Java code is too tempting, even though it is considered bad design to mix presentation with core logic, everyone knowingly does it.
Java code is required to do mundane things, such as <a href="<%= request.getContextPath() %>/index.html">Home page</a>
Simple tasks are difficult, such as escaping html, or formatting a date
Looping is verbose, awkward and messy
Bad exception handling, printing out things like NullPointerExceptions to the user
Need a compiler and any change needs to be recompiled.
Various application server bugs. We have recently run into a few problems on 'unnamed' application servers where the jsp's are created importing the servlet package without fully qualifying names, This causes us to have class name problems.

Freemarker as an alternative

To fully realize the benefits of the MVC Pattern, a true separation of Java Code (the controller) and the HTML (the view) is required. Using a template engine, such as Freemarker, as your view will solve many of the problems listed above. The underlying design will be cleaner, the syntax clearer, the error messages more meaningful, and the application more customizable.

Also, Unlike JSP, FreeMarker templates are completely independent of the file format; they can just as easily be used to create an HTML file, XML file, CSS file, JavaScript file, even a plain text file. In fact, FreeMarker is independent of servlets altogether, making it just as useful on the client as on the server.

As an example of how Freemarker can cleanup your view pages, lets take one line of JSP and convert it to freemarker:

JSP	Freemarker
<% Action action = ActionUtils.getAction(); %> <input type="text" name="subject" value="<%= action.getSubject() != null ? StringUtils.escapeHTMLTags(action.getSubject()) : "" %> "/>	<input type="text" name="subject" value="${subject!?html}"/>

JSP

Freemarker

<% Action action = ActionUtils.getAction(); %>

<input type="text" name="subject"

value="<%= action.getSubject() != null ? StringUtils.escapeHTMLTags(action.getSubject()) : "" %> "/>

<input type="text" name="subject"

value="${subject!?html}"/>

Interesting Clearspace features relating to Freemarker

Themes: To help facilitate our customer's need to customize the look and feel of our products, we wrote a feature that provides our customer's the ability to customize most front end pages directly from the admin console without having to make a single change to the source code or even restart the application server. Simply select the page you want to customize and edit the template. Additionally, these custom pages can be grouped into different "Themes" and mapped to a commuity, a forum, even a URL pattern. This type of flexible UI would not be possible with JSP's. Freemarker provides us the ability to load the source of a template from a number of places, including a remote server, and without ever needing to be recompiled.
Community Everywhere: If you want to make some dynamic HTML content available on any remote site, such as displaying a Clearspace thread at the bottom of a remote article, all you have to do is process the freemarker template that contains the thread HTML, wrap it in document.write(result); and return contentType text/javascript.
Freemarker Email Templates: Allows for easily customizable dynamic emails with very detailed and useful information.

After using Freemarker for some time, we can definitely say that it is a template language we?re confident in. We found it to be the easiest to use, learn and the most powerful while still having a clean, simple syntax. For a comparision with velocity, check out Freemarker vs. Velocity. We?ve also found that any good JSP programmer finds Freemarker enjoyable to use and learn. The one downside is that we all use Intellij Idea for development and there is currently no Freemarker support.

For those who still are not convinced, rest assured that it is still possible to make customizations to the application using only JSP's.

To learn more, check out FreeMarker: An open alternative to JSP

Clearspace Themes Explained

communities@jivesoftware.com — Tue, 17 Jul 2007 18:15:00 GMT

In this video, Jive Software's Nick Hill talks about how to create themes for Clearspace.

Or click here to watch the video.