biz.source_code.miniTemplator
Class MiniTemplator

java.lang.Object
  biz.source_code.miniTemplator.MiniTemplator

public class MiniTemplator
extends Object

A compact template engine for HTML files.

Template syntax:

    Variables:
       ${VariableName}

    Blocks:
       <!-- $beginBlock blockName -->
         ... block contents ...
       <!-- $endBlock blockName -->

    Conditional blocks:
       <!-- $if flag1 flag2 -->
         ... included if flag1 or flag2 is set ...
       <!-- $elseIf !flag3 flag4 -->
         ... included if flag3 is not set or flag4 is set ...
       <!-- $else -->
         ... included if none of the above conditions is met ...
       <!-- $endIf -->

    Short form of conditional blocks:
    (only recognized if TemplateSpecification.shortFormEnabled is true)
       <$? flag1 flag2 >
         ... included if flag1 or flag2 is set ...
       <$: !flag3 flag4 >
         ... included if flag3 is not set or flag4 is set ...
       <$:>
         ... included if none of the above conditions is met ...
       <$/?>
    Example:
       <$?de> Hallo Welt!
       <$:fr> Bonjour tout le monde!
       <$:  > Hello world!
       <$/?>

    Include a subtemplate:
       <!-- $include relativeFileName -->

General remarks:

• Variable names, block names, condition flags and commands (e.g. "$beginBlock") are case-insensitive.
• The same variable may be used multiple times within a template.
• Multiple blocks with the same name may occur within a template.
• Blocks can be nested.
• Conditional blocks ($if) and includes ($include) are resolved when the template is parsed. Parsing is done within the MiniTemplator constructor. Condition flags can be passed to the constructor using TemplateSpecification.
• Normal blocks ($beginBlock) must be added (and can be repeated) by the application program using addBlock().
• The MiniTemplatorCache class may be used to cache MiniTemplator objects with parsed templates.

Project home page: www.source-code.biz/MiniTemplator
Author: Christian d'Heureuse, Inventec Informatik AG, Zurich, Switzerland

Nested Class Summary

static class	MiniTemplator.BlockNotDefinedException Thrown when Minitemplator.addBlock is called with a blockName that is not defined within the template.
static class	MiniTemplator.Builder Specifies the parameters for constructing a MiniTemplator object.
static class	MiniTemplator.TemplateSyntaxException Thrown when a syntax error is encountered within the template.
static class	MiniTemplator.VariableNotDefinedException Thrown when Minitemplator.setVariable is called with a variableName that is not defined within the template and the isOptional parameter is false.

Constructor Summary

protected

MiniTemplator() Dummy constructor, used internally in newInstance().

Method Summary

void	addBlock(String blockName) Adds an instance of a template block.
void	addBlock(String blockName, boolean isOptional) Adds an instance of a template block.
void	addBlockOpt(String blockName) Adds an instance of an optional template block.
boolean	blockExists(String blockName) Checks whether a block with the specified name exists within the template.
MiniTemplator	cloneReset() Clones this MiniTemplator object and resets the clone.
static String	escapeHtml(String s) Escapes special HTML characters.
String	generateOutput() Generates the HTML page and returns it as a string.
void	generateOutput(String outputFileName) Generates the HTML page and writes it into a file.
void	generateOutput(Writer outputWriter) Generates the HTML page and writes it to a character stream.
Map<String,String>	getVariables() Returns a map with the names and current values of the template variables.
protected String	loadSubtemplate(String subtemplateName) Loads the template string of a subtemplate (used for the $Include command).
protected MiniTemplator	newInstance() Allocates a new uninitialized MiniTemplator object.
void	reset() Resets the MiniTemplator object to the initial state.
void	setVariable(String variableName, int variableValue) Sets a template variable to an integer value.
void	setVariable(String variableName, String variableValue) Sets a template variable.
void	setVariable(String variableName, String variableValue, boolean isOptional) Sets a template variable.
void	setVariableEsc(String variableName, String variableValue) Sets a template variable to an escaped value.
void	setVariableEsc(String variableName, String variableValue, boolean isOptional) Sets a template variable to an escaped value.
void	setVariableOpt(String variableName, int variableValue) Sets an optional template variable to an integer value.
void	setVariableOpt(String variableName, String variableValue) Sets an optional template variable.
void	setVariableOptEsc(String variableName, String variableValue) Sets an optional template variable to an escaped value.
boolean	variableExists(String variableName) Checks whether a variable with the specified name exists within the template.

Methods inherited from class java.lang.Object

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

Constructor Detail

MiniTemplator

protected MiniTemplator()

Dummy constructor, used internally in newInstance().

Method Detail

newInstance

protected MiniTemplator newInstance()

Allocates a new uninitialized MiniTemplator object. This method is intended to be overridden in a derived class. It is called from cloneReset() to create a new MiniTemplator object.

loadSubtemplate

protected String loadSubtemplate(String subtemplateName)
                          throws IOException

Loads the template string of a subtemplate (used for the $Include command). This method can be overridden in a subclass, to load subtemplates from somewhere else, e.g. from a database.

This implementation of the method interprets subtemplateName as a relative file path name and reads the template string from that file. MiniTemplator.TemplateSpecification#subtemplateBasePath is used to convert the relative path of the subtemplate into an absolute path.

Parameters:

subtemplateName - the name of the subtemplate. Normally a relative file path. This is the argument string that was specified with the "$Include" command. If the string has quotes, the quotes are removed before this method is called.

Returns:

the template text string of the subtemplate.

Throws:

IOException

reset

public void reset()

Resets the MiniTemplator object to the initial state. All variable values are cleared and all added block instances are deleted. This method can be used to produce another HTML page with the same template. It is faster than creating another MiniTemplator object, because the template does not have to be read and parsed again.

cloneReset

public MiniTemplator cloneReset()

Clones this MiniTemplator object and resets the clone. This method is used to copy a MiniTemplator object. It is fast, because the template does not have to be parsed again, and the internal data structures that contain the parsed template information are shared among the clones.

This method is used by the MiniTemplatorCache class to clone the cached MiniTemplator objects.

setVariable

public void setVariable(String variableName,
                        String variableValue,
                        boolean isOptional)
                 throws MiniTemplator.VariableNotDefinedException

Sets a template variable.

For variables that are used in blocks, the variable value must be set before addBlock() is called.

Parameters:

variableName - the name of the variable to be set. Case-insensitive.

variableValue - the new value of the variable. May be null.

isOptional - specifies whether an exception should be thrown when the variable does not exist in the template. If isOptional is false and the variable does not exist, an exception is thrown.

Throws:

MiniTemplator.VariableNotDefinedException - when no variable with the specified name exists in the template and isOptional is false.

setVariable

public void setVariable(String variableName,
                        String variableValue)
                 throws MiniTemplator.VariableNotDefinedException

Sets a template variable.

Convenience method for: setVariable (variableName, variableValue, false)

Parameters:

variableName - the name of the variable to be set. Case-insensitive.

variableValue - the new value of the variable. May be null.

Throws:

MiniTemplator.VariableNotDefinedException - when no variable with the specified name exists in the template.

See Also:

setVariable(String, String, boolean)

setVariable

public void setVariable(String variableName,
                        int variableValue)
                 throws MiniTemplator.VariableNotDefinedException

Sets a template variable to an integer value.

Convenience method for: setVariable (variableName, Integer.toString(variableValue))

Parameters:

variableName - the name of the variable to be set. Case-insensitive.

variableValue - the new value of the variable.

Throws:

MiniTemplator.VariableNotDefinedException - when no variable with the specified name exists in the template.

setVariableOpt

public void setVariableOpt(String variableName,
                           String variableValue)

Sets an optional template variable.

Convenience method for: setVariable (variableName, variableValue, true)

Parameters:

variableName - the name of the variable to be set. Case-insensitive.

variableValue - the new value of the variable. May be null.

See Also:

setVariable(String, String, boolean)

setVariableOpt

public void setVariableOpt(String variableName,
                           int variableValue)

Sets an optional template variable to an integer value.

Convenience method for: setVariableOpt (variableName, Integer.toString(variableValue))

Parameters:

variableName - the name of the variable to be set. Case-insensitive.

variableValue - the new value of the variable.

setVariableEsc

public void setVariableEsc(String variableName,
                           String variableValue,
                           boolean isOptional)
                    throws MiniTemplator.VariableNotDefinedException

Sets a template variable to an escaped value.

Convenience method for: setVariable (variableName, MiniTemplator.escapeHtml(variableValue), isOptional)

Parameters:

variableName - the name of the variable to be set.

variableValue - the new value of the variable. May be null. Special HTML/XML characters are escaped.

isOptional - specifies whether an exception should be thrown when the variable does not exist in the template. If isOptional is false and the variable does not exist, an exception is thrown.

Throws:

MiniTemplator.VariableNotDefinedException - when no variable with the specified name exists in the template and isOptional is false.

See Also:

setVariable(String, String, boolean), escapeHtml(String)

setVariableEsc

public void setVariableEsc(String variableName,
                           String variableValue)
                    throws MiniTemplator.VariableNotDefinedException

Sets a template variable to an escaped value.

Convenience method for: setVariable (variableName, MiniTemplator.escapeHtml(variableValue), false)

Parameters:

variableName - the name of the variable to be set. Case-insensitive.

variableValue - the new value of the variable. May be null. Special HTML/XML characters are escaped.

Throws:

MiniTemplator.VariableNotDefinedException - when no variable with the specified name exists in the template.

See Also:

setVariable(String, String, boolean), escapeHtml(String)

setVariableOptEsc

public void setVariableOptEsc(String variableName,
                              String variableValue)

Sets an optional template variable to an escaped value.

Convenience method for: setVariable (variableName, MiniTemplator.escapeHtml(variableValue), true)

Parameters:

variableName - the name of the variable to be set. Case-insensitive.

variableValue - the new value of the variable. May be null. Special HTML/XML characters are escaped.

See Also:

setVariable(String, String, boolean), escapeHtml(String)

variableExists

public boolean variableExists(String variableName)

Checks whether a variable with the specified name exists within the template.

Parameters:

variableName - the name of the variable. Case-insensitive.

Returns:

true if the variable exists.
false if no variable with the specified name exists in the template.

getVariables

public Map<String,String> getVariables()

Returns a map with the names and current values of the template variables.

addBlock

public void addBlock(String blockName,
                     boolean isOptional)
              throws MiniTemplator.BlockNotDefinedException

Adds an instance of a template block.

If the block contains variables, these variables must be set before the block is added. If the block contains subblocks (nested blocks), the subblocks must be added before this block is added. If multiple blocks exist with the specified name, an instance is added for each block occurrence.

Parameters:

blockName - the name of the block to be added. Case-insensitive.

isOptional - specifies whether an exception should be thrown when the block does not exist in the template. If isOptional is false and the block does not exist, an exception is thrown.

Throws:

MiniTemplator.BlockNotDefinedException - when no block with the specified name exists in the template and isOptional is false.

addBlock

public void addBlock(String blockName)
              throws MiniTemplator.BlockNotDefinedException

Adds an instance of a template block.

Convenience method for: addBlock (blockName, false)

Parameters:

blockName - the name of the block to be added. Case-insensitive.

Throws:

MiniTemplator.BlockNotDefinedException - when no block with the specified name exists in the template.

See Also:

addBlock(String, boolean)

addBlockOpt

public void addBlockOpt(String blockName)

Adds an instance of an optional template block.

Convenience method for: addBlock (blockName, true)

Parameters:

blockName - the name of the block to be added. Case-insensitive.

See Also:

addBlock(String, boolean)

blockExists

public boolean blockExists(String blockName)

Checks whether a block with the specified name exists within the template.

Parameters:

blockName - the name of the block.

Returns:

true if the block exists.
false if no block with the specified name exists in the template.

generateOutput

public void generateOutput(String outputFileName)
                    throws IOException

Generates the HTML page and writes it into a file.

Parameters:

outputFileName - name of the file to which the generated HTML page will be written.

Throws:

IOException - when an i/o error occurs while writing to the file.

generateOutput

public void generateOutput(Writer outputWriter)
                    throws IOException

Generates the HTML page and writes it to a character stream.

Parameters:

outputWriter - a character stream (writer) to which the HTML page will be written.

Throws:

IOException - when an i/o error occurs while writing to the stream.

generateOutput

public String generateOutput()

Generates the HTML page and returns it as a string.

Returns:

A string that contains the generated HTML page.

escapeHtml

public static String escapeHtml(String s)

Escapes special HTML characters. Replaces the characters <, >, &, ' and " by their corresponding HTML/XML character entity codes.

Parameters:

s - the input string.

Returns:

the escaped output string.