hirondelle.web4j.ui.translate
Class Text

Object
  SimpleTagSupport
      hirondelle.web4j.ui.tag.TagHelper
          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 to be translated
• formatting of the translated result
• turning off translation altogether

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 :

• *bold* for bold (needs intial space before first '*')
• _italic_ for italic (needs initial space before first '_')
• ^preserve formatting^ for preserving whitespace (<PRE>)
• ~~~~ on an otherwise blank line for a horizontal rule
• [link:http:\\www.javapractices.com\Topic1.cjp enumerations] produces this link: enumerations
• one or more empty lines for a paragraph (<P>)
• a bar | at the end of a line for a line break (<BR>)
• a line starting with ' ~ ' for a bullet entry in a list

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:

• using only the formatting services of this tag. For example, a message board application may want to provide basic wiki-style formatting, without any translation.
• as a workaround for database issues regarding large text. Sometimes databases treat large text differently from small text. For example in MySQL, it is not possible for a TEXT field to be assigned a UNIQUE constraint. This split between large text and small text can be a problem, since it may mean that blocks of text are treated differently simply according to their length, and workarounds for large blocks of text are needed.

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