Extensions Reference:

Bundled Extensions:

Several extensions are bundled with the include macro that can be used to document interfaces, extract information from XML and properties or simply enrich content inside generated sites.

Most extensions are implemented as helper classes that are compatible with the "source-class" parameter. For simplified access, these helper classes define aliases that allow their invocation with a single Macro parameter using registered implementations of RequestParameterTransformer to implement aliasing.

A complete Usage & Parameter Reference of Bundled Extensions, can be found in the left hand navigation bar below the section Bundled Extensions.

Writing Your Own Extensions:

Preparation

  • Decide what you want to extend or adjust, choose from any combination of:
    • Shorten macro calls using aliases & request transformations.
    • Bundle own templates or source classes.
    • Adjust the configuration of the velocity template engine & execution context.
    • Add new highlighting schemes (sh brushes).
    • Add new snippet selectors.
  • Create a new maven module that is built before the relevant site goal runs.
  • Optional: Add a dependency to the artifact "org.tinyjee.dim:doxia-include-macro" of scope "provided", if you need to access any of the extension point interfaces.
  • Add a dependency of your maven module above the site building dependency definition of org.tinyjee.dim:doxia-include-macro.
  • Site building will now require that builds include the phases 'package' or 'install' to run correctly as long as the extension artifact is not copied to a shared repository.

Macro Execution Sequence - Reference:

Within the macro the following general operations happen after each other:

  • Macro call entered
  • Pre configure Globals with call parameters.
  • Call all implementations of RequestParameterTransformer that can be found in the site building classpath.
  • Reconfigure Globals with adjusted call parameters.
  • Attempt to resolve 'source' and 'source-class'.
  • If 'source-class' was specified:
    • Create an instance of the specified class.
    • Reconfigure Globals with adjusted call parameters.
  • If the source url ends with '.vm' or 'source-is-template' is set to 'true', compile a velocity template from the source content and replace the original source with the template.
  • Read the source content (if source is a template, the template will be interpreted now).
  • If 'snippet' or 'id' was specified:
    • Call all implementations of SnippetSelector.
    • Reduce the original source content to the lines that were selected.
  • If content is 'verbatim':
    • Attempt to detect content type by inspecting the content and looking at the file extension given with the 'source' parameter.
    • Process source content with the code highlighter and replace original content.
  • Send final content to the underlying sink (= document output).
  • Macro call exited.

Extension Interfaces

Request Parameter Transformation:

Transforming request parameters can be used to shorten macro calls by adding, removing or changing parameters of the macro call before any further processing is applied.

RequestParameterTransformer defines an interface that may be implemented and registered via service loading to plug parameter transformers that adjust macro parameters on the fly before any other operation is triggered.

Implementation:

1
2
3
4
5
6
7
8
9
10
11
package my.package;
public class MyRequestParameterTransformer implements RequestParameterTransformer {
     public void transformParameters(Map<String, Object> requestParams) {
         Object value = requestParams.get("my-input-param");
         if (value != null) {
             requestParams.put("myText", value);
             requestParams.put("source", "classpath:my-template.vm");
         }
     }
}

Register the implementation using service loading:

  • Create the following file:
    1
    2
    3
    META-INF/services/
       org.tinyjee.maven.dim.spi.RequestParameterTransformer
  • Add the fully qualified class name of your implementation to the file "org.tinyjee.maven.dim.spi.RequestParameterTransformer":
    1
    2
    my.package.MyRequestParameterTransformer
Adjusting the Velocity Engine & Context configuration:
VelocityConfigurator defines an interface that may be implemented and registered via service loading to customize the configuration of the velocity template engine and context before the templates are rendered.

Implementation:

1
2
3
4
5
6
7
8
9
package my.package;
public class MyVelocityConfigurator implements VelocityConfigurator {
     public void configureEngine(VelocityEngine engine) {
         engine.setProperty(VM_PERM_INLINE_LOCAL, true);
         ...
     }
     ...
}

Register the implementation using service loading:

  • Create the following file:
    1
    2
    3
    META-INF/services/
       org.tinyjee.maven.dim.spi.VelocityConfigurator
  • Add the fully qualified class name of your implementation to the file "org.tinyjee.maven.dim.spi.VelocityConfigurator":
    1
    2
    my.package.MyVelocityConfigurator
Adding brushes to the syntax highlighting library:
BrushResolver defines an interface that may be implemented and registered via service loading to register additional javascript brushes (= language support) for the syntax highlighting library.

Implementation:

1
2
3
4
5
6
7
8
9
10
package my.package;
public class MyBrushResolver implements BrushResolver {
     public Collection<URL> resolveBrushes() {
         return Collections.singleton(getClass().getResource("/my/package/my-brush.js"));
     }
     public String detectBrushAlias(URL source, Map<Integer, List<String>> sourceContent) {
         return source.getPath().toLowerCase().endsWith(".my-extension") ? "my-brush-alias" : null;
     }
}

Register the implementation using service loading:

  • Create the following file:
    1
    2
    3
    META-INF/services/
       org.tinyjee.maven.dim.sh.BrushResolver
  • Add the fully qualified class name of your implementation to the file "org.tinyjee.maven.dim.sh.BrushResolver":
    1
    2
    my.package.MyBrushResolver
Creating custom snippet selection logic:
SnippetSelector defines an interface that may be implemented and registered via service loading to add new snippet selection mechanisms.

Implementation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package my.package;
public class MySnippetSelector implements SnippetSelector {
     public String[] getExpressionPrefixes() {
         return new String[] {"my:"};
     }
     public boolean canSelectSnippetsWith(String expression, URL contentUrl, Map<String, Object> macroParameters) {
         return expression.toLowerCase().startsWith("my:");
     }
     public Iterator<Integer> selectSnippets(String expression, URL contentUrl, LineNumberReader content,
                                                   Map<String, Object> macroParameters) throws IOException {
         List<Integer> output = new LinkedList<Integer>();
         for (String line = content.readLine(); line != null; line = content.readLine()) {
             if (... EXPRESSION MATCHES LINE ...) output.add(content.getLineNumber());
         }
         return output.iterator();
     }
}

Register the implementation using service loading:

  • Create the following file:
    1
    2
    3
    META-INF/services/
       org.tinyjee.maven.dim.spi.SnippetSelector
  • Add the fully qualified class name of your implementation to the file "org.tinyjee.maven.dim.spi.SnippetSelector":
    1
    2
    my.package.MySnippetSelector

Migration Information

API changes from 1.0.x to 1.1
  • Changed name 'org.tinyjee.maven.dim.RequestParameterTransformer' to 'org.tinyjee.maven.dim.spi.RequestParameterTransformer'.
  • Changed name 'org.tinyjee.maven.dim.utils.ResolveUtils' to 'org.tinyjee.maven.dim.spi.ResourceResolver'.
  • Replaced 'org.tinyjee.maven.dim.utils.MacroLoggers.getLogger()' with 'org.tinyjee.maven.dim.spi.Globals.getLog()'.
  • Deprecated 'org.tinyjee.maven.dim.utils.InterfaceScanner' is now 'org.tinyjee.maven.dim.extensions.JavaSourceLoader'.
  • Deprecated 'org.tinyjee.maven.dim.utils.PropertiesLoader' is now 'org.tinyjee.maven.dim.extensions.PropertiesLoader'.