com.x5.template
Class TemplateSet

java.lang.Object
  com.x5.template.TemplateSet

All Implemented Interfaces:

ChunkFactory, ContentSource

Direct Known Subclasses:

TemplateSetSlice

public class TemplateSet
extends java.lang.Object
implements ContentSource, ChunkFactory

TemplateSet is a Chunk "factory" and an easy way to parse template files into Strings. The default caching behavior is great for high traffic applications.

 // Dynamic content in templates is marked with {~...}
 //
 // Previously the syntax was {$...} but then I had a project where
 // some of the templates were shared by a perl script and I got
 // tired of escaping the $ signs in inline templates in my perl code.
 //
 // Before that there was an escaped-HTML-inspired syntax which
 // looked like &tag_...; since this was thought to be most
 // compatible with HTML editors like DreamWeaver but it was hard
 // to read and as it turned out DreamWeaver choked on it.
 //
 // See TemplateSet.convertTags(...) and .convertToMyTags(...) for
 // quick search-and-replace routines for updating tag syntax on
 // old templates...
 //
 // ...Or, if an entire template set uses another syntax just call
 // .setTagBoundaries("{$", "}") on the TemplateSet object before
 // you use it to make any chunks.  All subsequent chunks made from
 // that TemplateSet will find and replace the {$...} style tags.
 //
 // Be careful: for interoperability you will need to call
 // .setTagBoundaries() individually on any blank chunks you make
 // without the aid of the TemplateSet object, ie with the Chunk
 // constructor -- better to use the no-arg .makeChunk() method of
 // the TemplateSet instead, since that automatically coerces the
 // blank Chunk's tag boundaries correctly.
 //
 ///// In summary, for back-compatibility:
 //
 // TemplateSet templates = new TemplateSet(...);
 // templates.setTagBoundaries("{$", "}");
 // ...
 //
 // *** (A) BAD ***
 // ...
 // Chunk c = new Chunk(); // will only explode tags like default {~...}
 //
 // *** (B) NOT AS BAD ***
 // ...
 // Chunk c = new Chunk();
 // c.setTagBoundaries("{$", "}"); // manually match tag format :(
 //
 // *** (C) BEST ***
 // ...
 // Chunk c = templates.makeChunk(); // inherits TemplateSet's tag format :)
 //
 

Copyright: waived, free to use
Company: X5 Software
Updates: Chunk Documentation

Author:

Tom McClure

Field Summary

static java.lang.String	BLOCKEND_LONGHAND
static java.lang.String	BLOCKEND_SHORTHAND
static java.lang.String	DEFAULT_TAG_END
static java.lang.String	DEFAULT_TAG_START
static java.lang.String	INCLUDE_SHORTHAND
static java.lang.String	PROTOCOL_SHORTHAND

Constructor Summary

TemplateSet()

TemplateSet(java.lang.String templatePath)
Makes a template "factory" which reads in template files from the file system in the templatePath folder.

TemplateSet(java.lang.String templatePath, java.lang.String extension, int refreshMins)
Makes a template "factory" which reads in template files from the file system in the templatePath folder.

Method Summary

void	addProtocol(ContentSource src)
void	clearCache() Forces subsequent template fetching to re-read the template contents from the filesystem instead of the cache.
static java.lang.String	convertTags(java.lang.String withOldTags, java.lang.String oldTagStart, java.lang.String oldTagEnd) Converts a template with an alternate tag syntax to one that matches the default tag syntax {~myTag}.
static java.lang.String	convertTags(java.lang.String withOldTags, java.lang.String oldTagStart, java.lang.String oldTagEnd, java.lang.String newTagStart, java.lang.String newTagEnd) Converts a template from one tag syntax to another.
java.lang.String	convertToMyTags(java.lang.String withOldTags, java.lang.String oldTagStart, java.lang.String oldTagEnd) Converts a template with an alternate tag syntax to one that matches this TemplateSet's tags.
java.lang.String	fetch(java.lang.String name)
java.lang.String	getDefaultExtension()
java.util.Map<java.lang.String,ChunkFilter>	getFilters()
protected Snippet	getFromCache(java.lang.String name, java.lang.String extension)
java.lang.String	getProtocol()
java.lang.String	getResourcePath(java.lang.String templateName, java.lang.String ext)
Snippet	getSnippet(java.lang.String name) Retrieve as String the template specified by name.
Snippet	getSnippet(java.lang.String name, java.lang.String extension) Retrieve as String the template specified by name and extension.
TemplateSet	getSubset(java.lang.String context)
java.lang.String	getTemplatePath(java.lang.String templateName, java.lang.String ext)
Chunk	makeChunk() Creates a Chunk with no starter template and sets its tag boundary markers to match the other templates in this set.
Chunk	makeChunk(java.lang.String templateName) Creates a Chunk with a starting template.
Chunk	makeChunk(java.lang.String templateName, java.lang.String extension) Creates a Chunk with a starting template.
boolean	provides(java.lang.String itemName)
static java.lang.String	removeBlockTagIndents(java.lang.String template)
void	setDirtyInterval(int minutes) Controls caching behavior.
void	setEncoding(java.lang.String encoding)
void	setJarContext(java.lang.Class<?> classInSameJar)
void	setJarContext(java.lang.Object ctx)
void	setLayerName(java.lang.String layerName)
void	signalFailureWithNull()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_TAG_START

public static java.lang.String DEFAULT_TAG_START

DEFAULT_TAG_END

public static java.lang.String DEFAULT_TAG_END

INCLUDE_SHORTHAND

public static final java.lang.String INCLUDE_SHORTHAND

See Also:

Constant Field Values

PROTOCOL_SHORTHAND

public static final java.lang.String PROTOCOL_SHORTHAND

See Also:

Constant Field Values

BLOCKEND_SHORTHAND

public static final java.lang.String BLOCKEND_SHORTHAND

See Also:

Constant Field Values

BLOCKEND_LONGHAND

public static final java.lang.String BLOCKEND_LONGHAND

See Also:

Constant Field Values

Constructor Detail

TemplateSet

public TemplateSet()

TemplateSet

public TemplateSet(java.lang.String templatePath)

Makes a template "factory" which reads in template files from the file system in the templatePath folder. Caches for 15 minutes. Assumes .html is default file extension.

Parameters:

templatePath - folder where template files are located.

TemplateSet

public TemplateSet(java.lang.String templatePath,
                   java.lang.String extension,
                   int refreshMins)

Makes a template "factory" which reads in template files from the file system in the templatePath folder. Caches for refreshMins. Uses "extensions" for the default file extension (do not include dot).

Parameters:

templatePath - folder where template files are located.

extension - appends dot plus this String to a template name stub to find template files.

refreshMins - returns template from cache unless this many minutes have passed.

Method Detail

getSnippet

public Snippet getSnippet(java.lang.String name)

Retrieve as String the template specified by name. If name contains one or more dots it is assumed that the template definition is nested inside another template. Everything up to the first dot is part of the filename (appends the DEFAULT extension to find the file) and everything after refers to a location within the file where the template contents are defined.

For example: String myTemplate = templateSet.get("outer_file.inner_template");

will look for {#inner_template}bla bla bla{#} inside the file "outer_file.html" or "outer_file.xml" ie whatever your TemplateSet extension is.

Specified by:

getSnippet in interface ContentSource

Parameters:

name - the location of the template definition.

Returns:

the template definition from the file as a String

fetch

public java.lang.String fetch(java.lang.String name)

Specified by:

fetch in interface ContentSource

getProtocol

public java.lang.String getProtocol()

Specified by:

getProtocol in interface ContentSource

getSnippet

public Snippet getSnippet(java.lang.String name,
                          java.lang.String extension)

Retrieve as String the template specified by name and extension. If name contains one or more dots it is assumed that the template definition is nested inside another template. Everything up to the first dot is part of the filename (appends the PASSED extension to find the file) and everything after refers to a location within the file where the template contents are defined.

Parameters:

name - the location of the template definition.

extension - the nonstandard extension which forms the template filename.

Returns:

the template definition from the file as a String

makeChunk

public Chunk makeChunk()

Creates a Chunk with no starter template and sets its tag boundary markers to match the other templates in this set. The Chunk will need to obtain template pieces via its .append() method.

Specified by:

makeChunk in interface ChunkFactory

Returns:

blank Chunk.

makeChunk

public Chunk makeChunk(java.lang.String templateName)

Creates a Chunk with a starting template. If templateName contains one or more dots it is assumed that the template definition is nested inside another template. Everything up to the first dot is part of the filename (appends the DEFAULT extension to find the file) and everything after refers to a location within the file where the template contents are defined.

Specified by:

makeChunk in interface ChunkFactory

Parameters:

templateName - the location of the template definition.

Returns:

a Chunk pre-initialized with a snippet of template.

makeChunk

public Chunk makeChunk(java.lang.String templateName,
                       java.lang.String extension)

Creates a Chunk with a starting template. If templateName contains one or more dots it is assumed that the template definition is nested inside another template. Everything up to the first dot is part of the filename (appends the PASSED extension to find the file) and everything after refers to a location within the file where the template contents are defined.

Specified by:

makeChunk in interface ChunkFactory

Parameters:

templateName - the location of the template definition.

extension - the nonstandard extension which forms the template filename.

Returns:

a Chunk pre-initialized with a snippet of template.

removeBlockTagIndents

public static java.lang.String removeBlockTagIndents(java.lang.String template)

getFromCache

protected Snippet getFromCache(java.lang.String name,
                               java.lang.String extension)

clearCache

public void clearCache()

Forces subsequent template fetching to re-read the template contents from the filesystem instead of the cache.

setDirtyInterval

public void setDirtyInterval(int minutes)

Controls caching behavior. Set to zero to minimize caching.

Parameters:

minutes - how long to keep a template in the cache.

convertToMyTags

public java.lang.String convertToMyTags(java.lang.String withOldTags,
                                        java.lang.String oldTagStart,
                                        java.lang.String oldTagEnd)

Converts a template with an alternate tag syntax to one that matches this TemplateSet's tags.

Parameters:

withOldTags - Template text which contains tags with the old syntax

oldTagStart - old tag beginning marker

oldTagEnd - old tag end marker

Returns:

template with tags converted

convertTags

public static java.lang.String convertTags(java.lang.String withOldTags,
                                           java.lang.String oldTagStart,
                                           java.lang.String oldTagEnd)

Converts a template with an alternate tag syntax to one that matches the default tag syntax {~myTag}.

Parameters:

withOldTags - Template text which contains tags with the old syntax

oldTagStart - old tag beginning marker

oldTagEnd - old tag end marker

Returns:

template with tags converted

convertTags

public static java.lang.String convertTags(java.lang.String withOldTags,
                                           java.lang.String oldTagStart,
                                           java.lang.String oldTagEnd,
                                           java.lang.String newTagStart,
                                           java.lang.String newTagEnd)

Converts a template from one tag syntax to another.

Parameters:

withOldTags - Template text which contains tags with the old syntax

oldTagStart - old tag beginning marker

oldTagEnd - old tag end marker

newTagStart - new tag beginning marker

newTagEnd - new tag end marker

Returns:

template with tags converted

getSubset

public TemplateSet getSubset(java.lang.String context)

addProtocol

public void addProtocol(ContentSource src)

signalFailureWithNull

public void signalFailureWithNull()

getTemplatePath

public java.lang.String getTemplatePath(java.lang.String templateName,
                                        java.lang.String ext)

getResourcePath

public java.lang.String getResourcePath(java.lang.String templateName,
                                        java.lang.String ext)

getDefaultExtension

public java.lang.String getDefaultExtension()

provides

public boolean provides(java.lang.String itemName)

Specified by:

provides in interface ContentSource

setJarContext

public void setJarContext(java.lang.Class<?> classInSameJar)

setJarContext

public void setJarContext(java.lang.Object ctx)

setLayerName

public void setLayerName(java.lang.String layerName)

setEncoding

public void setEncoding(java.lang.String encoding)

getFilters

public java.util.Map<java.lang.String,ChunkFilter> getFilters()

Specified by:

getFilters in interface ChunkFactory