| java.lang.Object
 dinamica.TemplateEngine
| TemplateEngine | | public class TemplateEngine (Code) | | Core-level framework class: Text Generator.
Generates text output (html, xml, sql, etc) given
a template with some special markers that will be replaced
by data (supplied from recordsets). This class is used by the MVC mechanism of this framework
and for general purpose text management.
This is a very powerfull class, it can generate html forms
with its values ready to be edited, whole tables with one line
of code, complete well written, portable SQL statements with one line of code,
no matter how many fields or the type of each field, the statement will
be formatted appropiately, without programmer effort.
It helps to COMPLETELY separate content from presentation, the
templates are dynamically loaded and some labels are replaced with
data provided by recordsets using very simple and effective logic.
Markers are represented by:
Field Markers: ${fld:FieldName}
Default Values Markers: ${def:DefaultValueName}
Sequence Markers: ${seq:nextval@SequenceName} - ${seq:currval@SequenceName}. This markers allows cross-database sequence expressions, the generation
of the actual SEQUENCE SQL expression is determined by context parameters in WEB.XML (sequence-nextval and sequence-currval).
As you can see, the markers distingish themselves by a prefix which
denotes its type of marker (fld, def or seq).
Field Markers can have an additional attribute (not valid for SQL generation)
representing the output format, using any valid Java mask for dates and numbers.
Example: {fld:FieldName@mask} - where "mask" would be the output format mask.
Repeating blocks can also be generated and are conmmonly used for
printing tables or filling HTML SELECT controls (ComboBox/ListBox). Example:
<repeat>
<tr>
<td>${fld:col_1}</td>
<td>${fld:col_2}</td>
</tr>
</repeat>
This can be replaced using one line of code with the data
values of each record in a recordset, default formats are applied
unless you specify an output format for a specific field. Default formats
are configured in WEB.XML, as context parameters (def-format-date and def-format-double).
This class also supports two advanced features: Special markers for dynamic labes ${lbl:KeyName} which are replaced
according to a pre-selected language (ES, EN, IT, etc), this allows multi-language templates, and
also supports includes, the ability to dynamically include the output of another MVC transaction, which allows
composition of pages from smaller parts, using a special marker: ${inc:ModuleName}
Please consult the How-to documentation to learn all about this class and its
role inside the framework.
Context parameters in WEB.XML used by this class:
<![CDATA[
<context-param>
<param-name>def-format-date</param-name>
<param-value>dd-MM-yyyy</param-value>
<description>default format for dates</description>
</context-param>
<context-param>
<param-name>sequence-nextval</param-name>
<param-value>${seq}.NEXTVAL</param-value>
<description>SQL expression to obtain the next sequence value - sequence name will be ${seq}</description>
</context-param>
<context-param>
<param-name>sequence-currval</param-name>
<param-value>${seq}.CURRVAL</param-value>
<description>SQL expression to obtain the current sequence value - sequence name will be ${seq}</description>
</context-param>
]]>
Creation date: 18/09/2003
Last Update: 18/09/2003
(c) 2003 Martin Cordova
This code is released under the LGPL license
author:
Martin Cordova |
| Method Summary | |
| public void | clearFieldMarkers()
Replace all markers of type ${fld:xxx} with an empty string "".
Added on Aug-30-2005 to support a new print mode="clear" in config.xml. | | public String | encodeHTML(String input)
Encode reserved html characters (&,<,>,',").
This characters will be replaced by the pre-defined entities. | | public String | encodeJS(String input)
Encode reserved javascript characters (\,").
This characters will be replaced by the pre-defined entities. | | public String | encodeXML(String input)
Encode reserved xml characters (&,<,>,',").
This characters will be replaced by the pre-defined entities. | | String | getLabel(String labelName, Element root, String language)
| | public ArrayList<Marker> | getMarkers(String prefix)
| | ArrayList<TemplateSegment> | getSegments()
Split template into segments stored into an array. | | public String | getSql(Recordset rs)
Generates SQL using the recordset values from the current record,
substitutes the field markers with properly formatted values. | | public String | getTagBody(String tagName)
Returns a Tag body, including the tag markers. | | public void | print(HttpServletResponse res)
Print template and process any INCLUDE directive
present into the template; in order to do this the
class required a reference to the ServletContext, Request
and Response, otherwise it can't dispatch to include another servlets.
No writer must be obtained from the Servlet response object
prior to calling this method, because this method will call getWriter() from
the passed Response object.
NOTE: default values and dynamic labels will be automatically
replaced by this method. | | public void | replace(Recordset rs, String nullValueExpr)
Replace all possible field markers with corresponding
recordset field values from current record. | | public void | replace(Recordset rs, String nullValueExpr, String repeatSectionTag)
Navigate all the recordset and replace the
values of each record. | | void | replace(Recordset rs, String nullValueExpr, ArrayList markers)
| | public void | replace(String toReplace, String newValue)
| | public void | replaceDefaultValues()
Replace default values present in the template, default values
are special markers expressed in the form: ${def:valueName}
Implemented defaults are:
${def:user} - HttpServletRequest.getPrincipal().getUserName(). | | public void | replaceLabels()
Replace dynamic labels ${lbl:Name} using the
session locale, which must be indicated using the method
setLocale, otherwise the language code
specified in the context-attribute def-language in WEB.XML will be used
to select the default locale. | | public void | replaceRequestAttributes()
| | public void | replaceSessionAttributes()
| | public void | setCheckbox(String controlName, Recordset rs)
HTML Control utility method.
Set checkbox values for multiple items using a recordset
to lookup the values from a field and set the corresponding checkbox items
in the checkbox control group. | | public void | setComboValue(String controlName, String value)
HTML Control utility method.
Select combobox item for single select combobox. | | public void | setComboValue(String controlName, Recordset rs)
HTML Control utility method.
Set combobox values for multiple items using a recordset
to lookup the values from a field and set the corresponding option items
in the select control. | | public void | setEncoding(String encoding)
| | public void | setLocale(Locale l)
| | public void | setRadioButton(String controlName, String value)
HTML Control utility method.
Select RadioButton control from a group of controls
using a value to match the appropiate control
NOTE: All html keywords related to the control must be
in lower case, including attributes and tag names. | | public void | setRequest(HttpServletRequest req)
| | public void | setRowEventObject(IRowEvent obj)
| | public void | setTemplate(String string)
| | public void | setValues(dinamica.parser.FastTemplateEngine fte, ArrayList<dinamica.parser.Marker> markers, Recordset rs, String nullExpression)
| | public String | toString()
|
| TemplateEngine | | public TemplateEngine(ServletContext ctx, HttpServletRequest req, String template)(Code) | | Servlet oriented constructor
Parameters:
ctx - Servlet Context - will be used to read context parameters.
Parameters:
req - Servlet Request - will be used to produce default values, like userid or remote_addr.
Parameters:
template - Text template with markers
throws:
Throwable - |
| clearFieldMarkers | | public void clearFieldMarkers() throws Throwable(Code) | | Replace all markers of type ${fld:xxx} with an empty string "".
Added on Aug-30-2005 to support a new print mode="clear" in config.xml.
throws:
Throwable - |
| encodeHTML | | public String encodeHTML(String input)(Code) | | Encode reserved html characters (&,<,>,',").
This characters will be replaced by the pre-defined entities.
Parameters:
input - String that will be processed String with all reserved characters replaced |
| encodeJS | | public String encodeJS(String input)(Code) | | Encode reserved javascript characters (\,").
This characters will be replaced by the pre-defined entities.
Parameters:
input - String that will be processed String with all reserved characters replaced |
| encodeXML | | public String encodeXML(String input)(Code) | | Encode reserved xml characters (&,<,>,',").
This characters will be replaced by the pre-defined entities.
Parameters:
input - String that will be processed String with all reserved characters replaced |
| getLabel | | String getLabel(String labelName, Element root, String language) throws Throwable(Code) | | Lookup a dynamic label value given the language code and the label ID
Parameters:
labelName - Label ID
Parameters:
root - The root element of the labels.xml tree
Parameters:
language - The ISO language code (es, en, it, etc.) The label translation
throws:
Throwable - if the label ID or the language code are not valid |
| getMarkers | | public ArrayList<Marker> getMarkers(String prefix) throws Throwable(Code) | | Returns a list of markers of a given type
Parameters:
prefix - The type of marker (fld, lbl, inc, seq) ArrayList containing Marker objects
throws:
Throwable - |
| getSegments | | ArrayList<TemplateSegment> getSegments() throws Throwable(Code) | | Split template into segments stored into an array.
A segment may be a printable text or an INCLUDE directive
to include the content of another resource from the same context
ArrayList containing TemplateSegment objects
throws:
Throwable - |
| getSql | | public String getSql(Recordset rs) throws Throwable(Code) | | Generates SQL using the recordset values from the current record,
substitutes the field markers with properly formatted values. Saves a lot
of work with only one line of code. This method is smart enough as to generate
well formatted values for Strings and portable formats for dates and timestamps,
using the date/timestamp canonical syntax. Also special characters like single quote (') in
Strings will be correctly escaped to avoid SQL syntax errors or SQL injection attacks.
This object must be created using a SQL template containing markers like ${fld:FieldName}, ${def:date} or ${seq:nextval@SeqName}
Parameters:
rs - Recordset containing at least one record, the record position must be valid Well formatted SQL with all the markers replaced by the corresponding values (only fld, def and seq markers are considered, no format masks allowed)
throws:
Throwable - |
| getTagBody | | public String getTagBody(String tagName) throws Throwable(Code) | | Returns a Tag body, including the tag markers.
This is a utility method that may be used by special
Output modules, like Master/Detail reports that need
to extract and later replace subsections of a template.
Parameters:
tagName -
throws:
Throwable - if tagName is not present in the template |
| print | | public void print(HttpServletResponse res) throws Throwable(Code) | | Print template and process any INCLUDE directive
present into the template; in order to do this the
class required a reference to the ServletContext, Request
and Response, otherwise it can't dispatch to include another servlets.
No writer must be obtained from the Servlet response object
prior to calling this method, because this method will call getWriter() from
the passed Response object.
NOTE: default values and dynamic labels will be automatically
replaced by this method. This is the preferred way to print a template
to make sure everything is being replaced, the caller is only responsable
for setting the appropiate response headers.
Parameters:
res - HttpServletResponse
throws:
Throwable - if the ServletContext reference is null |
| replace | | public void replace(Recordset rs, String nullValueExpr) throws Throwable(Code) | | Replace all possible field markers with corresponding
recordset field values from current record. This method
is mainly used to populate forms
Parameters:
rs - Recordset with a valid record position
Parameters:
nullValueExpr - The string to represent null values ("" or )
throws:
Throwable - |
| replace | | public void replace(Recordset rs, String nullValueExpr, String repeatSectionTag) throws Throwable(Code) | | Navigate all the recordset and replace the
values of each record. This method is used to produce
tables or fill controls like ComboBoxes or ListBoxes. It is
suitable for any section of the template that must be repeated
as many times as records are in the recordset
Parameters:
rs - Recordset
Parameters:
nullValueExpr - The string to represent null values ("" or ) - when generating html tables it should be
Parameters:
RepeatSectionTag - A custom tag that encloses the repeatable section
throws:
Throwable - |
| replace | | void replace(Recordset rs, String nullValueExpr, ArrayList markers) throws Throwable(Code) | | Internal method that factorizes most of the code
that is common to all the overloaders
Parameters:
rs - Recordset
Parameters:
nullValueExpr - The string to represent null values ("" or ) - when generating html tables it should be
Parameters:
markers - ArrayList containing the field markers
throws:
Throwable - |
| replace | | public void replace(String toReplace, String newValue)(Code) | | Replace any text into the template
Parameters:
toReplace - Text to be replaced
Parameters:
newValue - New value |
| replaceDefaultValues | | public void replaceDefaultValues() throws Throwable(Code) | | Replace default values present in the template, default values
are special markers expressed in the form: ${def:valueName}
Implemented defaults are:
${def:user} - HttpServletRequest.getPrincipal().getUserName(). If the user is not authenticated then returns an empty string ""
${def:date} - yyyy-MM-dd
${def:time} - HH:mm:ss
${def:timestamp} - yyyy-MM-dd HH:mm:ss:SSS
${def:host} - HttpServletRequest.getServerName()
${def:context} - HttpServletRequest.getContextPath()
${def:remoteaddr} - HttpServletRequest.getRemoteAddr()
${def:uri} - HttpServletRequest.getRequestURI()
${def:dateDMY} - dd-MM-yyyy
${def:dateMDY} - MM-dd-yyyy
${def:actionroot} - action parent path
${def:httpserver} - protocol://hostname:port
All values extracted from HttpServletRequest will be replaced
by an empty string "" if the request object is null. Use the method
setRequest() to set the request object or the special constructor
TemplateEngine(ServletContext ctx, HttpServletRequest req, String t) if you want to set
the request object.
Default values can be used in every kind of template, SQL, HTML, XML, etc.
|
| replaceLabels | | public void replaceLabels() throws Throwable(Code) | | Replace dynamic labels ${lbl:Name} using the
session locale, which must be indicated using the method
setLocale, otherwise the language code
specified in the context-attribute def-language in WEB.XML will be used
to select the default locale. If none has been properly configured
or the label does not exist for the selected Locale, then
an exception will be triggered. This mechanism uses the label
configuration file stored in /WEB-INF/labels.xml. Please check
the documentation to learn the structure of this file.
Place the appropiate markers and make sure the labels.xml file is properly configured.
In order to use this method, the TemplateEngine must have access to
the ServletContext, so use the appropiate constructor. If there is no
valid reference to the ServletContext, then this method will trigger
an error
throws:
Throwable - |
| replaceRequestAttributes | | public void replaceRequestAttributes() throws Throwable(Code) | | Replace field markers representing request attribute values
like ${req:attributeID}
throws:
Throwable - |
| replaceSessionAttributes | | public void replaceSessionAttributes() throws Throwable(Code) | | Replace field markers representing session attribute values
like ${ses:attributeID}
throws:
Throwable - |
| setCheckbox | | public void setCheckbox(String controlName, Recordset rs) throws Throwable(Code) | | HTML Control utility method.
Set checkbox values for multiple items using a recordset
to lookup the values from a field and set the corresponding checkbox items
in the checkbox control group. All records from the recordset are used.
Parameters:
controlName - Name of the html select control which is also the nameof the field name to use from the Recordset
Parameters:
rs -
throws:
Throwable - |
| setComboValue | | public void setComboValue(String controlName, String value) throws Throwable(Code) | | HTML Control utility method.
Select combobox item for single select combobox. This method
will insert the word "selected" in the appropiate option element
from the corresponding select html control.
NOTE: All html keywords related to the control must be
in lower case, including attributes and tag names. Name and Value lookup
is case sensitive!
Parameters:
controlName - HTML control name attribute
Parameters:
value - Option value to search for
throws:
Throwable - if can't find control or its closing tag |
| setComboValue | | public void setComboValue(String controlName, Recordset rs) throws Throwable(Code) | | HTML Control utility method.
Set combobox values for multiple items using a recordset
to lookup the values from a field and set the corresponding option items
in the select control. All records from the recordset are used.
Parameters:
controlName - Name of the html select control which is also the nameof the field name to use from the Recordset
Parameters:
rs -
throws:
Throwable - |
| setEncoding | | public void setEncoding(String encoding)(Code) | | Set template encoding - for information purporses only
Parameters:
encoding - Canonical name of character encoding (ISO-8859-1, etc) |
| setLocale | | public void setLocale(Locale l) throws Throwable(Code) | | Set custom LOCALE for formatting
Parameters:
l - Locale object |
| setRadioButton | | public void setRadioButton(String controlName, String value) throws Throwable(Code) | | HTML Control utility method.
Select RadioButton control from a group of controls
using a value to match the appropiate control
NOTE: All html keywords related to the control must be
in lower case, including attributes and tag names. Name and Value lookup
is case sensitive!
Parameters:
controlName - HTML control name attribute
Parameters:
value - Value to search for
throws:
Throwable - if can't find control |
| setRequest | | public void setRequest(HttpServletRequest req)(Code) | | Set servlet request reference
Parameters:
req - HTTP Servlet Request object |
| setRowEventObject | | public void setRowEventObject(IRowEvent obj)(Code) | | Set reference to callback object that
implements the IRowEvent interface
Parameters:
obj - Object that implements the IRowEvent interface |
| setTemplate | | public void setTemplate(String string)(Code) | | Change template body - if necessary, should be called before replacing any data
because all previous changes will be lost
Parameters:
string - New template body |
| toString | | public String toString()(Code) | | Return current state of the internal template
|
|
|