Learn how to add your own format That also works for
* Syntaxes
* Encodings

Formats

The formatting queue applies a sophisticated algorithm to allow simple and powerful template definition. In a nut shell it first converts the value to a string. In this step it uses inheritance to support simple definition and consistent look.

A string refers to any kind of character data here: It could be an EncodedContainer or StringBuffer, too. If we push in a Template this phase is already done. And the encoding is preserved througout the rest of the process. And of course other conversion results may have an encoding, too.

The next step is the string adjustment. This allows ensuring a certain output length, or other string to string conversions. In this step only the attributes denoted on the actual node apply. (Syntax highlighting and links to java doc of this site are generated by the preprocessor using a format.) So it's for rather special cases, but very powerful whenever needed.

Note: A format, that provides conversion as well as decoration functionality will called twice. Just to be clear.

Once the value is formatted it might be escaped by the encoding facility. Even though escaping is a string to string conversion, too, it's very different to decoration. It doesn't address visual issues, but rather technical. In addition it's typically used for huge portions of a file. Therefore I added infrastructure to be able to use inheritance for definition.

Custom formats implement the Format interface and are registered using Format.REGISTRY. See Extending the plattfom for additional information. Using VoidFormats one can even have formats, that are executed if no value is provided at all and can even integrate other parameters in their result. default and toggle are examples how this can be used. Formats even support a sophisticated state handling if needed. Using the SimpleFormat simple things can be done easily, while real powerful stuff is possible.

Snippetory ships with some formats:

number (int / decimal)
The value of the attribute is used as pattern for java.text.DecimalFormat if its not one of the special values:
<empty String>
A number instance is used
currency
A currency instance is used
percent
A percent instance is used
JS
A number instance with locale US is used
In some case it helps to be able to generally helps handle java that do support decimal differently to those, that don't. So int only hit java types, that don't support decimals. While decimal obviously takes over Double, Float and BigDecimal. As a rule of thumb int / decimal makes a lot of sense for general cases, like setting up a TemplateContext while on a single location number is just fine.
date
The date format can convert instances of type java.util.Date and java.util.Calendar or sub types. It is registered The value of the attribute is used as pattern for java.text.DateFormat if its not one of the special values:
<empty String>
This represents the default behavior of the date format with what it will be automatically registered on every template. It depends on the locale set. If no locale is
short, medium, long, full
Will convert to a date representation according to the key word
_short, _medium, _long, _full
With a preceding underline it will convert to a time representation according to the key word
<date_key_word><time_key_word>
You can use a date key word immediately followed by a time key word to get a date time value: full_short, medium_medium, ...
sql, _sql, sql_sql
The sql values follow the same principle, but must not be combined with length based key words.
Note: sql refers to java.sql package rather than the ISO standard. I.e. the format looks like 2011-05-06 12:43:56
JS, _JS, JS_JS
This will generate JavaScript code that creates a new Date-object.
 US Englishsimplified ChineseGerman
longOctober 15, 20112011年10月15日15. Oktober 2011
short_full10/15/11 1:05:15 AM CEST11-10-15 上午01时05分15秒 CEST15.10.11 01:05 Uhr MESZ
_medium1:05:15 AM1:05:1501:05:15
sql2011-10-152011-10-152011-10-15
JS_JSnew Date(2011, 10, 15, 01, 05, 15)new Date(2011, 10, 15, 01, 05, 15)new Date(2011, 10, 15, 01, 05, 15)
pad
Ensures a minimum length.
Via the pad attribute it's possible to define a minimum length of an output string. The length will be enforced by appending additional spaces. In addition there are the the sub-attributes pad.align to determine whether the value should be aligned right or left and pad.fill to overwrite the fill character.
Attributes
value
InputOutputEffect
pad='2'xxxxxxNothing happens
pad="3" pad.align="right"xx xxOne space prepended
pad="7" pad.fill=". "xxxx. . . .fill characters are appended to achieve the required length
crop
Ensures a maximum length.
This is defined by an integer number immediately followed by a abbreviation marker of arbitrary length. This means that the abbreviation marker can't start with a number character, but in most cases either 3 dots or nothing might be used.
Attribute valueInputOutputEffect
crop="35" crop.mark="..."This is a long text (35 characters)This is a long text (35 characters)Nothing happens
crop="40"This is a long text (35 characters)This is a long text (35 characters)Nothing happens
crop="20" crop.mark="..."This is a long text (35 characters)This is a long te...Only the first 17 characters and
three dots are appended
crop="20"This is a long text (35 characters)This is a long text The first 20 characters are used
default
Declares how a value is rendered if no value is set. The value will not be escaped but it's formatted by string formatters. Without additional definition a location mark will be rendered as its markup while a region will be rendered by an empty string.
null
A null will mostly be handled like an empty string in Snippetory. At least for formatting. This format allows to override this with a fixed value.
toggle
Toggles over a semicolon separated list of values.
The toggling may be triggered simply by rendering the value similar to a default value or may be controlled by explicitly setting a number. In this case a modulo operation is applied to that number with the number of available values as second argument and the value is selected according to the result.
case
The case format converts the character case of some input data as specified by the attribute value.
This format will apply to data that implements either java.lang.CharSequenz or EncodedData.
upper
Converts the entire text to upper case
lower
Converts the entire text to lower case
firstUpper
This will only capatilize the first character of the input data and leaves the rest unchanged. If this is not a letter or has no upper case, nothing will happen.
camelizeUpper
Converts the given term to camel case.
The first character will be in upper case. Supported word bounderies are underline `_`and dash `-`.
camelizeLower
Converts the given term to camel case.
The first character will be in lower case. Supported word bounderies are underline `_`and dash `-`.
Bernd Ebertz Head, Founder and chief technology evangelist of
jproggy.org