hirondelle.web4j.ui.translate
Class TextFlow

Object
  SimpleTagSupport
      hirondelle.web4j.ui.tag.TagHelper
          hirondelle.web4j.ui.translate.TextFlow

All Implemented Interfaces:

JspTag, SimpleTag

public final class TextFlow
extends TagHelper

Custom tag for translating regular text flow in large sections of a web page.

This tag treats every piece of free flow text delimited by a tag as a unit of translatable base text, and passes it to Translator. That is, all tags are treated as delimiters of units of translatable text.

This tag is suitable for translating most, but not all, of the regular text flow in a web page. It is suitable for translating markup that contains short, isolated snippets of text, that have no "structure", and no dynamic data, such as the labels in a form, the column headers in a listing, and so on. (For many intranet applications, this makes up most of the free flow text appearing in the application.) Instead of using many separate <w:txt> Text tags to translate each item one by one, a single <w:txtFlow> tag can often be used to do the same thing in a single step.

Using this class has two strong advantages :

• the effort needed to internationalize a page is greatly reduced
• the markup will be significantly easier to read and maintain, since most of the free flow text remains unchanged from the single-language case

This tag is not suitable when the base text to be translated :

• contains markup
• has dynamic data of any sort
• contains a TEXTAREA with a non-empty body. Such text will be seen as a translatable unit, which is usually undesired, since such text is usually not fixed, but dynamic (that is, from the database). (To avoid this, simply nest this tag inside the <w:populate> tag surrounding the form that contains the TEXTAREA. This ensures that the population is not affected by the action of this tag.)

For example, given this text containing markup :

The <EM>raison-d'etre</EM> for this...

then this tag will split the text into three separate pieces, delimited by the EM tags. Then, each piece will be translated. For such items, this is almost always undesirable. Instead, one must use a <w:txt> Text tag, which can treat such items as a single unit of translatable text, without chopping it up into three pieces.

Example
Here, all of the LABEL tags in this form will have their content translated by the <w:txtFlow> tag :

<w:populate style='edit' using="myUser">
<w:txtFlow>
<form action='blah.do' method='post' class="user-input">
<table align="center">
<tr>
 <td>
  <label class="mandatory">Email</label>
 </td>
 <td>
  <input type="text" name="Email Address" size='30'>
 </td> 
</tr>

<tr>
 <td>
  <label>Age</label>
 </td>
 <td>
  <input type="text" name="Age" size="30">
 </td> 
</tr>

<tr>
 <td>
  <label>Desired Salary</label>
 </td>
 <td>
  <input type="text" name="Desired Salary" size="30">
 </td> 
</tr>

<tr>
 <td>
  <label> Birth Date </label>
 </td>
 <td>
  <input type="text" name="Birth Date" size="30">
 </td> 
</tr>

<tr>
 <td>
  <input type='submit' value='UPDATE'> 
 </td>
</tr>
</table>
</form>
</w:txtFlow>
</w:populate>

Constructor Summary

TextFlow()

Method Summary

protected String	getEmittedText(String aOriginalBody) Translate each piece of free flow text appearing in aOriginalBody.
void	setEscapeChars(boolean aValue) By default, this tag will escape any special characters appearing in the text flow, using EscapeChars.forHTML(String).

Methods inherited from class hirondelle.web4j.ui.tag.TagHelper

checkForContent, crossCheckAttributes, doTag, getPageContext, getPageName, getRequest, getResponse

Methods inherited from class SimpleTagSupport

findAncestorWithClass, getJspBody, getJspContext, getParent, setJspBody, setJspContext, setParent

Methods inherited from class Object

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

Constructor Detail

TextFlow

public TextFlow()

Method Detail

setEscapeChars

public void setEscapeChars(boolean aValue)

By default, this tag will escape any special characters appearing in the text flow, using EscapeChars.forHTML(String). To change that default behaviour, set this value to false.

Exercise care that text is not doubly escaped. For instance, if the text already contains character entities, and setEscapeChars is true, then the text &amp; will be emitted by this tag as &amp;amp;, for example.

getEmittedText

protected String getEmittedText(String aOriginalBody)

Translate each piece of free flow text appearing in aOriginalBody.

Each piece of text is delimited by one or more tags, and is translated using the configured Translator. Leading or trailing white space is preserved.

Specified by:

getEmittedText in class TagHelper

Parameters:

aOriginalBody - is the evaluated body of this tag. If there is no body, or if the body is present but empty, then it is null.

Returns:

the text to display in the resulting web page.