Jivespace Community Blog

Customization Part 7: Using the Clearspace API

dawn — Wed, 16 Jul 2008 21:46:18 GMT

This post is the seventh and final post in a series of blog posts about customizing for Clearspace 2.x. The previous posts covered:

Some of the most important changes in version 2 of Clearspace required that the underlying API be changed. To get things working on version 2, you'll need to change not only references to these in your Java classes, but also references to them in your FreeMarker templates.

The following describes the most significant changes.

Inject Dependencies with Spring
Work with Containers for Projects and Spaces/Communities
Use Transaction Support When Updating Multiple Tables
Use Manager Interfaces to Work with Managed Things
Handle Content As XML
Other API Changes

Inject Dependencies With Spring

For version 2, the Clearspace codebase was refactored to support Spring, a framework with modules for inversion of control, transaction management, authentication, and more. This has potentially the biggest impact on your code because components that extend Clearspace must use the same conventions in order to interact reliably with Clearspace. For example, as described below, dependency injection replaces version 1 conventions for using JiveContext and factory classes to get manager instances.

Dependency injection is a way to obtain a dependency, such as an object on which your code relies, by having the instance "injected" at run time -- that is, the instance is set with a JavaBeans-style accessor method. In Clearspace code, manager class instances are generally now injected rather than obtained via a context or factory class method.

A class that supports injection includes a class-level ++ variable for holding the instance it depends on and provides a set* accessor method through which Spring can inject the instance (in other words, your code provides a property of the interface's type). Your setter implementation assigns the injected instance to the variable, which your code can then use to access the instance. By specifying the interface on which your code depends -- rather than an implementation of the interface -- you have a loosely-coupled dependency. This lets you avoid breakage that might occur if the implementation changes.

Note: You can ensure that the setter you provide actually has a configured type associated with it by annotating the setter method with @org.springframework.beans.factory.annotation.Required. If the injected type is not known to Spring configuration, then the Spring container will throw an exception at run time.

The following example illustrates the basics of dependency injection with Spring: declare private class-level variables for manager instances and declare setter methods through which Spring will inject the instances. Code for version 1 techniques has been commented out in favor of the Spring conventions.

// Variables to hold the manager instances.
private DocumentManager documentManager;
private FreemarkerManager freemarkerManager;


// Setters for injecting manager instances.
public void setDocumentManager(DocumentManager documentManager) {
    this.documentManager = documentManager;
}
public void setFreemarkerManager(FreemarkerManager freemarkerManager) {
    this.freemarkerManager = freemarkerManager;
}

private String getDocContent(String documentID)
{
    // ... Declare variables ... 
    
        // Don't use JiveContext (from JiveApplication) to get a DocumentManager 
        // instance. The instance has been injected through the setter above.
        // DocumentManager documentManager = JiveApplication.getContext(AuthFactory
        //    .getSystemAuthToken()).getDocumentManager();
        
        // Use the manager to get a document by its ID.
        document = documentManager.getDocument(documentID);
        Map properties = new HashMap();
        
        // ... Set FreeMarker properties from the document, then apply 
        // a template with them ...
        result = applyFreemarkerTemplate(properties, FREEMARKER_HTML_FILE);
        
    // ... catch exceptions ...

    return result;
}

private String applyFreemarkerTemplate(Map properties,
        String templateName) {
        
    // ... Declare variables ... 
    
        // Don't use getInstance to get the FreemarkerManager instance. It has 
        // been injected.
        // FreemarkerManager freemarkerManager = FreemarkerManager.getInstance();
        
        // ... Use the manager to set up FreeMarker configuration ...
        config = freemarkerManager.getConfiguration(ServletActionContext.getServletContext());
        if (properties != null) {
            // Process the FreeMarker template and store the resulting HTML as a String
            result = applyFreemarkerTemplate(config, properties, templateName);
        }
        
    // ... catch exceptions ...

    return result;
}

While you can optionally name the specific interface implementation you want to have injected, Spring in Clearspace supports a feature known as autowiring. In autowiring, you merely include the setter method (using JavaBeans naming conventions) with a single parameter of the interface's type. To optionally specify the implementation you want injected, you include a spring.xml file that associates the implementation class with your setter.

Remove JiveContext uses that retrieve managers. In version 1 the JiveContext interface was a popular convention to get instances of the various manager interfaces -- CommunityManager, UserManager, DocumentManager, and so on. In version 2 this convention is, depending on the case, either unavailable or unreliable. For example, if you've written a plugin that has a static initializer that tries to bootstrap with call to JiveContext, Clearspace startup will likely fail.

Instead, use dependency injection as described above. In fact, to stay out of trouble, the general rule in version 2 is "Don't use JiveContext."

Remove getInstance calls that retrieve managers. This includes FreemarkerManager.getInstance, but also all of the *Factory.getInstance methods you might have used in version 1. In version 2 most of the factory classes have been removed. You should replace your calls to their getInstance methods with a property for setting the instance from Spring as described above. Here's a list of the removed classes:

GroupManagerFactory
UserManagerFactory
AvatarManagerFactory
BanManagerFactory
PollManagerFactory
SearchQueryLoggerFactory
StatusLevelManagerFactory
TagManagerFactory
WidgetDAOFactory

Work with Containers for Projects and Spaces/Communities

Version 2 introduces projects, which, like spaces (known as communities in Clearspace Community), collect content such as documents, discussions, and blogs. Projects also add tasks as a content type. To organize the conceptually similar projects and spaces, the API was changed to introduce the idea of a container. The interfaces that represent projects and spaces -- Project and Community -- now inherit from a common JiveContainer interface.

In practical terms, this means that some methods taking an instance of the Community interface now take a JiveContainer instance instead. The following code works to get the latest document in either a project or space, for example, because they inherit from JiveContainer and both can contain documents. To see how your code might be affected, search the Javadoc index for occurrences of JiveContainer in method signatures and return types.

public Document getLatestDocument(JiveContainer container) {
    if (getDocumentCount(container) == 0) {
        return null;
    }
    DocumentResultFilter filter = new DocumentResultFilter();
    filter.setSortOrder(DocumentResultFilter.DESCENDING);
    filter.setSortField(JiveConstants.MODIFICATION_DATE);

    // Round down the lower date boundary by 1 day.
    filter.setModificationDateRangeMin(ThreadResultFilter
        .roundDate(container.getModificationDate(), 24 * 60 * 60));
    filter.setNumResults(10);
    Iterable<Document> documents = documentManager.getDocuments(container, filter);
    if (documents.iterator().hasNext()) {
        return documents.iterator().next();
    }
    else {
        return null;
    }
}

By the way, this getLatestDocument method is now exposed by the DocumentManager interface; in version 1 this method was exposed by the Document interface. Methods such as this one were moved as part of a larger effort to migrate such functionality into managers.

Use Transaction Support When Updating Multiple Tables

Version 2 supports transaction management through Spring with the @Transactional annotation. When the work of your code results in updates (including deletes) to data in multiple database tables, supporting transactional behavior can help to ensure that the updates are made consistently (that is, all of the effected tables are updated or none are).

If you're explicitly supporting transactions with @Transactional, you'll need to add an AspectJ compilation step. The AspectJ compiler weaves into your code the support needed to include at load time your transactional method calls in a transaction context.

You'll want to add transaction support if your code updates multiple database tables as while executing a method. While the need to support transactions is fairly rare if you're doing all your work through the Clearspace API, keep in mind that your calls to API set* methods might result in database updates. If you're not sure whether your code's work results in database updates, it's not a bad idea probably to add the @Transactional annotation to the method.

Adding support for transactions is pretty easy. Here's what you do:

Add the @Transactional annotation to any methods whose execution might result in updates to multiple tables. The annotation is in the package org.springframework.transaction.annotation.
Compile your code with the AspectJ compiler. There are also Ant tasks.

Use Manager Interfaces to Work with Managed Things

Much of the Clearspace code was rewritten to clarify (or create) relationships between instances of manager interfaces and instances of what they manage. The result is an API that's more intuitive, but it also might mean changes to your code.

In general, methods designed to handle types of things -- documents, attachments, discussion messages, and so on -- were moved from a "containing" type to a manager type. For example, in version 1 the method getAttachmentCount was exposed by the interfaces BlogPost, Document, and ForumMessage ; each of these could have attachments, and getAttachmentCount was how you got the count of them. In version 2, you get the count of attachments with the AttachmentManager.getAttachmentCount(AttachmentContentResource) method. The AttachmentContentResource is a marker interface extended by BlogPost, Document, ForumMessage, and other things that can have attachments.

So in version 2 the rule of thumb, when looking for a way to manage types of things, is to look for a manager of those things.

Handle Content As XML

Version 2 includes significant changes in the way Clearspace handles content. Improving the rich text editor (which blogs, documents, and discussions threads all use) included completely reworking the way that content is handled in conversions between plain text (wiki markup), rich text, and HTML (for previewed and published content).

In particular, content is set and received as XML. In version 1, the content-related accessors that get and set content body, subject and so on received and returned String instances. In version 2, these methods handle content as instances of org.w3c.dom.Document. Version 2 interfaces that used content accessor methods -- including Document, PrivateMessage, ForumMessage, BlogPost, and others -- still include methods such as getPlainBody for retrieving content without markup.

For plugins that include actions, you can extend JiveActionSupport for several methods helpful in converting content from one format to another.

While version 2 features a model for setting and getting content as XML, there's also an exception: the Macro interface render method still returns content as a String. It has to parse as well-formed XML, but it's still a string.

Other API Changes

In some cases, methods that took a JiveObject instance now take an instance of an interface that extends JiveObject. The marker interfaces CommentContentResource and AttachmentContentResource were created to indicate an object's support for comments or attachments. Look for these types in the Javadoc index to find out whether you need to update your own code.

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

Customization Part 2: Upgrading Themes and FTL files

dawn — 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

dawn — 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.

Freemarker w/ WebWork Tutorial

nick — Thu, 31 Jan 2008 16:57:59 GMT

Configuring your action to use the freemarker result type

Freemarker views are rendered via the webwork result type freemarker, or by using the dispatcher result type in conjunction Webwork's FreemarkerServlet.
We use the freemarker result type which is defined in xwork-community.xml, so you can simply use it like so:


<action name="test" class="package.Test">
    <result name="success" type="freemarker">
        /templates/testView.ftl
    </result> 
</action>

Since freemarker is defined as the default result type, type="freemarker" is not necessary when declaring your action.

Property Resolution

Your action properties are automatically resolved. FOR EXAMPLE:


${name} will result in stack.findValue("name"), which generally results in action.getName() being executed.

A search process is used to resolve the variable, searching the following scopes in order, until a value is found:


1.) Freemarker Variables 
2.) Webwork Value Stack 
3.) Request Attributes 
4.) Session Attributes 
5.) Servlet Context Attributes

Objects in the Context

Webwork objects added to the context

request - the current HttpServletRequest
response - the current HttpServletResponse
stack - the current OgnlValueStack
ognl - the OgnlTool instance. This class contains useful methods to execute OGNL expressions against arbitary objects
webwork ? an instance of FreemarkerWebWorkUtil
action - the current WebWork action
exception - optional the Exception instance, if the view is a JSP exception or Servlet exception

Jive objects added to the context

JiveGlobals
JiveConstants
LocaleUtils
StringUtils
DateUtils
SkinUtils
Permissions
IMSettingsUtils
ActionUtils
RSSActionSupport
ViewCountManager
CommunityUtils
BlogUtils
FeedUtils
WikiUtils
LicenseManager
DocumentPermHelper
MessagePermHelper


${JiveGlobals.getJiveProperty(?skin.defaultHeader?)?default(?Community Home?)}

In addition, static models and enums can be referenced as so:


${statics('com.jivesoftware.community.action.CommunityAction').VIEW_OVERVIEW}
${enums('com.jivesoftware.community.SearchQueryCriteria$SortType').RELEVANCE.key?c}
where ) is replaced with ] and ( is replaced with [

The Switch to Freemarker

nick — 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