Version 4.10.0

hirondelle.web4j.ui.translate
Class Text

Object
  extended by SimpleTagSupport
      extended by hirondelle.web4j.ui.tag.TagHelper
          extended by hirondelle.web4j.ui.translate.Text
All Implemented Interfaces:
JspTag, SimpleTag

public final class Text
extends TagHelper

Custom tag for translating base language text (or a "coder key") into a localized form, and applying "wiki-style" formatting.

This tag uses Translator and LocaleSource to localize text.

There are several use cases for this tag. In general, the attributes control:

Specifying Base Text

The base text may be specified simply as the tag body, or as the value attribute.

Example 1 :

 <w:txt>
  Of prayers, I am the prayer of silence.
  Of things that move not, I am the Himalayas.
 </w:txt>
 
Example 2 uses a "coder key" :
 <w:txt value="quotation.from.bhagavad.gita" />
 

This second form is intended especially for translating items appearing inside a tag.

These two use cases are mutually exclusive : either a body must be specified, or the value attribute must be specified, but not both.

Here is another example, combining the two styles :

 <span title='<w:txt value="quotation.from.bhagavad.gita" />'>
  <w:txt>
   Of prayers, I am the prayer of silence.
   Of things that move not, I am the Himalayas.
  </w:txt>
 </span>
 

In either case, the item to be translated may be either some text in the application's base language, or it may be a 'coder key' (see Translator).

Formatting of the Result

By default, this tag will escape all special characters using EscapeChars.forHTML(String). Occasionally, it is desirable to allow some limited formatting of text input by the user. Even simple effects such as bold and italic can measurably increase legibility and clarity, and allowing links is also very useful. Most wikis allow such simple formatting. This tag uses the following special characters to denote various effects :

Example 3 has wiki style formatting:

 <w:txt wikiMarkup="true">
 Default Locale |   
 _Not all Locales are treated equally_ : there *must* be ... 
 </w:txt>
 
Is rendered as :

Default Locale
Not all Locales are treated equally : there must be ...

To allow the above rules to be interpreted as HTML by this tag, setWikiMarkup(boolean) to true.

Turning Off Translation

There are two cases in which it is useful to turn off translation altogether:

Example 4 has wiki style formatting for untranslated user input:

 <w:txt wikiMarkup="true" translate="false">
   ...render some user input with wiki style formatting...
 </w:txt>
 

Example 5 has wiki style formatting for large untranslated text, hard-coded in the JSP. An example of such text may be an extended section of "help" information :

 <w:txt locale="en">
   ..large amount of hard-coded text in English...
 </w:txt>

 <w:txt locale="fr">
   ..large amount of hard-coded text in French...
 </w:txt>
 
The above style is outside the usual translation mechanism. It does not use the configured Translator. It does not translate its content at all. Rather, it will echo the tag content only when the specified locale matches that returned by the LocaleSource. It is recommended that this style be used only when the above-mentioned problem regarding database text size exists. This style implicitly has translate="false".


Constructor Summary
Text()
           
 
Method Summary
protected  void crossCheckAttributes()
          Validate attributes against each other.
protected  String getEmittedText(String aOriginalBody)
          See class comment.
 void setLocale(String aLocale)
          Specify an explicit Locale (optional).
 void setTranslate(boolean aValue)
          Toggle translation on and off (optional, default true).
 void setValue(String aTextAsAttr)
          Set the item to be translated (optional).
 void setWikiMarkup(boolean aValue)
          Allow wiki style formatting to be used (optional, default false).
 
Methods inherited from class hirondelle.web4j.ui.tag.TagHelper
checkForContent, 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

Text

public Text()
Method Detail

setValue

public void setValue(String aTextAsAttr)
Set the item to be translated (optional).

aTextAsAttr takes two forms : user-visible text in the base language, or a coder key (known to the programmer, but not seen by the end user). See Translator for more information.

If this attribute is set, then the tag must not have a body.

Parameters:
aTextAsAttr - must have content; this value is always trimmed by this method.

setTranslate

public void setTranslate(boolean aValue)
Toggle translation on and off (optional, default true).

By default, text will be translated. An example of setting this item to false is a discussion board, where users input in a single language, and wiki style formatting is desired.

An example of rendering such text is :

   <w:txt translate="false" wikiMarkup="true">
     This is *bold*, and so on...
   </w:txt>
   


setLocale

public void setLocale(String aLocale)
Specify an explicit Locale (optional).

When this attribute is specified, this tag will never translate its content. Instead, this tag will simply emit or suppress its content, according to whether aLocale matches that returned by LocaleSource.


setWikiMarkup

public void setWikiMarkup(boolean aValue)
Allow wiki style formatting to be used (optional, default false).


crossCheckAttributes

protected void crossCheckAttributes()
Validate attributes against each other.

Overrides:
crossCheckAttributes in class TagHelper

getEmittedText

protected String getEmittedText(String aOriginalBody)
                         throws JspException
See class comment.

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.
Throws:
JspException

Version 4.10.0

Copyright Hirondelle Systems. Published October 19, 2013 - User Guide - All Docs.