| java.lang.Object
 freemarker.core.Configurable
freemarker.template.Template
| Template | | public class Template extends Configurable (Code) | | A core FreeMarker API that represents a compiled template.
Typically, you will use a
Configuration object to instantiate a template.
Configuration cfg = new Configuration();
...
Template myTemplate = cfg.getTemplate("myTemplate.html");
However, you can also construct a template directly by passing in to
the appropriate constructor a java.io.Reader instance that is set to
read the raw template text. The compiled template is
stored in an an efficient data structure for later use.
To render the template, i.e. to merge it with a data model, and
thus produce "cooked" output, call the process method.
Any error messages from exceptions thrown during compilation will be
included in the output stream and thrown back to the calling code.
To change this behavior, you can install custom exception handlers using
Configurable.setTemplateExceptionHandler(TemplateExceptionHandler) on
a Configuration object (for all templates belonging to a configuration) or on
a Template object (for a single template).
It's not legal to modify the values of FreeMarker settings: a) while the
template is executing; b) if the template object is already accessible from
multiple threads.
version:
$Id: Template.java,v 1.216.2.3 2006/03/10 17:49:02 revusky Exp $ |
| Inner Class :public static class WrongEncodingException extends ParseException | |
| Method Summary | |
| public void | addImport(LibraryLoad ll)
| | public void | addMacro(Macro macro)
| | public void | addPrefixNSMapping(String prefix, String nsURI)
This is used internally. | | public TreePath | containingElements(int column, int line)
| | public Environment | createProcessingEnvironment(Object rootMap, Writer out, ObjectWrapper wrapper)
Creates a
freemarker.core.Environment Environment object,
using this template, the data model provided as the root map object, and
the supplied object wrapper to convert map elements to template models.
You can then call Environment.process() on the returned environment
to set off the actual rendering.
Use this method if you want to do some special initialization on the environment
before template processing, or if you want to read the environment after template
processing.
Example:
This:
Environment env = myTemplate.createProcessingEnvironment(root, out, null);
env.process();
is equivalent with this:
myTemplate.process(root, out);
But with createProcessingEnvironment, you can manipulate the environment
before and after the processing:
Environment env = myTemplate.createProcessingEnvironment(root, out);
env.include("include/common.ftl", null, true); // before processing
env.process();
TemplateModel x = env.getVariable("x"); // after processing
Parameters:
rootMap - the root node of the data model. | | public Environment | createProcessingEnvironment(Object rootMap, Writer out)
Same as createProcessingEnvironment(rootMap, out, null). | | public void | dump(PrintStream ps)
Dump the raw template in canonical form. | | public void | dump(Writer out)
Dump the raw template in canonical form. | | public Configuration | getConfiguration()
Returns the Configuration object associated with this template. | | public String | getDefaultNS()
| | public String | getEncoding()
Returns the character encoding used for reading included files. | | public List | getImports()
| | public Map | getMacros()
| | public String | getName()
The path of the template file relative to the directory what you use to store the templates.
For example, if the real path of template is "/www/templates/community/forum.fm",
and you use ""/www/templates" as
Configuration.setDirectoryForTemplateLoading "directoryForTemplateLoading" ,
then name should be "community/forum.fm". | | public String | getNamespaceForPrefix(String prefix)
the NamespaceUri mapped to this prefix in this template. | | public static Template | getPlainTextTemplate(String name, String content, Configuration config)
Returns a trivial template, one that is just a single block of
plain text, no dynamic content. | | public String | getPrefixForNamespace(String nsURI)
the prefix mapped to this nsURI in this template. | | public String | getPrefixedName(String localName, String nsURI)
| | public TemplateElement | getRootTreeNode()
| | public String | getSource(int beginColumn, int beginLine, int endColumn, int endLine)
Returns the template source at the location
specified by the coordinates given. | | public void | process(Object rootMap, Writer out)
Processes the template, using data from the map, and outputs
the resulting text to the supplied Writer The elements of the
map are converted to template models using the default object wrapper
returned by the
Configuration.getObjectWrapper getObjectWrapper() method of the Configuration.
Parameters:
rootMap - the root node of the data model. | | public void | process(Object rootMap, Writer out, ObjectWrapper wrapper, TemplateNodeModel rootNode)
Processes the template, using data from the root map object, and outputs
the resulting text to the supplied writer, using the supplied
object wrapper to convert map elements to template models.
Parameters:
rootMap - the root node of the data model. | | public void | process(Object rootMap, Writer out, ObjectWrapper wrapper)
Processes the template, using data from the root map object, and outputs
the resulting text to the supplied writer, using the supplied
object wrapper to convert map elements to template models.
Parameters:
rootMap - the root node of the data model. | | public void | setEncoding(String encoding)
Sets the character encoding to use for
included files. | | public String | toString()
Returns a string representing the raw template
text in canonical form. |
| DEFAULT_NAMESPACE_PREFIX | | final public static String DEFAULT_NAMESPACE_PREFIX(Code) | | |
| Template | | public Template(String name, Reader reader, Configuration cfg, String encoding) throws IOException(Code) | | Constructs a template from a character stream.
Parameters:
name - the path of the template file relative to the directory what you use to storethe templates. See Template.getName for more details.
Parameters:
reader - the character stream to read from. It will always be closed (Reader.close()).
Parameters:
cfg - the Configuration object that this Template is associated with.If this is null, the "default" Configuration object is used,which is highly discouraged, because it can easily lead toerroneous, unpredictable behaviour.(See more Configuration.getDefaultConfiguration here...)
Parameters:
encoding - This is the encoding that we are supposed to be using. If this isnon-null (It's not actually necessary because we are using a Reader) then it ischecked against the encoding specified in the FTL header -- assuming that is specified,and if they don't match a WrongEncodingException is thrown. |
| addImport | | public void addImport(LibraryLoad ll)(Code) | | Called by code internally to maintain
a list of imports
|
| addMacro | | public void addMacro(Macro macro)(Code) | | Called by code internally to maintain
a table of macros
|
| addPrefixNSMapping | | public void addPrefixNSMapping(String prefix, String nsURI)(Code) | | This is used internally.
|
| containingElements | | public TreePath containingElements(int column, int line)(Code) | | an array of the elements containing the given column and line numbers.
Parameters:
column - the column
Parameters:
line - the line |
| createProcessingEnvironment | | public Environment createProcessingEnvironment(Object rootMap, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException(Code) | | Creates a
freemarker.core.Environment Environment object,
using this template, the data model provided as the root map object, and
the supplied object wrapper to convert map elements to template models.
You can then call Environment.process() on the returned environment
to set off the actual rendering.
Use this method if you want to do some special initialization on the environment
before template processing, or if you want to read the environment after template
processing.
Example:
This:
Environment env = myTemplate.createProcessingEnvironment(root, out, null);
env.process();
is equivalent with this:
myTemplate.process(root, out);
But with createProcessingEnvironment, you can manipulate the environment
before and after the processing:
Environment env = myTemplate.createProcessingEnvironment(root, out);
env.include("include/common.ftl", null, true); // before processing
env.process();
TemplateModel x = env.getVariable("x"); // after processing
Parameters:
rootMap - the root node of the data model. If null, anempty data model is used. Can be any object that the effective objectwrapper can turn into a TemplateHashModel Basically, simple andbeans wrapper can turn java.util.Map objects into hashesand the Jython wrapper can turn both a PyDictionary as well as anyobject that implements __getitem__ into a template hash.Naturally, you can pass any object directly implementingTemplateHashModel as well.
Parameters:
wrapper - The object wrapper to use to wrap objects intoTemplateModel instances. If null, the default wrapper retrievedby Configurable.getObjectWrapper is used.
Parameters:
out - the writer to output the text to. the freemarker.core.Environment Environment object created for processing
throws:
TemplateException - if an exception occurs while setting up the Environment object.
throws:
IOException - if an exception occurs doing any auto-imports |
| getConfiguration | | public Configuration getConfiguration()(Code) | | Returns the Configuration object associated with this template.
|
| getEncoding | | public String getEncoding()(Code) | | Returns the character encoding used for reading included files.
|
| getName | | public String getName()(Code) | | The path of the template file relative to the directory what you use to store the templates.
For example, if the real path of template is "/www/templates/community/forum.fm",
and you use ""/www/templates" as
Configuration.setDirectoryForTemplateLoading "directoryForTemplateLoading" ,
then name should be "community/forum.fm". The name is used for example when you
use <include ...> and you give a path that is relative to the current
template, or in error messages when FreeMarker logs an error while it processes the template.
|
| getNamespaceForPrefix | | public String getNamespaceForPrefix(String prefix)(Code) | | the NamespaceUri mapped to this prefix in this template. (Or null if there is none.) |
| getPlainTextTemplate | | public static Template getPlainTextTemplate(String name, String content, Configuration config)(Code) | | Returns a trivial template, one that is just a single block of
plain text, no dynamic content. (Used by the cache module to create
unparsed templates.)
Parameters:
name - the path of the template file relative to the directory what you use to storethe templates. See Template.getName for more details.
Parameters:
content - the block of text that this template represents
Parameters:
config - the configuration to which this template belongs |
| getPrefixForNamespace | | public String getPrefixForNamespace(String nsURI)(Code) | | the prefix mapped to this nsURI in this template. (Or null if there is none.) |
| getPrefixedName | | public String getPrefixedName(String localName, String nsURI)(Code) | | the prefixed name, based on the ns_prefixes definedin this template's header for the local name and node namespacepassed in as parameters. |
| getSource | | public String getSource(int beginColumn, int beginLine, int endColumn, int endLine)(Code) | | Returns the template source at the location
specified by the coordinates given.
Parameters:
beginColumn - the first column of the requested source, 1-based
Parameters:
beginLine - the first line of the requested source, 1-based
Parameters:
endColumn - the last column of the requested source, 1-based
Parameters:
endLine - the last line of the requested source, 1-based
See Also: freemarker.core.TemplateObject.getSource |
| process | | public void process(Object rootMap, Writer out) throws TemplateException, IOException(Code) | | Processes the template, using data from the map, and outputs
the resulting text to the supplied Writer The elements of the
map are converted to template models using the default object wrapper
returned by the
Configuration.getObjectWrapper getObjectWrapper() method of the Configuration.
Parameters:
rootMap - the root node of the data model. If null, anempty data model is used. Can be any object that the effective objectwrapper can turn into a TemplateHashModel. Basically, simple andbeans wrapper can turn java.util.Map objects into hashesand the Jython wrapper can turn both a PyDictionary as well asany object that implements __getitem__ into a template hash.Naturally, you can pass any object directly implementingTemplateHashModel as well.
Parameters:
out - a Writer to output the text to.
throws:
TemplateException - if an exception occurs during template processing
throws:
IOException - if an I/O exception occurs during writing to the writer. |
| process | | public void process(Object rootMap, Writer out, ObjectWrapper wrapper, TemplateNodeModel rootNode) throws TemplateException, IOException(Code) | | Processes the template, using data from the root map object, and outputs
the resulting text to the supplied writer, using the supplied
object wrapper to convert map elements to template models.
Parameters:
rootMap - the root node of the data model. If null, anempty data model is used. Can be any object that the effective objectwrapper can turn into a TemplateHashModel Basically, simple andbeans wrapper can turn java.util.Map objects into hashesand the Jython wrapper can turn both a PyDictionary as well as anyobject that implements __getitem__ into a template hash.Naturally, you can pass any object directly implementingTemplateHashModel as well.
Parameters:
wrapper - The object wrapper to use to wrap objects intoTemplateModel instances. If null, the default wrapper retrievedby Configurable.getObjectWrapper is used.
Parameters:
out - the writer to output the text to.
Parameters:
rootNode - The root node for recursive processing, this may be null.
throws:
TemplateException - if an exception occurs during template processing
throws:
IOException - if an I/O exception occurs during writing to the writer. |
| process | | public void process(Object rootMap, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException(Code) | | Processes the template, using data from the root map object, and outputs
the resulting text to the supplied writer, using the supplied
object wrapper to convert map elements to template models.
Parameters:
rootMap - the root node of the data model. If null, anempty data model is used. Can be any object that the effective objectwrapper can turn into a TemplateHashModel Basically, simple andbeans wrapper can turn java.util.Map objects into hashesand the Jython wrapper can turn both a PyDictionary as well as anyobject that implements __getitem__ into a template hash.Naturally, you can pass any object directly implementingTemplateHashModel as well.
Parameters:
wrapper - The object wrapper to use to wrap objects intoTemplateModel instances. If null, the default wrapper retrievedby Configurable.getObjectWrapper is used.
Parameters:
out - the writer to output the text to.
throws:
TemplateException - if an exception occurs during template processing
throws:
IOException - if an I/O exception occurs during writing to the writer. |
| setEncoding | | public void setEncoding(String encoding)(Code) | | Sets the character encoding to use for
included files. Usually you don't set this value manually,
instead it is assigned to the template upon loading.
|
| toString | | public String toString()(Code) | | Returns a string representing the raw template
text in canonical form.
|
|
|