SiteMesh and Charsets

Platform Defaults

The default character set for SiteMesh is iso-8859-1. SiteMesh currently assumes that the underlying platform encoding is also iso-8859-1.

This can cause some fairly insidious problems if there is a mismatch between the two! Specifically, on platforms which have a different file encoding, this should be overridden. The two known platforms which do not have iso-8859-1 encoding by default are IBM AS/400 JDK's and OSX. The work around in these cases is to specify a -Dfile.encoding=iso-8859-1 parameter as JVM argument when starting the application server.

Using Other Encodings

The iso-8859-1 encoding is sufficient for most European and Western character sets, so nothing will need to be done in this case. However, for other languages that require the full range of the UTF-8 character set, this has to be explicitly specified at a number of places, some SiteMesh specific, some app server specific/jsp specific.

Note that the examples below all refer to UTF-8. The same approach applies to any encoding other than iso-8859-1, and is not limited to UTF-8.

1. If possible, the web application should be configured to use UTF-8 as the default encoding. Orion allows this to be specific in orion-web.xml, as the default-charset attribute. Weblogic requires a context parameter named weblogic.httpd.inputCharset. See your application server documentation for more details. If the application server of choice does not allow to set the default charset for all web-apps, then every page (including the decorators) will need to specify the content-type. This is done by specifying a page header tag like this:

<%@ page contentType="text/html; charset=utf-8"%>

Note that some older versions of Orion do not respect the contentType page directive in included pages, so to be on the safe side, this directive should be specified in ALL pages, not just the top level one (one could use an include).

2. The next step is to inform the browser that the page contents are of a specific character set. This is done by specifying a meta tag in the HEAD element of the html page, like this:

<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=utf-8">

3. The final step is informing SiteMesh's decorator mechanism that it should use a specific encoding other than the default. This is done by specifying an encoding attribute to the applyDecorator tag with the name of the encoding to use.

<page:applyDecorator name="form" encoding="utf-8">
    ...
</page:applyDecorator>