Fork me on GitHub

Encodings

The purpose of an encoding is to ensure the syntactical correctness of an output by escaping terms or characters with special meaning in the syntax of the output file. For example the ampersand is illegal within XML as it's used to mark an entity. It has to be replaced by &.

By handling those technical issues of the output file within the template definition the handling logic gets more reusable. And simpler to implement. This is a simple but very efficient abstraction layer.

As the encoding is inherited throughout the tree of snippets within a template a single encoding definition is sufficient for many cases. However, combination of encodings is common as well. This is why it can be overwritten as often as needed, for entire subtrees or just for single leaf nodes.

Trans-coding

The encoding support in Snippetory is based on not encoded data and already encoded containers. Containers are marked by annotations. The not encoded data will be formatted which always results in a string, when bound to a template. (Templates are encoded containers.) Now, if we try to combine to encoded containers things stay easy as long as they are encoded the same way. The contained data is copied verbatim. But if the encodings are different this difference is tried to resolve by trans-coding. Trans-coding is a 2-phase process. First the overwrites are searched for a specific Trans-coding for this specific combination of encodings. If one is found it'll do the job. If not the trans-code method of the target encoding is called. If the trans-coding is unable to resolve the difference an IncompatibleEncodingException is thrown.

The Snippetory Template Engine ships with a number of predefined Encodings:

xml
It's assumed that Snippetory is used in a modern Unicode based environment. Only a minimal escaping is done:
<-->&lt;
&-->&amp;
As XML is a compound format, i.e. it can contain other formats, almost each other will be placed within without any trans-coding. Only on plain text the normal escaping is applied.
html
HTML is derived from XML. It just converts line breaks to <br />-tags to enable transporting of simple formatting within the data bound. Be aware: this applies to data bound, not to some kind of source code like in HTML pages, so we do not break with the good practice of separating the layout of source code and it's resulting appearance.
url
Applies URL encoding to the data
string
Most C-based languages have almost the same rules. This fits at least Java and JavaScript.
html_string
In JavaScript I've sometimes data that is transported in a string before it's displayed as HTML.
plain
Plain text. You will get an IllegalEncodingExcption if you try to bind encoded data to it.
NULL
The wild card encoding. Fits to any other, any other fits to this. Sometimes it's necessary to work around the checks. But in general you should not use it.

Bernd Ebertz

Head, Founder and chief technology evangelist of
jproggy.org
Java, and all Java-based marks are trademarks or registered trademarks of Oracle.
This site is not affiliated in any way with Oracle.