An item in a code table.
Here, a value in a code table is modeled with one required item (text), and four optional items (id, short form, long form, and order index). The id is optional, since for 'add' operations it is not yet specified. This class is offered as a convenience for implementing Code Tables. Applications are not required to use it.
Please see the example application for an example of one way of implementing code tables.
Code Tables
A code table is an informal term describing a set of related values. It resembles an enumeration. Simple examples :
- geographical divisions - countries, states or provinces
- list of accepted credit cards - Mastercard, Visa, and so on
- the account types offered by a bank - chequing, savings, and so on
Other important aspects of code tables :
- most applications use them.
- they often appear in the user interface as drop-down SELECT controls.
- they usually don't change very often.
- they may have a specific sort order, unrelated to alphabetical ordering.
- it is almost always desirable that the user-visible text attached to a code be unique (in a given code table), since the user will usually have no means to distinguish the identical items.
- it is often desirable to present the same code in different ways, according to context. For example, report listings may present codes in an abbreviated style, while a tool-tips may present a codes in a more verbose style, to explain their meaning.
- they are usually closely related to various foreign keys in the database.
Underlying Data
Code tables may be implemented in various ways, including
- database tables constructed explicitly for that purpose
- database tables that have already been constructed to hold problem domain items. That is, data from an existing table may be extracted in a shortened form, to be used as a code table.
- simple in-memory data. For example, a 1..10 rating system might use simple Integer objects created upon startup.
Avoiding Double-Escaping
This class uses {@link SafeText}, which escapes special characters. When rendering a
Code object in a JSP, some care must be taken to ensure that special characters are not mistakenly escaped
twice.
In a single language app, it's usually safe to render a Code by simply using ${code}. This calls {@link #toString()}, which returns escaped text, safe for direct rendering in a JSP.
In a multilingual app, however, the various translation tags (<w:txt>, <w:txtFlow>, <w:tooltip>) already escape special characters. So, if a translation tag encounters a Code somewhere its body, the Code must be in an unescaped form, otherwise it wil be escaped twice, which undesirable. In a multilingual app, you should usually render a Code using ${code.text.rawString}.
This asymmetry between single-language and many-language apps is somewhat displeasing, and constitutes a pitfall of using this class. If desired, you could define an alternate Code class whose toString returns a String instead of {@link SafeText}.