Charset issues

FreeMarker works with "UNICODE text". Nonetheless, there is a situation where it must deal with charsets: when it has to load a template file or an unparsed text file. You can use the encoding setting to specify the charset. This setting takes effect only when FreeMarker loads a template (parsed or unparsed) with the getTemplate method of Configuration. Note that the include directive uses this method internally, so the value of the encoding setting is significant for an already loaded template if the template contains include directive call.

The getter and setter method of the encoding setting is special in the first (configuration) layer. The getter method guesses the return value based on a Locale passed as parameter; it looks up the encoding in a table that maps locales to encodings (called encoding map), and if the locale was not found there, it returns the default encoding. You can fill the encoding map with the setEncoding(Locale locale, String encoding) method of the configuration; the encoding map is initially empty. The default encoding is initially the file.encoding system property, but you can set a different default with the setDefaultEncoding method.

You can give the charset directly by overriding the encoding setting in the template layer or runtime environment layer (When you specify an encoding as the parameter of getTemplate method, you override the encoding setting in the template layer.). If you don't override it, the effective value will be what the configuration.getEncoding(Locale) method returns for the effective value of the locale setting.

Also, instead of relying on this charset guessing mechanism, you can specify the charset of the template in the template file itself, with the ftl directive.

FreeMarker does not deal with the charset of the output, since it writes the output to a Writer. However, the common practice is to use the charset of the template for the output, or using UTF-8.


Page generated: 2004-06-15 22:17:59 GMT FreeMarker Manual -- For FreeMarker 2.3