Java Doc for Template.java in  » Web-Framework » rife-1.6.1 » com » uwyn » rife » template » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Templates can be used for a variety of text types, including XHTML, plain text, XML, SQL and even Java source. Each template type has similar features, the biggest difference is the syntax of the invisible tag which takes the form of a comment in the corresponding language (<!-- --> for XHTML and XML, /* -* / for Java and SQL, ...).

Using templates

Templates are most commonly used to produce web pages, which is why a method like com.uwyn.rife.engine.Element.getXhtmlTemplate(String) is used. By obtaining a template instance from the active com.uwyn.rife.engine.Element , features that are related to the web engine are added. To print a template for page output, com.uwyn.rife.engine.Element.print(Template) is usually used. However, the content of any template instance can be retrieved with the Template.getContent method which produces a regular String that is usable anywhere.

Components of a template

Templates are controlled by external code (usually a ), but communication is bidirectional between a template and the logic that controls it. A template can provide content to the controller through blocks, and the controller can insert or replace text in the template through template values. The controller can also provide the template with expression variables and resource bundles.

Values

A value is the simplest concept in a template. It is the placeholder for text somewhere in a block or in the page itself. In a HTML template, a value called "name" is created using a declaration like:

<!--!V 'name'/-->

The controller can then fill this value with any of the Template.setValue(String,String) setValue and Template.appendValue(String,String)appendValue methods.

Values are mainly a one-way communication channel from the logic to the template. However, values may contain a default value which can be by the controller:

<!--V 'name'-->Some default<!--/V-->

Values are automatically filled in many ways aside from calling Template.setValue and Template.appendValue directly. We will discuss this later.

Blocks

Blocks represent the other direction of communication between a controller and a template. A HTML template can define a block called "greeting" like this:

<!--B 'greeting'-->Welcome, <!--V 'name'/--><!--/B-->

The literal text in the block is not accessible by the controller. It is evaluated when the block is used. For example by , or in the template itself. The evaluation is based on the values that are currently present in the template. If a block contains a value that hasn't been set yet, the value placeholder will be remembered, unpopulated. It will be evaluated against another value context the next time the content of the block is used.

As soon as value placeholders exist when a block is used, they are captured from the template and replaced with their available content. They will become immutable in the result of the operation that used the block. This means that repeated calls to Template.appendBlock can append a block to a value multiple times with different values each time. This feature allows blocks to be used for producing repeating constructs such as tables, using a pattern like this:

template.removeValue("people", "");
 Iterator it = people.iterator();
 while (it.hasNext()) {
 Person person = (Person)it.next();
 template.setValue("name", person.getName());
 template.setValue("age", person.getAge());
 template.appendBlock("people", "person");
 }

Nested loops and corresponding nested blocks may be used to produce more complex constructs.

Expressions

Templates may contain small boolean expressions that are written in JVM scripting languages like OGNL, Groovy, or Janino. These expressions will be automatically evaluated and allow certain blocks to be assigned automatically to a value according to the scripted conditions. The controller does not execute the scripts itself, but it may provide variables to which the scripts have access, using the Template.setExpressionVar setExpressionVar method. For example, if a template contains:

<!--V 'GROOVY:welcome'--><!--/V-->
 <!--V 'GROOVY:welcome:[[ showWelcome ]]'-->Welcome,
 <!--V 'name'/--><!--/V-->

A controller could decide whether the welcome block should be shown using:

template.setExpressionVar("showWelcome", person != null);

Apart from the expression variables, each expression is evaluated against a current root object whose methods and properties you can access using the regular scripting language syntax. This root object is by default the template instance that you are processing.

To make it easy to write expressions against commonly used contexts, RIFE also provides specialized scripted tags that set different root objects. Currently the language:ROLEUSER and language:CONFIG tags are provided.

Localization

It's possible to easily localize templates through the standard ResourceBundle mechanism that is available in Java. The strings that are localized are automatically filtered and replace values tags. The format for localized values is:

<!--V 'L10N:key'-->default value<!--/V-->

Of course, before replacement, the template instance has to know where to look for the key. Therefore, the Template.addResourceBundle(ResourceBundle) method needs to be called to make the template aware of it.

For example, consider the following resource bundles:

text_nl.properties

hello = Hallo

text_fr.properties

hello = Bonjour

and the following template:

Hey mister, I said: <!--V 'L10N:hello'/-->!"

The following Java code:

Template template_html = TemplateFactory.HTML.get("text");
 ResourceBundle bundle = Localization.getResourceBundle("text", "fr");
 template_html.addResourceBundle(bundle);
 System.out.println(template.getContent());

will output:

Hey mister, I said: "Bonjour!"

Just replacing the second line with the following:

...
 ResourceBundle bundle = Localization.getResourceBundle("text", "nl");
 ...

will output:

Hey mister, I said: "Hallo!"

Very often, resourcebundle are used for the whole application. Therefore, application-wide default resource bundles can be specified for each template type through the com.uwyn.rife.config RIFEconfiguration , for example:

<list name="TEMPLATE_DEFAULT_RESOURCEBUNDLES_ENGINEHTML">
 <item>l10n/graphics</item>
 <item>l10n/text</item>
 <item>l10n/descriptions</item>
 </list>

This will automatically add these resourcebundles to any template instance of the corresponding type, calling Template.addResourceBundle(ResourceBundle) is thus not needed anymore and localization will happen without any intervention from the controller.

While resource bundles offer a good method to isolate localized text snippets, it's sometimes interesting to be able to conditionally display parts of templates with lots of markup. For this purpose, resource bundles are actually awkward to use. Templates are therefore able to set blocks automatically to values, according to the default localization language (L10N_DEFAULT_LANGUAGE configuration parameter). This can be done with the <!--B 'LANG:id:language'--> block syntax.

For example:

<!--V 'LANG:value1'-->default<!--/V--> [!V 'LANG:value2'/]
 <!--B 'LANG:value1:nl'-->ja ja<!--/B-->
 [!B 'LANG:value2:fr']oui oui[!/B]
 [!B 'LANG:value2:en ']yes yes[!/B]

will display this when the default language is 'en':

default yes yes

or this when the default language is 'fr':

default oui oui

or this when the default language is 'nl':

ja ja [!V 'LANG:value2'/]

Value renderers

Besides the main manipulation logic of a template, value content needs to be sometimes created that is solely presentation related. This doesn't actually have its place in elements and sometimes even creates a burden. For these purposes, we created the ValueRenderer interface. Classes that implement this interface can be specified in any template like this:

<!--V 'RENDER:pakkage.classname'/-->

An instance of the class will be created and the ValueRenderer.render method will be called if the value hasn't been set yet. This has as side-effect that if you have several occurances of this value ID, they will all have the same renderer value and the renderer will only be called once.

If you need to have different results of the same renderer, you need to use a differentiator, like this:

<!--V 'RENDER:pakkage.classname:differentiator'/-->

Encoding

Templates automatically encode values to the appropriate format (HTML, XHTML, etc.) when using forms, , localization tags, and when . However, in many cases it is necessary to encode values manually, to prevent malicious content from being inserted into your site, or simply to display text correctly if it may contain illegal characters (like < in HTML). You can encode text using the template's encoder after calling the Template.getEncoder method.

Other features

Templates are powerful and some features are not described here. The Templates wiki page describes several other features, including filtered values, alternative means of localization, and other forms of templates.
author:
   Keith Lea <keith[remove] at cs dot oswego dot edu>
author:
   Geert Bevin (gbevin[remove] at uwyn dot com)
version:
   $Revision: 3643 $
since:
   1.0

If no matching block for the current language is found, the content of the specified value will not be modified.

This method is called automatically when the output is generated (such as when calling Template.getContent() ).

This list is the internal representation of all content with placeholders for the values that aren't filled in yet.

This list is the internal representation of all content with placeholders for the values that aren't filled in yet.

For example, given a class:

 class Person {
 private String first;
 private String last;
 public String getFirstName() { return first; }
 public void setFirstName(String name) { this.first = name; }
 public String getLastName() { return last; }
 public void setLastName(String name) { this.last = name; }
 

And given a template:

 Hello <!--V 'firstName'/--> <!--V 'lastName'/-->.
 

Calling this method with an instance of Person where first was "Jim" and last was "James", would produce:

Hello Jim James.

Calling this method is equivalent to calling Template.setValue(String,String) setValue individually for each property of the bean.

This method uses this template's to encode the bean properties before setting the values.

For example, given a class:

 class Person {
 private String first;
 private String last;
 public String getFirstName() { return first; }
 public void setFirstName(String name) { this.first = name; }
 public String getLastName() { return last; }
 public void setLastName(String name) { this.last = name; }
 

And given a template:

 Hello <!--V 'NAME:firstName'/--> <!--V 'NAME:lastName'/-->.
 

Calling this method with an instance of Person where first was "Jim" and last was "James", and the prefix "NAME:", would produce:

Hello Jim James.

Calling this method is equivalent to calling Template.setValue(String,String) setValue individually for each property of the bean prefixed with the given prefix.

This method uses this template's to encode the bean properties before setting the values.

The returned internal value is tied closely to the template it was obtained from, methods like InternalValue.appendBlock(String)InternalValue.appendBlock reference blocks within this template. a new internal value instance for constructing more complexparts of this template
See Also:   InternalValue
since:
   1.0

This method is normally called automatically during template initialization. You should call it if you wish to re-evaluate the tags at any time during the template's life. the list of names of the template values that were generated
since:
   1.0

The prefix for OGNL is "OGNL:", the prefix for Groovy is "GROOVY:" and the prefix for Janino is "JANINO:".

The context for the expressions will be the Config object returned by Config.getRepInstance .

Expression config tags are evaluated automatically when the output is generated (such as when calling Template.getContent() ). You can manually call this method to force evaluation of the tags earlier than that.
Parameters:
  id - the ID whose expression tag will be replaced with the valueof the evaluated expression in the tag ID the list of names of the template values that were generated
since:
   1.0

The prefix for OGNL is "OGNL:", the prefix for Groovy is "GROOVY:" and the prefix for Janino is "JANINO:".

This method is called automatically when the output is generated (such as when calling Template.getContent() ). You can manually call this method to force evaluation of the tags earlier than that.
Parameters:
  id - the ID whose expression tag will be replaced with the valueof the evaluated expression in the tag ID the list of names of the template values that were generated
since:
   1.0

This method is normally called automatically during template initialization. You should call it if you wish to re-evaluate the tags at any time during the template's life. the list of names of the template values that were generated
since:
   1.0

If no matching block for the current language is found, the content of the specified value will not be modified.

This method is called automatically when the output is generated (such as when calling Template.getContent() ). You can manually call this method to force evaluation of the tags earlier than that.
Parameters:
  id - the ID whose language tag should be filled with theappropriate block the list of names of the template values that were generated
since:
   1.0

For example, given a class MyRenderer in the package "org.rifers.something", which extends ValueRenderer , a value "RENDER:org.rifers.something.MyRenderer:test" would create a new instance of MyRenderer (using its no-arg constructor), call render(this, "RENDER:org.rifers.something.MyRenderer:test", "test"), and set the value in this template to whatever value the call returns.

Value renderer tags are evaluated automatically when the output is generated (such as when calling Template.getContent() ). You can manually call this method to force evaluation of the tags earlier than that.
exception:
  TemplateException - if a class in a render tag cannot beinstantiated the list of names of the template values that were generated
since:
   1.0

Values without content will either use their default value if it has been provided, or the tag that was used to declare the value will be output as-is.

All specialized tags will also be evaluated (resourcebundle localization, block localization, value renderers, expressions, ...). the entire textual content of the template
exception:
  TemplateException - when an error occurred during theprocessing of the specialized tags
See Also:   Template.appendBlock
See Also:   Template.setBlock
See Also:   Template.getBlock
See Also:   Template.hasBlock
since:
   1.0

null if no default content type is known for this template instance
since:
   1.3

If no default value was specified for the given value, this method will return null.
Parameters:
  id - the ID of a value in this template, or null the original text value of the specified value
See Also:   Template.hasDefaultValue
since:
   1.0

This list is the internal representation of all content with placeholders for the values that aren't filled in yet. This structure is mainly used internally by the framework. The list structure also makes it possible to optimize performance and memory usage.
Parameters:
  id - the ID of a block in this template a list of the contents of the specified block
exception:
  TemplateException - if no such block exists; or

if an error occurred during the retrieval
See Also:   Template.getDeferredContent
since:
   1.0

This list is the internal representation of all content with placeholders for the values that aren't filled in yet. This structure is mainly used internally by the framework. The list structure also makes it possible to optimize performance and memory usage. a list of the contents of this template
exception:
  TemplateException - if an error occurred during the retrieval
See Also:   Template.getDeferredBlock
since:
   1.0

This method is mainly used by the framework itself, the supported filter regular expressions are available from TemplateFactory and TemplateFactoryEngineTypes .
Parameters:
  filter - a template factory regular expression a list of captured groups for matching block ID's
See Also:   Template.hasFilteredBlocks
since:
   1.0

This method is mainly used by the framework itself, the supported filter regular expressions are available from TemplateFactory and TemplateFactoryEngineTypes .
Parameters:
  filter - a template factory regular expression a list of captured groups for matching value ID's
See Also:   Template.hasFilteredValues
since:
   1.0

If no such value exists in this template, this method will not throw an exception, it will return false.
Parameters:
  id - the ID of a value in this template whether the specified value has been set
See Also:   Template.appendValue
See Also:   Template.setValue
See Also:   Template.isValueSet
See Also:   Template.removeValue
See Also:   Template.removeValues
See Also:   Template.blankValue
See Also:   Template.hasValueId
since:
   1.0

Calling this method is equivalent to calling Template.removeValueremoveValue once for the name of each property of the given bean.
Parameters:
  bean - a bean
exception:
  TemplateException - if this template has no bean handlingcapability; or

an error occurred during the introspection of the bean
See Also:   Template.setBean
since:
   1.0

Calling this method is equivalent to calling Template.removeValueremoveValue once for the name of each property of the given bean, prefixed with the given prefix.
Parameters:
  bean - a bean whose properties will be used to determine whichvalues to remove from the template
Parameters:
  prefix - a prefix
exception:
  TemplateException - if this template has no bean handlingcapability; or

an error occurred during the introspection of the bean
See Also:   Template.setBean
since:
   1.0

For example, given a class:

 class Person {
 private String first;
 private String last;
 public String getFirstName() { return first; }
 public void setFirstName(String name) { this.first = name; }
 public String getLastName() { return last; }
 public void setLastName(String name) { this.last = name; }
 

And given a template:

 Hello <!--V 'firstName'/--> <!--V 'lastName'/-->.
 

Calling this method with an instance of Person where first was "Jim" and last was "James", would produce:

Hello Jim James.

Calling this method is equivalent to calling Template.setValue(String,String) setValue individually for each property of the bean.

This method uses this template's to encode the bean properties before setting the values. To prevent this, use .

Only bean properties will be considered for insertion in the template. This means only properties with a getter and a setter will be considered.
Parameters:
  bean - a bean whose properties will be used to fill in values inthe template
exception:
  TemplateException - if this template has no bean handlingcapability; or

an error occurred during the introspection of the bean
See Also:   Template.removeBean
since:
   1.0

For example, given a class:

 class Person {
 private String first;
 private String last;
 public String getFirstName() { return first; }
 public void setFirstName(String name) { this.first = name; }
 public String getLastName() { return last; }
 public void setLastName(String name) { this.last = name; }
 

And given a template:

 Hello <!--V 'NAME:firstName'/--> <!--V 'NAME:lastName'/-->.
 

Calling this method with an instance of Person where first was "Jim" and last was "James", and the prefix "NAME:", would produce:

Hello Jim James.

Calling this method is equivalent to calling Template.setValue(String,String) setValue individually for each property of the bean prefixed with the given prefix.

This method uses this template's to encode the bean properties before setting the values. To prevent this, use .

Only bean properties will be considered for insertion in the template. This means only properties with a getter and a setter will be considered.
Parameters:
  bean - a bean whose properties will be used to fill in values inthe template
Parameters:
  prefix - the prefix of values which will be filled with the givenbean's property values
exception:
  TemplateException - if this template has no bean handlingcapability; or

an error occurred during the introspection of the bean
See Also:   Template.removeBean
since:
   1.0

For example, given a class:

 class Person {
 private String first;
 private String last;
 public String getFirstName() { return first; }
 public void setFirstName(String name) { this.first = name; }
 public String getLastName() { return last; }
 public void setLastName(String name) { this.last = name; }
 

And given a template:

 Hello <!--V 'NAME:firstName'/--> <!--V 'NAME:lastName'/-->.
 

Calling this method with an instance of Person where first was "Jim" and last was "James", and the prefix "NAME:", would produce:

Hello Jim James.

Calling this method is equivalent to calling Template.setValue(String,String) setValue individually for each property of the bean prefixed with the given prefix.

If encode is true, this method will use this template's to encode the bean properties before setting the values.

Only bean properties will be considered for insertion in the template. This means only properties with a getter and a setter will be considered.
Parameters:
  bean - a bean whose properties will be used to fill in values inthe template
Parameters:
  prefix - the prefix of values which will be filled with the givenbean's property values
Parameters:
  encode - true if the bean poroperty values have to beencoded; or

false otherwise
exception:
  TemplateException - if this template has no bean handlingcapability; or

an error occurred during the introspection of the bean
See Also:   Template.removeBean
since:
   1.0

This is used when Template.evaluateL10nTags filling localized textvalues .
Parameters:
  lang - a 2-letter language code for the language to be used bythis template
See Also:   Template.getLanguage
since:
   1.0

If the given template is null, the specified value will be set to an empty string.
Parameters:
  id - the ID of the value in this template
Parameters:
  template - a template
exception:
  TemplateException - if the specified value ID does not existin this template; or

if an error occurred during the evaluation of the template parameter
See Also:   Template.appendValue
See Also:   Template.isValueSet
See Also:   Template.removeValue
See Also:   Template.removeValues
See Also:   Template.blankValue
See Also:   Template.hasValueId
since:
   1.0

when the character set isn't valid
exception:
  TemplateException - when an error occurs during the templatecontent evaluation
See Also:   Template.writeBlock
See Also:   Template.writeContent(OutputStream)
See Also:   Template.writeContent(OutputStream,String)
since:
   1.0

when the character set isn't valid
exception:
  TemplateException - when an error occurs during the templatecontent evaluation
See Also:   Template.writeBlock
See Also:   Template.writeContent(OutputStream)
See Also:   Template.write
since:
   1.0