Contents README Changelog FTL Changelog Known Issues pdf

This tutorial gives you the basics on how to build macros. A user adds a macro to content in order to do specific kinds of formatting, include particular kinds of content, and so on.

With a macro, a user adds the macro tag to their document in plain text, then publishes the document to view the macro's result. An example is using the following to display text in red:

{color:red}This is red text.{color}

The result would be something like this:

This is red text.

A macro is one or two tags bracketed by curly braces. They look like this:

The macro at the end of this sentence could embed a {username}.
Or you could format text by {blinking_lights}surrounding it with blinking lights{blinking_lights}.

With just a bit of code, you can add macros to those that Clearspace includes by default. In this tutorial you'll build a simple "Author" macro that displays the name of the person who's logged in. Along the way you'll see the pieces that make up a basic macro – a plugin.xml file and the Java code behind the macro.

Macro Basics

For simple macros, you'll really need just two pieces of code:

You package your macro in a JAR file and deploy it by copying it to the <jiveHome>/plugins directory of your Clearspace instance. You can also install a macro using the admin console at System > Plugins > Add Plugin.

What You'll Need to Get Started

This tutorial is about the basics, so you'll want only a few things to build all the pieces it describes:

That's about it. Check out the next section for a few setup steps, then you can get started writing code.

Setting Up

These setup steps are likely pretty common to other extension work you'll do, whether with macros or plugins or themes.

Set Up Clearspace

If you haven't installed Clearspace and used its setup tool, use the following instructions. If you have, you can skip this part. Here are the steps:

  1. Install your Clearspace development instance using the installation instructions.
  2. Run Clearspace and use its setup tool to set basic configuration options, such as the location of the jiveHome directory. If you're unfamiliar with the setup tool, use the following setup tool settings:
    • For jiveHome, use <distribution_root>/jiveHome
    • For License, accept "Evaluation".
    • For Database Settings, choose "Evaluation Database".
    • Accept defaults for the rest.

Set Up Test Spaces

To test your macro you'll create a document and add your macro markup to it. This assumes you've set up spaces or communities in your Clearspace instance. You can test with any spaces or communities you like, but you might find it easier to follow the tutorial if you set up as described here:

  1. If you haven't started Clearspace, start it now. With the standalone distribution, open a command prompt and execute the following at the distribution's root:

    Linux/Unix 

    sh start-clearspace.sh

    Windows 

    start-clearspace.bat
  2. Navigate to the admin console of your running instance with your browser, then log in. The console is probably at a URL such as 
    http://<hostname>:<portnumber>/<context>/admin
    For example, by default you might use http://localhost:8080/clearspace/admin
  3. Create a space (in Clearspace) or community (in Clearspace Community) for testing.
    1. Click Spaces > Create New Sub-Space
    2. In Space Creation - Step 1, select a parent space and enter the following values:
      • Space Name: My Content
      • Description of Space: <whatever you like>
      • Space display name: mycontent
    3. In Step 2, accept Open and click Next.
    4. In Step 3, click Next.
  4. In the Review page, click Finish.

You don't need to add users if you don't have any. You'll log in as a system admin during the tutorial.

Note: At this point, if you don't know where your application log files are, you might want to find them. The logs can be very helpful for debugging. If you're using the standalone distribution, you'll find the log files at <dist_root>/server/logs.

Set Up Your Project

It's easiest to develop plugins such as macros if you have your source and compiled artifacts in certain places. In particular, Clearspace expects your compiled Java classes to live in a classes directory under your plugin's root, your plugin.xml file will need to be at the root, and so on.

If You're Using Another Distribution

This tutorial (and the Ant build file that does with it) assumes you're using the Clearspace standalone distribution. Of course, you can use this tutorial with another Clearspace distribution you've set up for development and testing (such as a Clearspace WAR file deployed to your application server). You can also set a jiveHome directory that's external to the distribution (this is the best practice for production). If you do either of these, you'll want to edit a couple of properties in the included Ant build file:

Create a Project Hierarchy

  1. Create an "example" directory for your plugin code. If you're using the standalone Clearspace distribution with the included application server, set up your project directory at the following path inside the exploded distribution: 
    <distribution_root>/plugins/plugins/SimpleExamples
  2. Grab the included Ant build file and copy it into the example directory you created.
  3. Open a command prompt and navigate to the example directory.
  4. Run the Ant target that creates the project directories:
    ant create.plugin.dirs
    Now that you've got a place for your code, you'll actually write some. In the next section you'll start out by adding a simple theme that customizes the Clearspace user interface.

Create a plugin.xml File

Every plugin has one. This file tells Clearspace what's in the plugin – in short, what Clearspace features you're extending – and where to find code and other supporting files your plugin needs (although not necessarily all of them, as you'll see in the next section).

  1. Create a text file called plugin.xml in the root directory of your project (where the Ant build file is).
  2. Paste the following into the new file: 

    <plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.jivesoftware.com/schemas/clearspace/2_0/plugin.xsd">
    <name>example</name>
    <description>A simple macro that displays the name of the enclosing content's author.</description>
    <author>Me</author>
    <version>1.0.0</version>
    <minServerVersion>2.0.0</minServerVersion>

    <!-- 
        A macro element indicates a macro included in this plugin. The class
        attribute points to the Java implementation included in the classes directory.
        The name attribute is the name that will be used in the macro tag in content.
        The hasBody attribute tells Clearspace whether to look for content (the "body") 
        between two macro tags rather than just a single tag. This macro has one tag.
    -->
    <name="author" hasBody="false"
        class="com.jivesoftware.clearspace.plugin.example.macro.AuthorsNameMacro" />
 
</plugin>
    The <plugin> element's children include information about where the plugin is coming from (you), its version (in case you revise it for upgrade), and so on. The minServerVersion indicates the earlier Clearspace version that the macro supports (it simply won't load on earlier versions). There's a corresponding maxServerVersion element, also. Note the <macro> element, which points to a Java class you'll make in the next step. The plugin.xml can contain information about multiple bits of plugin functionality.

Create a Plugin Class

Your plugin class will provide the logic to tell Clearspace what to do when rendering a page that has your macro in it.

  1. In the src directory created by the Ant build file, create a Java file called AuthorsNameMacro.java and put it in a package called com.jivesoftware.clearspace.plugin.example.macro.
  2. Add the following code to the new file. 
    package com.jivesoftware.clearspace.plugin.example.macro;

import java.util.Map;

import com.jivesoftware.base.plugin.Macro;
import com.jivesoftware.base.plugin.MacroContext;

/**
 * A simple macro that displays the name of the logged in user. This macro illustrates how to, well,
 * write a simple macro. Essentially, your Macro implementation -- and the render method in
 * particular -- provides your macro code with the context it needs to process what the user has
 * done with your macro and to return the HTML markup Clearspace needs to display the published
 * document containing your macro.
 */
public class AuthorsNameMacro implements Macro {

    /**
     * Called by Clearspace to get the HTML markup that should be displayed for the macro.
     *
     * @param body The content between the macro's tags, if any.
     * @param parameters Parameters set by the user and passed as part of the macro.
     * @param macroContext Information about the context in which the macro is executing.
     */
    public String render(String body, Map<String, String> parameters, MacroContext macroContext) {
        return encodeInHtmlTag("b", macroContext.getContentObject().getUser().getUsername());
    }

    /**
     * Wraps the content in the HTML tag.
     *
     * @param tag The HTML tag in which to wrap the content.
     * @param content The content to wrap in HTML tags.
     * @return The generated HTML.
     */
    private String encodeInHtmlTag(String tag, String content) {
        String result = String.format("<%1$s class='author-name'>%2$s</%1$s>", tag, content);
        return result;
    }
}

    That's all the source code you'll need for this macro. Now it's time to...

Build, Deploy and Test the Macro

Use Ant to compile and package the code into a JAR file, then copy your macro into the <jiveHome>/plugins directory.

  1. At your command prompt, run 
    ant build.plugins
    to build, then 
    ant deploy.plugins
    to deploy to your server.

    There's no need to restart your server, but you'll want to wait five or ten seconds for Clearspace to deploy the plugin for use.
  2. Open your browser to Clearspace and click the My Content space you created.
  3. In the My Content space, create a new document called "Just saying hello".
  4. Add whatever content you like, but be sure to add your macro's tag. So you might have something like the following: 

    Here's a test of a new macro.
{author} says hello, world!
  5. Publish the document.
    After you've published the document, you should see something like this (where "me" is the name you used when you created the document):
Here's a test of a new macro.
                Me says hello, world!

That's it for building a simple macro! Be sure to check out more content and samples on Jivespace.