Package biz.source_code.miniTemplator

Class 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:
       <$? 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.
    • Normal blocks ($beginBlock) must be added (and can be repeated) by the application program using addBlock().

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

    • Constructor Detail

      • MiniTemplator

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

    • Method Detail

      • 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.

        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.
        Returns:

      • 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,
                        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)

      • 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.

      • 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.