Dynamic Template in Java

cb.jdynamite
Class JDynamiTe

java.lang.Object
  |
  +--cb.jdynamite.analyser.DefaultDynamicElement
        |
        +--cb.jdynamite.JDynamiTe
All Implemented Interfaces:
IDynamicElement, ITemplateDocument, ITemplateElement, java.io.Serializable

public class JDynamiTe
extends DefaultDynamicElement
implements ITemplateDocument, java.io.Serializable

JDynamiTe is the unique class you need to parse a template document. This implementation extends the DefaultDynamicElement class (from package analyser), so a JDynamiTe object is a "Dynamic Element". The use is very simple :
First define the input file or input stream (for example an HTML template document) with the "setInput" method.
Secondly fill and develop this document with a few methods such as "setVariable", and "parseDynElem".
Finally, after calling the "parse" method to finalize building your dynamic document, you simply obtain the result with the "toString" method.

See an example in the main method of this class.

JDynamiTe elements

There are (only) two elements which make a document a "template" document.

1) "Variable Element"
A "Variable Element" is defined by an identifier in the template document. Its value can be changed with the JDynamiTe.setValue method.
Example of use: titles, values of cells in tables, etc.

2) "Dynamic Element"
A "Dynamic Element" is a "block" which can be dynamically developed. It has an identifier, a template definition, and a value. Its value can be set or developed with the JDynamiTe.parseDynElem and JDynamiTe.setDynElem methods.
Example of use: list, table, enumeration, etc.


Template document syntax

There are only 3 tags to use JDynamiTe : "Variable" tag, "Begin Dynamic Element" tag, and "End Dynamic Element" tag. The tag syntax is defined by regular expressions, you can change it in the analyser.
By default JDynamiTe uses the "DefaultAnalyser" to parse the template documents. By default, this analyser uses HTML style tags.

1) "Variable" tag:
 {VARNAME} 
means you can use setVariable("VARNAME", aStringValue) in Java code.

2) "Begin Dynamic Element" tag:
 <!-- BEGIN DYNAMIC : dynElemName --> 
or
 <!-- BEGIN DYNAMIC BLOCK: dynElemName --> 
means the "dynElemName" Dynamic Element definition begins on the next line.

3) "End Dynamic Element" tag:
 <!-- END DYNAMIC : dynElemName --> 
or
 <!-- END DYNAMIC BLOCK: dynElemName --> 
means the "dynElemName" Dynamic Element definition ends on the previous line.

Identifiers syntax (for Variables and Dynamic Elements):
By default, it is a word made up of alphanumeric characters and these four characters: '.', ':', '_' and '-'


New concept : "Ignored Element"

Since JDynamiTe 1.1, this optional element can be used in template documents. An "Ignored Element" is a "block" which will be completly ignored (skipped during document analysis).
Example of use: it allows the HTML designer to build more realistic pages, with concrete data, giving a better idea of the possible dynamic page look and feel. An "Ignored Element" can be inserted anywhere in the template document, even inside "Dynamic Element".

"Ignored Element" tags
 <!-- BEGIN IGNORED : ignoredElemName --> 
means an ignored block (skipped during analysis and document output) begins on the next line.
 <!-- END IGNORED : ignoredElemName --> 
means this ignored block ends on the previous line.


JDynamiTe home page

JDynamiTe latest versions, news, examples ... at http://jdynamite.sourceforge.net


Author:
Christophe Bouleau
See Also:
Serialized Form

Constructor Summary
JDynamiTe()
          Constructs an empty "JDynamiTe" (Java Dynamic Template) document.
JDynamiTe(java.lang.String name)
          Constructs an empty "JDynamiTe" (Java Dynamic Template) document.
 
Method Summary
 void clearAll()
          Reset all Variables and all Dynamic Element values.
 void clearAllDynElemValues()
          Reset all Dynamic Element values.
 void clearAllVariables()
          Reset all Variables.
 ITemplateAnalyser getAnalyser()
          Returns the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).
 IDynamicElement getDynElem(java.lang.String key)
          Returns the "Dynamic Element" identified by a string (Note: You do not need to directly call this method to use JDynamiTe).
 java.lang.String getTemplateDefinition()
          For debugging purposes : get the result (structure of the template document) of the analyser parsing.
 java.lang.String getVariable(java.lang.String key)
          Returns the value of a variable that was set by setVariable.
 java.util.Enumeration getVariableKeys()
          Returns an enumeration of the template Variable keys in this JDynamiTe document.
static void main(java.lang.String[] args)
          Provides a simple (but sufficient) example of use.
 void parse()
          Calls the parse method inherited from DefaultDynamicElement.
 void parseDynElem(java.lang.String elementName)
          This is a "key" method you call to append elements to the current value of a Dynamic Element.
 void recordDynElem(java.lang.String key, IDynamicElement value)
          Records a "Dynamic Element" in this "JDynamiTe" Document (Note: You do not need to directly call this method to use JDynamiTe).
 void setAnalyser(ITemplateAnalyser templateAnalyser)
          Set the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).
 void setDynElemValue(java.lang.String elementName, java.lang.String value)
          Set an arbitrary value to a Dynamic Element.
 void setInput(java.io.BufferedReader reader)
          Starts the analysis of the input template document.
 void setInput(java.io.InputStream istream)
          Starts the analysis of the input template document.
 void setInput(java.lang.String fileName)
          Starts the analysis of the input template document.
 void setVariable(java.lang.String key, java.lang.String value)
          Set the value of a variable.
 java.lang.String toString()
          Returns the value (after parsing) of this JDynamiTe document.
 
Methods inherited from class cb.jdynamite.analyser.DefaultDynamicElement
addElement, getDefinition, getValue, parse, setValue
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

JDynamiTe

public JDynamiTe()
Constructs an empty "JDynamiTe" (Java Dynamic Template) document.

JDynamiTe

public JDynamiTe(java.lang.String name)
Constructs an empty "JDynamiTe" (Java Dynamic Template) document.
Parameters:
name - The name of this "JDynamiTe" document, used for debugging purposes by the "getTemplateDefinition" method.
Method Detail

setInput

public void setInput(java.io.BufferedReader reader)
              throws java.io.IOException
Starts the analysis of the input template document. If no custom "ITemplateAnalyser" was defined, JDynamiTe uses the "DefaultAnalyser". After this step, all the Variables and Dynamic Elements are identified, so this JDynamiTe is ready to be developed. By default all Variables are set to an empty string value. In addition, Variable identifiers (keys) can be retreived by getVariablesKeys.
Parameters:
reader - A BufferedReader to read the input template document.
Throws:
java.io.IOException - If an I/O error occurs.
Since:
JDynamyTe 1.2
See Also:
setInput(java.io.InputStream), setInput(java.lang.String), DefaultAnalyser, setAnalyser(ITemplateAnalyser templateAnalyser)

setInput

public void setInput(java.io.InputStream istream)
              throws java.io.IOException
Starts the analysis of the input template document. If no custom "ITemplateAnalyser" was defined, JDynamiTe uses the "DefaultAnalyser". After this step, all the Variables and Dynamic Elements are identified, so this JDynamiTe is ready to be developed. By default all Variables are set to an empty string value. In addition, Variable identifiers (keys) can be retreived by getVariablesKeys.
Parameters:
istream - A stream to read the input template document.
Throws:
java.io.IOException - If an I/O error occurs.
See Also:
setInput(java.io.BufferedReader), setInput(java.lang.String), DefaultAnalyser, setAnalyser(ITemplateAnalyser templateAnalyser)

setInput

public void setInput(java.lang.String fileName)
              throws java.io.IOException,
                     java.io.FileNotFoundException
Starts the analysis of the input template document. If no custom "ITemplateAnalyser" was defined, JDynamiTe uses the "DefaultAnalyser". After this step, all the Variables and Dynamic Elements are identified, so this JDynamiTe is ready to be developed. By default all Variables are set to an empty string value. In addition, Variable identifiers (keys) can be retreived by getVariablesKeys.
Parameters:
fileName - The name of the file which contains the input template document.
Throws:
java.io.IOException - If an I/O error occurs.
java.io.FileNotFoundException - Bad filename.
See Also:
setInput(java.io.BufferedReader), setInput(java.io.InputStream), DefaultAnalyser, setAnalyser(ITemplateAnalyser templateAnalyser)

getVariable

public java.lang.String getVariable(java.lang.String key)
Returns the value of a variable that was set by setVariable. A "JDynamiTe" document maintains a list of key/value pairs, which is used when Dynamic Elements are parsed.
Specified by:
getVariable in interface ITemplateDocument
Parameters:
key - The key of the variable to retrieve.
Returns:
The value of the variable.
See Also:
setVariable(java.lang.String, java.lang.String)

setVariable

public void setVariable(java.lang.String key,
                        java.lang.String value)
Set the value of a variable. Overrides its previous value if any. A "JDynamiTe" document maintains a list of key/value pairs, which is used when Dynamic Elements are parsed.
Specified by:
setVariable in interface ITemplateDocument
Parameters:
key - The key of the variable to set.
value - The new value of this variable.
See Also:
getVariable(java.lang.String)

getVariableKeys

public java.util.Enumeration getVariableKeys()
Returns an enumeration of the template Variable keys in this JDynamiTe document. A "JDynamiTe" document maintains a list of key/value pairs, which is used when Dynamic Elements are parsed. The setInput method build this list (with an empty string as default value) during the template document analysis. After this step, the setVariable method is used to set a value to a Variable. Example of use :
 Enumeration keys = myJDynamiTeDoc.getVariableKeys();
 while (keys.hasMoreElements()) {
    String key = keys.nextElement();
    System.err.println(keys);
    String value = myDatabase.selectValue(key); // get the current value somewhere...
    myJDynamiTeDoc.setVariable(key, value); // set the template Variable.
 }
 
Returns:
The value of the variable.
Since:
JDynamiTe 1.2
See Also:
setVariable(java.lang.String, java.lang.String), setInput(InputStream istream), setInput(String fileName)

getDynElem

public IDynamicElement getDynElem(java.lang.String key)
Returns the "Dynamic Element" identified by a string (Note: You do not need to directly call this method to use JDynamiTe). A "JDynamiTe" document maintains a list of "Dynamic Elements".
Parameters:
key - The "Dynamic Element" identifier. This is the string defined in the template document in the "BEGIN DYNAMIC" tag. For example:
 <-- BEGIN DYNAMIC : myList -->
 
Here "myList" identifies the Dynamic Element which begins.
Returns:
The interface of the Dynamic Element.

recordDynElem

public void recordDynElem(java.lang.String key,
                          IDynamicElement value)
Records a "Dynamic Element" in this "JDynamiTe" Document (Note: You do not need to directly call this method to use JDynamiTe). A "JDynamiTe" document maintains a list of "Dynamic Elements". It is called by the analyser.
Specified by:
recordDynElem in interface ITemplateDocument
Parameters:
key - The "Dynamic Element" identifier.
value - An object that implements the IDynamicElement interface.

getAnalyser

public ITemplateAnalyser getAnalyser()
Returns the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).
Specified by:
getAnalyser in interface ITemplateDocument
Returns:
The current analyser.
See Also:
setAnalyser(cb.jdynamite.analyser.ITemplateAnalyser)

setAnalyser

public void setAnalyser(ITemplateAnalyser templateAnalyser)
Set the analyser that parses template documents (Note: You do not need to directly call this method to use JDynamiTe).
Specified by:
setAnalyser in interface ITemplateDocument
Parameters:
templateAnalyser - The new analyser.
See Also:
getAnalyser()

parseDynElem

public void parseDynElem(java.lang.String elementName)
This is a "key" method you call to append elements to the current value of a Dynamic Element. These elements are built from the template definition of this Dynamic Element and the current value of variables (and possibly nested Dynamic Elements). See examples.
Parameters:
elementName - The "Dynamic Element" identifier. This is the string defined in the template document in the "BEGIN DYNAMIC" tag. For example:
 <-- BEGIN DYNAMIC : myList -->
 
Here "myList" identifies the Dynamic Element that begins.

setDynElemValue

public void setDynElemValue(java.lang.String elementName,
                            java.lang.String value)
Set an arbitrary value to a Dynamic Element. For example, enables emptying a Dynamic Element if you give an empty string as argument.
Parameters:
elementName - The Dynamic Element identifier.
value - New value for The Dynamic Element

parse

public void parse()
Calls the parse method inherited from DefaultDynamicElement. As this object is the "top level" dynamic element, this method enables obtaining the "final" value of this document. You can use the "toString" method to get this value.
See Also:
toString()

toString

public java.lang.String toString()
Returns the value (after parsing) of this JDynamiTe document.
Overrides:
toString in class java.lang.Object
Returns:
Value (after parsing) of this JDynamiTe document

getTemplateDefinition

public java.lang.String getTemplateDefinition()
For debugging purposes : get the result (structure of the template document) of the analyser parsing.
Returns:
Result (structure of the template document) of the analyser parsing.

clearAll

public void clearAll()
Reset all Variables and all Dynamic Element values.

clearAllVariables

public void clearAllVariables()
Reset all Variables.

clearAllDynElemValues

public void clearAllDynElemValues()
Reset all Dynamic Element values.

main

public static void main(java.lang.String[] args)
Provides a simple (but sufficient) example of use. Needs "testTemplate.html" in current directory as a template file. Writes the result on standard output.

JDynamiTe

Copyright Christophe Bouleau