Skip navigation

Jive Release Blog

1 Post authored by: alok

An easy way to extend Clearspace is by writing a macro. Macros can be used to modify and/or decorate a piece of a document, blog post or comment. For example: Say you wanted to include a map of downtown Portland, OR. Assuming you had the yahoomaps plugin installed, you could do so using the ymaps macro included in the plugin.

In a document or a blog post, you could write the following :

Jive Software is located in Downtown Portland
Address:
{ymaps}304 SW Adler, Portland, OR{ymaps}

 

When the document or the blog post is rendered, the

{ymaps}304 SW Adler, Portland, OR{ymaps}

 

portion of the document would be replaced by a map from Yahoo.

 

Writing a macro is simple, all you have to do is implement that Macro interface

public interface Macro{
    String render(String body, Map<String, String> parameters, MacroContext macroContext);
}

The return value (String) contains the HTML and/or Javascript code that replaces the macro tag in the document. For example, in case of Yahoo maps, the macro returns the following.

<script type="text/javascript" src="http://maps.yahooapis.com/v3.5/fl/javascript/apiloader.js?apid=foo"></script>
<div id="mapContainer_1234">
</div>
<script type="text/javascript">
...
</script>

When the document is rendered in the browser, the Javascript block executes and adds the Yahoo maps widget to the &lt;div&gt; element.

 

The render method of the Macro interface is passed three arguments.

  • body: This argument contains the text between tags. So, 304 SW Adler, Portland, OR, would mean that the render method would be passed the string "304 SW Adler, Portland, OR" as the body argument.

  • parameters: This argument is a map of name value pairs that capture the attributes set on the macro. For example, it is possible to specify the type of the map and zoom level by using "type" and "zoom" attributes on the yahoo maps plugin. So, 304 SW Adler, Portland, OR, will create a hybrid map with the zoom level set to 4. These two attributes will be passed inside the parameter map argument. In the code, you would access them using the name of the attribute as the key.

     String render(String body, Map<String, String> parameters, MacroContext macroContext){
          ....
          String mapType = parameters.get("type");//will return the string "hybrid"
          String zoomLevel = parameters.get("zoom"); //will return the string "4"
          ....
     }
  • macroContext: macroContext argument allows you to get handle to objects and managers inside Clearspace. Most macros never use this argument, but sometimes it is neccesary call into Clearspace to lookup a value or peek at the document that the macro was included in. For example, the yahoo maps macro needs to ensure that yahoo apis javascript is included only once in a document, regardless of the number of times a macro was included in the document. So, in the render method, it queries the macroContext for the document body and checks to see how many times it has been included and appropriately includes the &lt;script&gt; tag when needed.

 

Testing

Unit testing macros is extremely easy, since all of the arguments of the render method are easily mock-able. Macros are ideal candidates for TDD, since you know exactly what the input arguments and the HTML/Javascript return value should look like.

 

Packaging and additional docs

Macros are packaged as part of a plugin. So, the process is the same as a plugin. See Plugin and Clearspace documentation for additional details.

Filter Blog

By date: By tag: