Basic Examples

Including Verbatim Content or Snippets (parts) of it

Include Full Content

%{include|source=samples/sample-pom.xml}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  
    <modelVersion>4.0.0</modelVersion>
  
    <!-- START SNIPPET: Signature -->
    <groupId>org.tinyjee</groupId>
    <artifactId>doxia-include-macro</artifactId>
    <version>1.0-SNAPSHOT</version>
    <!-- END SNIPPET: Signature -->
  
    <name>Doxia :: Include - Macro</name>
    <url>http://doxia-include.sf.net/</url>
  
    <!-- START SNIPPET: Signature -->
    <licenses>
        <license>
            <name>The Apache Software License, Version 2.0</name>
            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
        </license>
    </licenses>
    <!-- END SNIPPET: Signature -->
  
    <!-- START SNIPPET: Remote Resources -->
    <issueManagement>
        <system>SourceForge BugTracker</system>
        <url>https://sourceforge.net/p/${application.id}/tickets/?aid=%ISSUE%</url>
    </issueManagement>
  
    <ciManagement>
        <system>hudson</system>
        <url>http://www.tinyjee.org/hudson/view/All/</url>
    </ciManagement>
    <!-- END SNIPPET: Remote Resources -->
</project>

When content is specified using the "source" parameter, it is by default resolved against the following paths:

<project-root>
  site
    resources
  src
    main
      java
      resources
    site
      resources
    test
      java
      resources
  target

The built-in search path is pre-configured using the system environment and can be adjusted using -Dorg.tinyjee.maven.dim.siteSourceSearchPath=... and -Dorg.tinyjee.maven.dim.sourceSearchPath=....
See ResourceResolver ( ApiDocs| Source ) for implementation details.

Include Snippets of the Content

Single Snippet

%{include|source=samples/sample-pom.xml|snippet=#Remote Resources}
25
26
27
28
29
30
31
32
33
<issueManagement>
    <system>SourceForge BugTracker</system>
    <url>https://sourceforge.net/p/${application.id}/tickets/?aid=%ISSUE%</url>
</issueManagement>
  
<ciManagement>
    <system>hudson</system>
    <url>http://www.tinyjee.org/hudson/view/All/</url>
</ciManagement>

Multiple Snippets in one Source

%{include|source=samples/sample-pom.xml|snippet=#Signature}
7
8
9
16
17
18
19
20
21
<groupId>org.tinyjee</groupId>
<artifactId>doxia-include-macro</artifactId>
<version>1.0-SNAPSHOT</version>
<licenses>
    <license>
        <name>The Apache Software License, Version 2.0</name>
        <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
    </license>
</licenses>

Note: Multiple matching sections append to each other. Check the line numbers in the gutter above.

Excluding Snippets

%{include|source=samples/sample-pom.xml|snippet=!#Signature, !snippet-ids}
1
2
3
4
5
11
12
13
14
23
25
26
27
28
29
30
31
32
33
35
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  
    <modelVersion>4.0.0</modelVersion>
  
  
    <name>Doxia :: Include - Macro</name>
    <url>http://doxia-include.sf.net/</url>
  
  
    <issueManagement>
        <system>SourceForge BugTracker</system>
        <url>https://sourceforge.net/p/${application.id}/tickets/?aid=%ISSUE%</url>
    </issueManagement>
  
    <ciManagement>
        <system>hudson</system>
        <url>http://www.tinyjee.org/hudson/view/All/</url>
    </ciManagement>
</project>

Note: snippet-ids matches any snippet id definition, using !snippet-ids removes them from the included content.

Deal with Code Highlighting

Code is automatically highlighted when verbatim content is included. The applied highlighting scheme and whether content is verbatim is auto detected based on file extension or the content itself (e.g. '<?xml', '#!/bin/sh').

In case of auto-detection isn't working correctly it can be bypassed using:

%{include|source=myJavaScriptContent|verbatim=true|highlight-type=js}
%{include|source=nonHighlightedContent|verbatim=true|highlight-type=none}
%{include|source=nonVerbatimContent|verbatim=false}

Behind the scenes, syntax highlighting is implemented using Alex Gorbatchev's excellent syntax highlighter (http://alexgorbatchev.com/SyntaxHighlighter/) running directly on Rhino. Choosing this wide-spread highlighter ensures excellent support for highlighting schemes and finally it produces professional results. Version 3.x has everything that is required for static processing: CommonJS support, In place code selection, no Flash or JS dependencies at runtime.

Bundled highlighting schemes (brushes) include support for: Java, JavaFX, JavaScript, JSP, Groovy, GSP, XML/XHTML, SQL, Bash, Batch, Flex/AS3 and much more. Custom schemes can be added via "META-INF/services" using org.tinyjee.maven.dim.sh.BrushResolver, (see documentation for more details).

Including Content

Include plain content

Plain (non-verbatim) content can be included using the Include Macro in a similar way as used in server side includes.

By default all content is considered verbatim except content of the types apt, xdoc or fml. In order to include plain HTML use the following call:

%{include|source=samples/red-box.html|verbatim=false}
This is plain included content.

Include plain content in APT, XDoc or FML format

When the file extension of the included content contains ".apt", ".xdoc" or ".fml" or when the parameter source-content-type is set, the included content is parsed and the result is added to the page. (see Templates section below for examples)

Note: The included content doesn't need to be of the same type as the page containing the include macro call. This is the case as the input is parsed independently from the target document type and directly rendered to the output.

Effectively this allows to get the best of the different formats, e.g. using APT for most of the page and create more complex content using XDoc includes. (See Real World Example for an example of a combination of multiple aspects, including this one.)

Important: With ".xdoc" includes it is advisable NOT to include a XML schema definition in order to disable content validation. As soon as XML validation is enabled, the validator expects that the document starts with a new section element which usually collides with the document hierarchy of the target document when a section is already opened (.. and in most cases this is true).

Including Templates

Including a plain template

Any included content is automatically considered a velocity template as soon as ".vm" is added to the file extension (just like with normal pages below the site tree).

For the cases where the addition of the extension is not possible (e.g. when including snippets of existing sources) it is also possible to enable template processing by adding the parameter "source-is-template=true".

Trivial example

hello-world.jsp.vm:

1
2
3
4
5
6
<%@ page contentType="text/html;charset=UTF-8"%>
<html>
    <body>
        <h1><% out.println("${title}"); %></h1>
    </body>
</html>

Macro call:

%{include|source=samples/hello-world.jsp.vm|title=Hello World!}

Result:

1
2
3
4
5
6
<%@ page contentType="text/html;charset=UTF-8"%>
<html>
    <body>
        <h1><% out.println("Hello World!"); %></h1>
    </body>
</html>

Force processing when using a snippet

IncludeMacroTest.java (snippet "version"):

44
45
46
public class Version {
    final String version = "${projectVersion}";
}

Macro call:

%{include|source=org.tinyjee.maven.dim.IncludeMacroTest|snippet=#version|source-is-template=true|projectVersion=1.0}

Result:

44
45
46
public class Version {
    final String version = "1.0";
}

Including a template that produces APT, XDoc or FML format

table-template.apt.vm:

1
2
3
4
5
6
7
8
*----------------*-----------------------------------*
||Parameter Name ||Description
#foreach($row in $rows.toString().split(";"))
*----------------*-----------------------------------*
#foreach($cell in $row.toString().split("[,:]", 2))|$cell#end
  
#end
*----------------*-----------------------------------*

Macro call:

%{include|source=samples/table-template.apt.vm|rows=a:Parameter A; b:Parameter B}

Result:

Parameter NameDescription
aParameter A
bParameter B

Using a "source-class"

org.tinyjee.maven.dim.IncludeMacroTest$ColorSource:

50
51
52
53
54
55
56
57
58
59
60
61
62
public static class ColorSource extends HashMap<String, Object> {
    public ColorSource(File basePath, Map requestParameters) throws Exception {
        final String[] colors = requestParameters.get("colors").toString().toUpperCase().split(",");
  
        final List<List<String>> rows = new ArrayList<List<String>>();
        put("colors", rows);
  
        for (String colorName : colors) {
            Color color = (Color) Color.class.getField(colorName.trim()).get(null);
            rows.add(Arrays.asList(colorName, '#' + Integer.toHexString(color.getRGB()).substring(2)));
        }
    }
}

color-table-template.xdoc.vm:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
<?xml version="1.0"?>
<document>
    <body>
        <table>
            <tr>
                <th>Name</th>
                <th>Color</th>
            </tr>
#foreach($row in $colors)
            <tr>
                <td>$row.get(0)</td>
                <td>
                    <div style="background-color:$row.get(1); color:$row.get(1);
                        margin:2px; border: 1px solid black;">-</div>
                </td>
            </tr>
#end
        </table>
    </body>
</document>

Macro call:

%{include|source=samples/color-table-template.xdoc.vm|source-class=org.tinyjee.maven.dim.IncludeMacroTest$ColorSource|colors=red,green,blue,yellow,gray}

Result:

Name Color
RED
-
GREEN
-
BLUE
-
YELLOW
-
GRAY
-

Note: It is required to run the compile, test or install goal before building the site when using source-class. (depending on the type of dependency that was used)

Executing:

mvn clean site

.. will break, whereas:

mvn clean install site

should work if the class is in the module's 'main' or 'test' path.

Appendix

Tipp: As long as source classes do not change, use 'mvn site:run' to open a dynamically rendered site that allows live editing of sources including templates and can dramatically speed up building sites (once running use "http://localhost:8080/" to see the site inside a browser).

Future version of include macro may also support 'source-class' reloading in this mode.