Latest TeamWall Brick API

Latest version of the TeamWall API is 1.0.

Bricks and Templates

If you want to program your own Brick you need to create at least two artefacts, a Brick and a BrickTemplate.

Setup

To get started you need to use the latest versions of our API. For maven style projects you can include the following dependency and repository. Make sure you check for the latest version.

If you are not using maven you can download the latest version from http://maven.40bits.com/releases/com/fourtybits/teamwall/api/teamwall-brick-api/ .

The API is still in beta. This means it still can change.

BrickTemplate

As mentioned above you need to create a BrickTemplate in order to use the Brick later on. Your class needs to implement the BrickTemplate interface.
Let's start with a simple Brick which will show a text the user has entered before.

Let's go through it step by step.

public Brick createNewBrickInstance()

This tells TeamWall on how to create a new Brick to show your information in our TeamWall.

public BrickCategory getBrickCategory()

Each BrickTemplate needs to be in on of the categories defined by TeamWall. This is used for organizing all available BrickTemplate in the TeamWall administration screen.

The available choices are:

• VERSION_CONTROL("VCS")
• ISSUE_TRACKER("Issue Tracker")
• CONTINUOUS_INTEGRATION("Continuous Integration")
• JMX("JMX")
• CODE_METRIC("Code Metrics")
• MONITORING("Monitoring")
• OTHER("Other")

public String getBrickKey()

Each BrickTemplate needs to define a unique key to identify itself. This should be stable as possible since it identifies the BrickTemplate and it's associated configuration data.

public String getBrickName()

Returns the name of the Brick/BrickTemplate which will be shown at configuration time.

public BrickTemplateConfiguration getBrickConfiguration()

A BrickTemplateConfiguration configures the parameters a user of the brick can use to tweak the output. In our case we use it to configure the text which should be displayed. The following types of BrickTemplateParameters are available:

• BrickTemplateParameterText - used for text input
• BrickTemplateParameterMultipleChoice - used for multiple choice input
• BrickTemplateParameterTextOutput - used for text output

The above code will produce the following configuration dialog.

Brick

A Brick needs to implement com.fourtybits.teamwall.api.brick.Brick.

This code does a little bit more than just implementing the interface. com.fourtybits.teamwall.api.Brick.AbstractBrick implements all but the render() method. If you would not extends this class you would need to also write methods for

void configure(String jsonData);

TeamWall stores the configuration of your Brick as JSON strings and TeamWall will set this configuration in your brick when it is needed. Your render method can use some of the convenience methods of AbstractBrick to get back values for the known input parameters. With com.fourtybits.teamwall.api.brick.ConfigurationParser you can parse the JSON String also by yourself.
In our case we need to get back the value of TextBrickTemplate.text as String since we want to show it.

String getConfiguredDescription();

This method is used to show a very brief text in the admin screen in how the brick is configured. By default in AbstractBrick it returns an empty String.

public String render();

The render method is the one where you create your fragment of Html code. The return value of it is the Brick output a user will see.

TeamWall supports Freemarker as templating engine. The render method of AbstractBrick takes a class and some data to render the content. By default it will try to load the Freemarker file from the classpath.
If you put TextBrick in a package com.mycompany.bricks your freemarker file needs to be in (and named) com.mycompany.bricks.TextBrick.ftl. You can put it either directly right next to your class and package it our use something like the Maven resource mechanism to have the source in different directories but together at packaging.

This will simply output the text as h1 headline.

Testing your Brick

Finally the TeamWall API supports you in previewing the result.

com.fourtybits.teamwall.api.brick.test.BrickPreview provides the possibility to render the output to a file which you then you view in your browser.

All you need to do is to define the same map as in your brick and feed the BrickPreview with it and the just written TextBrick.

Make it available

The final step to make it accessible from TeamWall is to create a configuration file.
You need to put create a file named 'bricks.json.txt' in the root of your classpath of the jar with the following content:

As with most of the configuration this is formatted as JSON text. If you have multiple Bricks in one jar, just add another template line after the comma.

Add your own CSS and Javascript

Now it is time to make the text a little more stylish.

TeamWall allows it to add your own CSS and Javascript to a Brick. Just annotate your class with the @BrickStyle Annotation.

Both style.css and fonts.js are now included in the generated html output. They need to be in the specified packages in the classpath.

Including files from within these defined files will not work. You can however define multiple files at the css and javascript attributes.

If we now change TextBrick.ftl to

And create the style.css file in the same package as TextBrick.

Including Javascript works the same, we just do not have an example here.

To test your Brick without a TeamWall server you can again use the BrickPreview. Your test would look like

Summary

Now you have the toolset to create your first Bricks. Have fun with it.

If you have questions please do not hesitate to contact our support.