Extensions API

The Extensions API allows you to add functionality to Concordion, for example implementing new commands, listening to events, or modifying the Concordion output.

For full details, see the Extension API specifications, the classes in org.concordion.api.extension and the fixtures that demonstrate it.

Adding extensions to Concordion

Extensions are added to Concordion by:

Annotating the fixture class with @org.concordion.api.extension.Extensions. This annotation is parameterised with a list of extension, and/or extension factory, classes to be installed. For example:
```
@RunWith(ConcordionRunner.class)
@Extensions({LoggingTooltipExtension.class, TimestampFormatterExtension.class})
public class MyTest {
...
```
Or annotating public fields in the fixture class with @org.concordion.api.extension.Extension. This allows the extensions to be configured per class instance. For example:
```
...
@Extension
public ConcordionExtension extension = new ScreenshotExtension().setScreenshotTaker(camera);
...
```
Or by setting the system property "concordion.extensions" to a comma separated list of extension, and/or extension factory, classes. For example:
```
java -Dconcordion.extensions="org.concordion.ext.LoggingTooltipExtension,com.acme.Extra"
```

For further details see the extension configuration specification.

Building your own extension

Extensions must implement the ConcordionExtension interface, which allows extensions to hook into the Concordion build phase through the ConcordionExtender interface.

Example: Adding custom CSS

Amongst other features, the ConcordionExtender interface provide a means for adding CSS, JavaScript or arbitrary resources to the Concordion output folder.

The following example extension copies /my_concordion.css from the classpath to the root folder of the Concordion output, and links to it from the Concordion output HTML.

package com.acme;

public class MyCssExtension implements ConcordionExtension {
    @Override
    public void addTo(ConcordionExtender concordionExtender) {
        concordionExtender.withLinkedCSS("/my_concordion.css",
            new Resource("/my_concordion.css"));
    }
}

Note: if you have already declared a link to the CSS file in your HTML, you should use concordionExtender.withResource() rather than concordionExtender.withLinkedCSS() to avoid a duplicate declaration.

If you'd prefer to embed the CSS in the HTML, use concordionExtender.withEmbeddedCSS(). Similar methods exist for including JavaScript in the output, or you can use withResource() to copy images or other resources to the output.

Other examples

For examples that listen to events and add new commands, see the concordion-extensions source code.