hr.ngs.templater

Interface Templater

public interface Templater

Provides access to low level API.

Templater low level API is generic abstraction over documents. Same abstraction is used for text, Word document, Excel workbook and PowerPoint presentation.

There are only several basic operations this API can do:

• inspect state via tags and user defined metadata and positioned metadata
• replace tags via simple replace and positioned replace
• duplicate (or remove) part of the region via smart resize
• duplicate (or remove) part of the region via explicit resize
• clone the entire document via cloning

Templater will recognize special data types sent to replace (jagged arrays, ResultSet, ImageInfo, XElement, ...) and handle it in a smart way - eg, ImageInfo will be replaced with a picture, ResultSet will be treated as a table, ...

When resize is performed, Templater will take special care of detecting best context and performing operation on it.

Most plugins are not invoked when Low-level API is used. Only low level replace plugin is invoked, while handlers, formatters, navigation and others are not.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Templater.TagPosition Exact tag position for the resize method.

Method Summary

Modifier and Type	Method and Description
Templater[]	clone(int count) Clones a document.
java.lang.String[]	getMetadata(java.lang.String tag, boolean all) User-defined metadata for tags.
java.lang.String[]	getMetadata(java.lang.String tag, int index) Since there can be multiple tags with same path, metadata for each specific tag in sequence can be obtained by passing in its index.
int	replace(java.lang.String tag, int index, java.lang.Object value) Replace tag at the position in the sequence of same tag paths with provided value.
boolean	replace(java.lang.String tag, java.lang.Object value) Replace first specified tag with provided value.
boolean	resize(java.lang.String[] tags, int count) Resize context which contains all specified tags.
boolean	resize(Templater.TagPosition[] tags, int count) Resize context which contains all specified tags.
java.lang.String[]	tags() Recognized tags in the document.

Method Detail

tags

java.lang.String[] tags()

Recognized tags in the document. Each tag is enumerated only once.

If there are tags in nested documents, they are also enumerated here.

Only the path of the tag is enumerated, so for [[my.tag]] only "my.tag" will be listed.

To gather more information about tags position metadata API should be used

Returns:

tags in the document

getMetadata

java.lang.String[] getMetadata(java.lang.String tag,
                               boolean all)

User-defined metadata for tags. For tag such as [[my.tag]:format:custom] only "format" and "custom" will be listed for the first tag. Metadata can be used for value conversions and formatting via built-in and user defined plugins. Plugins are registered during library initialization and should inspect the arguments to check if they are applicable.

When there are multiple tags with the same path and all argument is passed to enumerate all metadata for this tag, each metadata will be enumerated only once.

For more detailed control there is position based API

Parameters:

tag - tag for which metadata is required

all - true returns metadata for all matching tags, false returns metadata for just the first one

Returns:

String array of tag metadata. If the tag was not found an empty array will be returned

getMetadata

java.lang.String[] getMetadata(java.lang.String tag,
                               int index)

Since there can be multiple tags with same path, metadata for each specific tag in sequence can be obtained by passing in its index. If tags doesn't exists at that index null will be returned.

This metadata also includes internal values used to keep track of tag placement. Such metadata starts with _ci:

Parameters:

tag - tag for which metadata is required

index - tag index in sequence of same tag names

Returns:

Found metadata. null if tag/index does not exist

replace

boolean replace(java.lang.String tag,
                java.lang.Object value)

Replace first specified tag with provided value. Some document formats and value converters support complex values (Date, Image, ...)

For documents where Dynamic resize feature is supported, ResultSet or jagged arrays can be passed.

To access underlying XML in some formats, element can be used

Most other types will be converted to string via .toString() method

Low-level replace handlers will be invoked before final value is used in the document. When default formatting of some type needs to be defined, this can be implemented via Low-level replace handler.

Parameters:

tag - tag to be replaced

value - replacement value (which can be formatted)

Returns:

successful replacement

replace

int replace(java.lang.String tag,
            int index,
            java.lang.Object value)

Replace tag at the position in the sequence of same tag paths with provided value. Some document formats and value converters support complex values (Date, Image, ...)

For documents where Dynamic resize feature is supported, result set or jagged arrays can be passed.

To access underlying XML in some formats, element can be used

Most other types will be converted to string via .toString method

Index of the next tag with same path which is shared across context and should be replaced next will be returned. If none is found it will return -1

Low-level replace handlers will be invoked before final value is used in the document. When default formatting of some type needs to be defined, this can be implemented via Low-level replace handler.

Parameters:

tag - tag to be replaced

index - tag index in sequence of same tag paths

value - replacement value (which can be formatted)

Returns:

index of the next shared tag

resize

boolean resize(java.lang.String[] tags,
               int count)

Resize context which contains all specified tags. Context can be row in a table, paragraph in a document or named group in a spreadsheet. Templater will use various assumptions to pick the best region for the detected tags. Thus, document structure should closely match the tags usage, preferably through similar nesting structure.

If specified tags do not exist, they will be ignored.

When applicable this method will include additional tags with the same name which are part of the same context. Specifying tag multiple times results in same behavior as tag being specified only once.

When tags are shared, resize will affect multiple contexts at once (table, list, chart, etc...) When shared context is being processed, tag position info will be passed to handler plugin.

resize with count = 0 means removing the context/region and all tags within that region (even if they were not specified)

resize with count = 1 will bind the tags together which allows Templater to do smart replacement from high level API calls.

Parameters:

tags - tags which specify the context

count - number of contexts after the resize operation. If the count value is zero, the specified context will be removed.

Returns:

context found and resized

resize

boolean resize(Templater.TagPosition[] tags,
               int count)

Resize context which contains all specified tags. Context can be row in a table, paragraph in a document or named group in a spreadsheet.

This method does not include additional tags, only the specified ones. If multiple tags with the same name must be included, tags must be specified multiple times with the appropriate index.

Each element of the tags collection consist from the tag and its position in the document.

When tags are shared, resize will only affect specific context. Other shared contexts will be ignored.

If unknown tag is specified or index is outside of boundary, exception will be thrown.

resize with count = 0 means removing the context/region and all tags within that region (even if they were not specified)

resize with count = 1 will not bind the tags together like the similar resize API.

Parameters:

tags - exact tags which specify the context

count - number of contexts after the resize operation. If the count value is zero, the specified context will be removed.

Returns:

context found and resized

clone

Templater[] clone(int count)

Clones a document. New low level API can be operated independently from the current one.

Parameters:

count - number of clones to create

Returns:

an Templater array with cloned tags, text and other document properties