IncludeMacroSignature (Doxia :: Include Macro 1.1 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.tinyjee.maven.dim
Interface IncludeMacroSignature

public interface IncludeMacroSignature

Defines the signature of the include macro.

Version:: 1.1
Author:: Juergen_Kellerer, 2010-09-06

Field Summary
`static String`	`PARAM_CHARSET` Defines the charset to use when loading the source content.
`static String`	`PARAM_CHARSET_AUTODETECT` Toggles whether charset detection is used when loading source content.
`static String`	`PARAM_FILE` Sets the source path using `java.io.File` instead of evaluating it against URL or File paths.
`static String`	`PARAM_HIGHLIGHT` Deprecated.
`static String`	`PARAM_HIGHLIGHT_LINES` Defines lines to highlight inside verbatim content using the same selection logic as used within the "`snippet`" parameter.
`static String`	`PARAM_HIGHLIGHT_THEME` Sets the highlighting color theme to use.
`static String`	`PARAM_HIGHLIGHT_TYPE` Sets the highlighter (brush) to use when highlighting verbatim content.
`static String`	`PARAM_NO_CACHE` Forces the re-loading of source content when set to `true`.
`static String`	`PARAM_PAD_LINE_NUMBERS` Pads all line numbers by the specified amount of zeros (if gutter is shown).
`static String`	`PARAM_SET_FIRST_LINE` Sets the line number to use for the first line (if gutter is shown).
`static String`	`PARAM_SHOW_GUTTER` Toggles whether the gutter including line numbers is shown for verbatim content.
`static String`	`PARAM_SITE_DIRECTORY` Deprecated.
`static String`	`PARAM_SNIPPET` Sets one or more comma separated expression to select the content snippets to include.
`static String`	`PARAM_SNIPPET_END_OFFSET` Optional parameter that can be used to grow the end of snippet selections by the given amount of lines.
`static String`	`PARAM_SNIPPET_GROW_EXCLUDES` Optional boolean parameter that toggles whether growing is applied to exclusions as well.
`static String`	`PARAM_SNIPPET_GROW_OFFSET` Optional parameter that can be used to grow snippet selections by the given amount of lines.
`static String`	`PARAM_SNIPPET_ID` Deprecated.
`static String`	`PARAM_SNIPPET_START_OFFSET` Optional parameter that can be used to grow the start of snippet selections by the given amount of lines.
`static String`	`PARAM_SOURCE` Sets the content to include using a source path, source URL or the fully qualified java class name.
`static String`	`PARAM_SOURCE_CLASS` Sets a class to use as dynamic source for content, request parameters or both.
`static String`	`PARAM_SOURCE_CONTENT` Sets the source content inline with the macro call.
`static String`	`PARAM_SOURCE_CONTENT_TYPE` Sets the content type of the source.
`static String`	`PARAM_SOURCE_IS_TEMPLATE` Toggles whether the source content is treated as a Velocity template.
`static String`	`PARAM_VERBATIM` Toggles whether the content is verbatim (included as source) or non-verbatim (included as markup and interpreted).

Field Detail

PARAM_SOURCE

static final String PARAM_SOURCE

Sets the content to include using a source path, source URL or the fully qualified java class name.

Examples:

 source=path/to/file
 source=my.package.MyClass
 source=/absolute/path/to/file
 source=http://somehost/someservice#.xml
 source=classpath:/bundled/template.vm

Relative source paths are resolved against multiple base locations including site, java (test)source and resource directories. Non existing absolute paths starting with the project's base directory are stripped and retried using the relative paths resolver.
When remote content is specified using URLs with schemes like http or ftp, the content is downloaded using a network connection and cached locally for the time of a single build (= subsequent requests to the same remote source will not download the source again).

Executing the goal "initialize" within the maven build enables the following additional syntax for referencing a module file location:

 [artifactId]:path/to/file
 [groupId:artifactId]:path/to/file
 [top]:path/to/file/in/project/root

Finally sources can also be loaded from the module's or the site building classpath using "classpath:/path/to/file".
The classpath is constructed out of the module sources and test-sources folder with the parent classloader being defined by the dependency list of the maven-site-plugin. When the goal "initialize" is executed the classpath includes all dependencies that are defined inside the pom.xml.

See Also:: Constant Field Values

PARAM_SOURCE_CLASS

static final String PARAM_SOURCE_CLASS

Sets a class to use as dynamic source for content, request parameters or both.

A class that is set using this parameter must implement the interface java.util.Map (or derive from a Map implementation like java.util.HashMap). All entries of this map are treated as if they had been specified as request parameters, on the macro call (therefore all parameters except 'source-class' can be set dynamically).

The source class may choose to use one of the 4 constructor signatures: Default, Constructor(java.io.File basePath), Constructor(java.util.Map requestProperties) or Constructor(java.io.File basePath, java.util.Map requestProperties).

The default behaviour of a source class should be to provide properties for a velocity template that is specified by either setting the "source" key to a bundled template or require the user to set the parameter when using the macro with this class.
Alternatively it can also directly provide the content to include (instead of loading the template specified with "source"). To do so the map key "source-content" must either return a String or Map<Integer, List<String>> (firstLine=>lines) containing the content to include.

The classpath that is used to load the class is similar to the classpath used when loading sources. (see "source" parameter for more information)

Simple Example:

 package my.package;
 public class MySource extends HashMap<String, Object> {
     public MySource(java.io.File basePath, java.util.Map requestProperties) {
         putAll(requestProperties);
         put("verbatim", false);
         put("source-content", "<b>Hello World!</b>");
     }
 }

Macro Call:

 %{include|source-class=my.package.MySource}

See Also:: Constant Field Values

PARAM_SOURCE_CONTENT

static final String PARAM_SOURCE_CONTENT

Sets the source content inline with the macro call. (This feature may become more useful when DOXIA-445 gets implemented. Voting for it may help.)

The purpose of this parameter is to allow the inline definition of templates used to render output of source classes. Unless specified, "source-is-template" is set to "true" when this parameter is set with the macro call (it is not implicitly set when the parameter was set by a source class).

Example: Including the main java doc comment of a class (using the JavaSourceLoader extension)

 %{include|source-content=$comment|source-java=my.package.MyClass}

See Also:: Constant Field Values

PARAM_FILE

static final String PARAM_FILE

Sets the source path using java.io.File instead of evaluating it against URL or File paths.

Under normal conditions it's easier to set the "source" parameter instead. However there may be occasions where it's necessary to force that the path is treated as a file path.

See Also:: Constant Field Values

PARAM_SOURCE_IS_TEMPLATE

static final String PARAM_SOURCE_IS_TEMPLATE

Toggles whether the source content is treated as a Velocity template. (Default: auto (= true if file extension ends with ".vm"))

See Also:: Constant Field Values

PARAM_SOURCE_CONTENT_TYPE

static final String PARAM_SOURCE_CONTENT_TYPE

Sets the content type of the source. (Default: auto (= detected by file extensions ".apt", ".fml", ".xdoc"))

Setting this property has no effect for verbatim content. With non-verbatim content this information is used to select a doxia parser that transcodes the the content when including it into the site. Using a parser allows to use xdoc templates inside apt documents and vice versa.

Values that will select a parser are "apt", "fml", "xdoc", any other values will have no effect.

See Also:: Constant Field Values

PARAM_CHARSET

static final String PARAM_CHARSET

Defines the charset to use when loading the source content. (Default: context specific, used to be "UTF-8" in pre 1-1-alpha)

When no charset is specified the following actions apply:

If auto detection is enabled, the detected charset is used.
If source is using the HTTP protocol, any given charset is used.
The build charset is used when the goal initialize was executed.
The systems default charset is used if nothing else is defined.

See Also:: Constant Field Values

PARAM_CHARSET_AUTODETECT

static final String PARAM_CHARSET_AUTODETECT

Toggles whether charset detection is used when loading source content. (Default: true)

This value can have multiple values:

false: Disable any auto detection.
true: Enable auto detection, externally specified charsets override detected values.
force: Use auto detection result even if confidence is low.

See Also:: Constant Field Values

PARAM_VERBATIM

static final String PARAM_VERBATIM

Toggles whether the content is verbatim (included as source) or non-verbatim (included as markup and interpreted). (Default: auto)

See Also:: Constant Field Values

PARAM_SNIPPET_ID

@Deprecated
static final String PARAM_SNIPPET_ID

Deprecated.

Sets the snippet-id to use for extracting snippets out of the specified source.

Snippets are processed on a line by line basis and multiple snippets with the same name may appear in one file. In order to define a section using a snippet id, surround a block with:
// START SNIPPET: snippet-id ... code to include ... // END SNIPPET: snippet-id

Note: From version 1.1 this parameter is deprecated, use snippet instead. Calls like "%{include|id=SnippetId|..}" translate to %{include|snippet=#SnippetId|..}

See Also:: Constant Field Values

PARAM_SNIPPET

static final String PARAM_SNIPPET

Sets one or more comma separated expression to select the content snippets to include.

Snippet selection allows to define what content is included or excluded from the loaded or generated source. This operation is always the last thing to happen before including and highlighting content and can therefore be combined with any other options that the macro offers.

The general format of this parameter is "prefix:expression1, prefix:expression2, .." to include matching content and "!prefix:expression1, !prefix:expression2, .." to exclude matching content.

Examples:

Include snippet by ID: 'snippet=#SnippetId'
Exclude all snippet id definitions: 'snippet=!snippet-ids'
Include by ID, exclude any definitions: 'snippet=#SnippetId, !snippet-ids'
'grep' like syntax: 'snippet=grep:Token,!grep:NotToken'
'Regular Expression' syntax: 'snippet=re:([0-9,.;\s]+)$' (all lines ending with numeric expressions)
'XPath' syntax: 'snippet=xp:/html/head/title'
'AOP'-like syntax: 'snippet=aj:..InnerClass, !aj:..toString()'
'Token & Brace' syntax: 'snippet=tb:"json-key"{, !tb:"inner-array"['
Line range: 'snippet=lines:50-100'

Some snippet selectors (e.g. XPath or AOP) require that the source content is well formed (XML/JSON or Java in this example) and may fail if applied to other content.
A complete overview on available expressions can be seen by looking after implementations of SnippetSelector.

Since:: 1.1-alpha
See Also:: Constant Field Values

PARAM_SNIPPET_GROW_OFFSET

static final String PARAM_SNIPPET_GROW_OFFSET

Optional parameter that can be used to grow snippet selections by the given amount of lines.

Since:: 1.1-alpha
See Also:: Constant Field Values

PARAM_SNIPPET_START_OFFSET

static final String PARAM_SNIPPET_START_OFFSET

Optional parameter that can be used to grow the start of snippet selections by the given amount of lines.

Since:: 1.1-alpha
See Also:: Constant Field Values

PARAM_SNIPPET_END_OFFSET

static final String PARAM_SNIPPET_END_OFFSET

Optional parameter that can be used to grow the end of snippet selections by the given amount of lines.

Since:: 1.1-alpha
See Also:: Constant Field Values

PARAM_SNIPPET_GROW_EXCLUDES

static final String PARAM_SNIPPET_GROW_EXCLUDES

Optional boolean parameter that toggles whether growing is applied to exclusions as well. (Default: false)

Since:: 1.1-alpha
See Also:: Constant Field Values

PARAM_SHOW_GUTTER

static final String PARAM_SHOW_GUTTER

Toggles whether the gutter including line numbers is shown for verbatim content. (Default: true)

See Also:: Constant Field Values

PARAM_SET_FIRST_LINE

static final String PARAM_SET_FIRST_LINE

Sets the line number to use for the first line (if gutter is shown). (Default: auto)

See Also:: Constant Field Values

PARAM_PAD_LINE_NUMBERS

static final String PARAM_PAD_LINE_NUMBERS

Pads all line numbers by the specified amount of zeros (if gutter is shown).

See Also:: Constant Field Values

PARAM_HIGHLIGHT

@Deprecated
static final String PARAM_HIGHLIGHT

Deprecated.

Sets a list of lines to highlight inside verbatim content.

Lines can be specified as a comma separated list of line numbers, as a range using x-y or as a mixture of the 2.
Example usage: highlight=1,5,10,20-25

As of version 1.1-beta this option is deprecated and was replaced by "highlight-lines". The example usage from above translates to "highlight-lines=lines:1,5,10,20-25"

See Also:: Constant Field Values

PARAM_HIGHLIGHT_LINES

static final String PARAM_HIGHLIGHT_LINES

Defines lines to highlight inside verbatim content using the same selection logic as used within the "snippet" parameter. Selected lines are highlighted by the use of a background color.

Examples:

"highlight-lines=grep:org.tinyjee.dim+3"
"highlight-lines=xp://license"
"highlight-lines=lines:1,5,10,20-25"

Since:: 1.1-beta
See Also:: Constant Field Values

PARAM_HIGHLIGHT_TYPE

static final String PARAM_HIGHLIGHT_TYPE

Sets the highlighter (brush) to use when highlighting verbatim content. (Default: auto ; uses source content or extension to detect)

DIM bundles the brushes bat, properties, clojure and velocity in addition to what is available by default inside the syntax highlighting library. A set of known brushes includes: java, js, jsp, cpp, csharp, sql, xml, html, etc. Check the documentation of SyntaxHighlighter to get a complete list.

Highlighting of verbatim content can be disabled by setting this property to none.

Specifying the highlight type as "html/[brushname]" allows to highlight HTML with embedded scripts. A common use case is "html/js" which highlights any HTML-like code with embedded javascript (Note: files with an extension of ".xhtml" or ".html" default to this highlighting type).

See Also:: Constant Field Values

PARAM_HIGHLIGHT_THEME

static final String PARAM_HIGHLIGHT_THEME

Sets the highlighting color theme to use. (Default: default)

Possible values: "default", "django", "eclipse", "emacs", "fadeToGrey", "MDUltra", "midnight", "RDark". (See: http://alexgorbatchev.com/SyntaxHighlighter/manual/themes/)
The theme can be set only once per page. The first highlighted inclusion will set the theme for all others.

See Also:: Constant Field Values

PARAM_NO_CACHE

static final String PARAM_NO_CACHE

Forces the re-loading of source content when set to true.

Content is cached for the lifetime of the build to avoid double downloads of remote resources.

See Also:: Constant Field Values

PARAM_SITE_DIRECTORY

@Deprecated
static final String PARAM_SITE_DIRECTORY

Deprecated.

Sets the path of the site source directory.

Setting this property is not required if the site directory uses standard paths or is located directly below the module's base directory.

As of version 1.1-beta this option is deprecated and was replaced by running the "initialize" goal using the macro as build plugin.

See Also:: Constant Field Values

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.tinyjee.maven.dim Interface IncludeMacroSignature

PARAM_SOURCE

PARAM_SOURCE_CLASS

PARAM_SOURCE_CONTENT

PARAM_FILE

PARAM_SOURCE_IS_TEMPLATE

PARAM_SOURCE_CONTENT_TYPE

PARAM_CHARSET

PARAM_CHARSET_AUTODETECT

PARAM_VERBATIM

PARAM_SNIPPET_ID

PARAM_SNIPPET

PARAM_SNIPPET_GROW_OFFSET

PARAM_SNIPPET_START_OFFSET

PARAM_SNIPPET_END_OFFSET

PARAM_SNIPPET_GROW_EXCLUDES

PARAM_SHOW_GUTTER

PARAM_SET_FIRST_LINE

PARAM_PAD_LINE_NUMBERS

PARAM_HIGHLIGHT

PARAM_HIGHLIGHT_LINES

PARAM_HIGHLIGHT_TYPE

PARAM_HIGHLIGHT_THEME

PARAM_NO_CACHE

PARAM_SITE_DIRECTORY

org.tinyjee.maven.dim
Interface IncludeMacroSignature