HTML
Class Template

java.lang.Object
  |
  +--HTML.Template

public class Template

extends java.lang.Object

Use HTML Templates with java.

The HTML.Template class allows you to use HTML Templates from within your java programs. It makes it possible to change the look of your servlets without having to recompile them. Use HTML.Template to separate code from presentation in your servlets.

	Hashtable args = new Hashtable();
	args.put("filename", "my_template.tmpl");

	Template t = new Template(args);

	t.setParam("title", "The HTML Template package");
	t.printTo(response.getWriter());
 

HTML.Template is based on the perl module HTML::Template by Sam Tregar

Constructor Summary

Template(java.util.Hashtable args)
Initialises a new Template object, using the values in the Hashtable args as defaults.

Template(java.lang.Object[] args)
Initialises a new Template object, using the name/value pairs passed as default values.

Template(java.lang.String filename)
Initialises a new HTML.Template object with the contents of the given file.

Method Summary

java.lang.Object	getParam(java.lang.String name) Returns a parameter from this template identified by the given name.
java.lang.String	output() Returns the parsed template as a String.
void	printTo(java.io.PrintWriter out) Prints the parsed template to the provided PrintWriter.
boolean	setParam(java.lang.String name, boolean value) Sets a single boolean parameter in this template.
java.lang.Boolean	setParam(java.lang.String name, java.lang.Boolean value) Sets a single Boolean parameter in this template.
int	setParam(java.lang.String name, int value) Sets a single int parameter in this template.
java.lang.Integer	setParam(java.lang.String name, java.lang.Integer value) Sets a single Integer parameter in this template.
java.lang.String	setParam(java.lang.String name, java.lang.String value) Sets a single scalar parameter in this template.
java.util.Vector	setParam(java.lang.String name, java.util.Vector value) Sets a single list parameter in this template.
int	setParams(java.util.Hashtable params) Sets the values of parameters in this template from a Hashtable.

Methods inherited from class java.lang.Object

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

Constructor Detail

Template

public Template(java.lang.String filename)
         throws java.io.FileNotFoundException,
                java.lang.IllegalStateException,
                java.io.IOException

Initialises a new HTML.Template object with the contents of the given file.

Parameters:

filename - a string containing the name of the file to be used as a template. This may be an absolute or relative path to a template file.

Throws:

java.io.FileNotFoundException - If the file specified does not exist.

java.lang.IllegalStateException - If <tmpl_include> is used when no_includes is in effect.

java.io.IOException - If an input or output Exception occurred while reading the template.

Template

public Template(java.lang.Object[] args)
         throws java.lang.ArrayIndexOutOfBoundsException,
                java.io.FileNotFoundException,
                java.lang.IllegalArgumentException,
                java.lang.IllegalStateException,
                java.io.IOException

Initialises a new Template object, using the name/value pairs passed as default values.

The parameters passed may be any combination of filename, scalarref, arrayref, path, case_sensitive, loop_context_vars, strict, die_on_bad_params, global_vars, max_includes, no_includes, search_path_on_include and debug. Each with its own value. Any one of filename, scalarref or arrayref must be passed.

Eg:

	String [] template_init = {
		"filename",  "my_template.tmpl",
		"case_sensitive", "true",
		"max_includes",   "5"
	};

      Template t = new Template(template_init);
 

The above code creates a new Template object, initialising its input file to my_template.tmpl, turning on case_sensitive parameter matching, and restricting maximum depth of includes to five.

Parameter values that take boolean values may either be a String containing the words true/false, or the Boolean values Boolean.TRUE and Boolean.FALSE. Numeric values may be Strings, or Integers.

Parameters:

args - an array of name/value pairs to initialise this template with. Valid values for each element may be:

filename - [Required] a String containing the path to a template file

scalarref - [Required] a String containing the entire template as its contents

arrayref - [Required] an array of lines that make up the template

path - [Optional] an array of Strings specifying the directories in which to look for the template file. If not specified, the current working directory is used. If specified, only the directories in this array are used. If you want the current directory searched, include "." in the path.

If you have only a single path, it can be a plain String instead of a String array.

This is effective only for the template file, and not for included files, but see search_path_on_include for how to change that.

case_sensitive - [Optional] specifies whether parameter matching is case sensitive or not. A value of "false", "0" or "" is considered false. All other values are true.

Default: false

loop_context_vars - [Optional] when set to true four loop context variables are made available inside a loop: __FIRST__, __LAST__, __INNER__, __ODD__, __COUNTER__. They can be used with <TMPL_IF>, <TMPL_UNLESS> and <TMPL_ELSE> to control how a loop is output. Example:

	    <TMPL_LOOP NAME="FOO">
	       <TMPL_IF NAME="__FIRST__">
	         This only outputs on the first pass.
	       </TMPL_IF>

	       <TMPL_IF NAME="__ODD__">
	         This outputs on the odd passes.
	       </TMPL_IF>

	       <TMPL_UNLESS NAME="__ODD__">
	         This outputs on the even passes.
	       </TMPL_IF>

	       <TMPL_IF NAME="__INNER__">
	         This outputs on passes that are 
		neither first nor last.
	       </TMPL_IF>

	       <TMPL_IF NAME="__LAST__">
	         This only outputs on the last pass.
	       <TMPL_IF>
	    </TMPL_LOOP>
			

NOTE: A loop with only a single pass will get both __FIRST__ and __LAST__ set to true, but not __INNER__.

Default: false

strict - [Optional] if set to false the module will allow things that look like they might be TMPL_* tags to get by without throwing an exception. Example:

          <TMPL_HUH NAME=ZUH>
			

Would normally cause an error, but if you create the Template with strict == 0, HTML.Template will ignore it.

Default: true

die_on_bad_params - [Optional] if set to true the module will complain if you try to set template.setParam("param_name", "value") and param_name doesn't exist in the template.

This effect doesn't descend into loops.

Default: false (may change in later versions)

global_vars - [Optional] normally variables declared outside a loop are not available inside a loop. This option makes TMPL_VARs global throughout the template. It also affects TMPL_IF and TMPL_UNLESS.

	    <p>This is a normal variable: <TMPL_VAR NORMAL>.</p>

	    <TMPL_LOOP NAME="FROOT_LOOP>
	       Here it is inside the loop: <TMPL_VAR NORMAL>
	    </TMPL_LOOP>
			

Normally this wouldn't work as expected, since <TMPL_VAR NORMAL>'s value outside the loop isn't available inside the loop.

Default: false (may change in later versions)

max_includes - [Optional] specifies the maximum depth that includes can reach. Including files to a depth greater than this value causes an error message to be displayed. Set to 0 to disable this protection.

Default: 10

no_includes - [Optional] If set to true, disallows the <TMPL_INCLUDE> tag in the template file. This can be used to make opening untrusted templates slightly less dangerous.

Default: false

search_path_on_include - [Optional] if set, then the path is searched for included files as well as the template file. See the path parameter for more information.

Default: false

debug - [Optional] setting this option to true causes HTML.Template to print random error messages to STDERR.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If an odd number of parameters is passed.

java.io.FileNotFoundException - If the file specified does not exist or no filename is passed.

java.lang.IllegalArgumentException - If an unknown parameter is passed.

java.lang.IllegalStateException - If <tmpl_include> is used when no_includes is in effect.

java.io.IOException - If an input or output Exception occurred while reading the template.

Since:

0.0.8

Template

public Template(java.util.Hashtable args)
         throws java.io.FileNotFoundException,
                java.lang.IllegalArgumentException,
                java.lang.IllegalStateException,
                java.io.IOException

Initialises a new Template object, using the values in the Hashtable args as defaults.

The parameters passed are the same as in the Template(Object []) constructor. Each with its own value. Any one of filename, scalarref or arrayref must be passed.

Eg:

	Hashtable args = new Hashtable();
	args.put("filename", "my_template.tmpl");
	args.put("case_sensitive", "true");
	args.put("loop_context_vars", Boolean.TRUE);
	// args.put("max_includes", "5");
	args.put("max_includes", new Integer(5));

	Template t = new Template(args);
 

The above code creates a new Template object, initialising its input file to my_template.tmpl, turning on case_sensitive parameter matching, and the loop context variables __FIRST__, __LAST__, __ODD__ and __INNER__, and restricting maximum depth of includes to five.

Parameter values that take boolean values may either be a String containing the words true/false, or the Boolean values Boolean.TRUE and Boolean.FALSE. Numeric values may be Strings, or Integers.

Parameters:

args - a Hashtable of name/value pairs to initialise this template with. Valid values are the same as in the Template(Object []) constructor.

Throws:

java.io.FileNotFoundException - If the file specified does not exist or no filename is passed.

java.lang.IllegalArgumentException - If an unknown parameter is passed.

java.lang.IllegalStateException - If <tmpl_include> is used when no_includes is in effect.

java.io.IOException - If an input or output Exception occurred while reading the template.

Since:

0.0.10

See Also:

Template(Object [])

Method Detail

printTo

public void printTo(java.io.PrintWriter out)

Prints the parsed template to the provided PrintWriter.

Parameters:

out - the PrintWriter that this template will be printed to

output

public java.lang.String output()

Returns the parsed template as a String.

Returns:

a string containing the parsed template

setParams

public int setParams(java.util.Hashtable params)

Sets the values of parameters in this template from a Hashtable.

Parameters:

params - a Hashtable containing name/value pairs for this template. Keys in this hashtable must be Strings and values may be either Strings or Vectors.

Parameter names are currently not case sensitive.

Parameter names can contain only letters, digits, ., /, +, - and _ characters.

Parameter names starting and ending with a double underscore are not permitted. eg: __myparam__ is illegal.

Returns:

the number of parameters actually set. Illegal parameters will not be set, but no error/exception will be thrown.

setParam

public java.lang.String setParam(java.lang.String name,
                                 java.lang.String value)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.NullPointerException

Sets a single scalar parameter in this template.

Parameters:

name - a String containing the name of this parameter. Parameter names are currently not case sensitive.

value - a String containing the value of this parameter

Returns:

the value of the parameter set

Throws:

java.lang.IllegalArgumentException - if the parameter name contains illegal characters

java.lang.NullPointerException - if the parameter name is null

See Also:

setParams(Hashtable)

setParam

public java.lang.Integer setParam(java.lang.String name,
                                  java.lang.Integer value)
                           throws java.lang.IllegalArgumentException,
                                  java.lang.NullPointerException

Sets a single Integer parameter in this template.

Parameters:

name - a String containing the name of this parameter. Parameter names are currently not case sensitive.

value - an Integer containing the value of this parameter

Returns:

the value of the parameter set

Throws:

java.lang.IllegalArgumentException - if the parameter name contains illegal characters

java.lang.NullPointerException - if the parameter name is null

See Also:

setParams(Hashtable)

setParam

public int setParam(java.lang.String name,
                    int value)
             throws java.lang.IllegalArgumentException,
                    java.lang.NullPointerException

Sets a single int parameter in this template.

Parameters:

name - a String containing the name of this parameter. Parameter names are currently not case sensitive.

value - an int containing the value of this parameter

Returns:

the value of the parameter set

Throws:

java.lang.IllegalArgumentException - if the parameter name contains illegal characters

java.lang.NullPointerException - if the parameter name is null

See Also:

setParams(Hashtable)

setParam

public boolean setParam(java.lang.String name,
                        boolean value)
                 throws java.lang.IllegalArgumentException,
                        java.lang.NullPointerException

Sets a single boolean parameter in this template.

Parameters:

name - a String containing the name of this parameter. Parameter names are currently not case sensitive.

value - a boolean containing the value of this parameter

Returns:

the value of the parameter set

Throws:

java.lang.IllegalArgumentException - if the parameter name contains illegal characters

java.lang.NullPointerException - if the parameter name is null

See Also:

setParams(Hashtable)

setParam

public java.lang.Boolean setParam(java.lang.String name,
                                  java.lang.Boolean value)
                           throws java.lang.IllegalArgumentException,
                                  java.lang.NullPointerException

Sets a single Boolean parameter in this template.

Parameters:

name - a String containing the name of this parameter. Parameter names are currently not case sensitive.

value - a Boolean containing the value of this parameter

Returns:

the value of the parameter set

Throws:

java.lang.IllegalArgumentException - if the parameter name contains illegal characters

java.lang.NullPointerException - if the parameter name is null

See Also:

setParams(Hashtable)

setParam

public java.util.Vector setParam(java.lang.String name,
                                 java.util.Vector value)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.NullPointerException

Sets a single list parameter in this template.

Parameters:

name - a String containing the name of this parameter. Parameter names are not currently case sensitive.

value - a Vector containing a list of Hashtables of parameters

Returns:

the value of the parameter set

Throws:

java.lang.IllegalArgumentException - if the parameter name contains illegal characters

java.lang.NullPointerException - if the parameter name is null

See Also:

setParams(Hashtable)

getParam

public java.lang.Object getParam(java.lang.String name)
                          throws java.util.NoSuchElementException,
                                 java.lang.NullPointerException

Returns a parameter from this template identified by the given name.

Parameters:

name - a String containing the name of the parameter to be returned. Parameter names are not currently case sensitive.

Returns:

the value of the requested parameter. If the parameter is a scalar, the return value is a String, if the parameter is a list, the return value is a Vector.

Throws:

java.util.NoSuchElementException - if the parameter does not exist in the template

java.lang.NullPointerException - if the parameter name is null