<@page title="Settings" keywords="settings, options, engine"> <@sect title="Things you must know about settings">

The basic definition of the "setting" term is <@a href="overview.html#settings">here... <@sect title="The common characteristics of settings">

The characteristics of a setting can be described with these attributes:

Notes:

<@sect title="The merging of setting values">

Setting values can be specified in multiple layers. For example, it is possible that a setting is specified in the configuration file, and then again with a command-line argument of the command-line tool.

Setting layers has a priority order, for example, the setting layer defined by the command-line arguments has higher priority than the setting layer defined by the configuration file. When the value of the same setting is specified in two layers, then the value that comes from the layer with higher priority overrides the setting value comes from the lower layer. If the type of the setting is not map or sequence, then this simply means that the value from the higher layer will be used, and the other value will be totally hidden. But if the setting type is sequence or hash, then the sequence values will be merged:

Logically, the rules described in this section can be applied for more than two layers of settings as well.

<@sect title="Directories"> <@setting name="sourceRoot" type="string (path)" default="" merging=false clShort="S" antAltAtt="srcdir" /> <@setting name="outputRoot" type="string (path)" default="" merging=false clShort="O" antAltAtt="destdir" /> <@setting name="dataRoot" type="string (path)" default="ex:the value of <@s\gsourceRoot <@setting name="alwaysCreateDirectories" type="boolean" default="false" merging=false antAltAtt="alwaysCreateDirs" />

In the typical use case FMPP processes all files in the directory specified by <@s>sourceRoot, and writes the result into the directory specified by the <@s>outputRoot directory. These two root directories serve as the root directory of two virtual file systems that store the source files and the output files respectively. This means that all files that FMPP processes must be inside the source root directory (except data files - see later), and it is guaranteed that all output files will be inside the output root directory (as far as you do not by-pass FMPP intentionally with custom extensions). You can't leave the roots by moving upward with <@c>..-s. Also, when you refer to files or directories in the templates as the parameters of predefined directives, absolute paths like <@c>/example.html are interpreted relatively to the source or output root directories (except if the parameter deals with data files - see later).

Note that both the source root and the output root must be defined before starting a processing session (but a front-end may assings a default value to them). Also, if you use the <@s>outputFile setting these two settings always have a default value.

The directory specified by <@s>dataRoot is interesting for <@a href="dataloader.html">data loaders only. If a data loader gets a relative path, then it should interpret that relatively to the data root directory. If it gets an absolute path, it should interpret that as is. As you can see from this, data root directory does not try to mimic a file system root as the other two root directories. Data loaders can reach files outside the data root directory.

By default, the data root is the same as the source root. This encourages the practice where you store the data files in the, say, <@c>data subdirectory of the source root, and then mark that directory with a <@c>ignoredir.fmpp file (file content is irrelevant), so FMPP will not process the content of the directory. Thus, you keep all input together: data sources, templates and static files (as images).

By default, no empty subdirectories will be created in the output root directory. More precisely, directories are created only on demand, when actual output files have to be created in them, hence normally you don't have empty directories in the output. However, this behavior can be changed with <@c>alwaysCreateDirectories; with that setting set to <@c>true, each source directory will produce a corresponding output directory (unless it contains an <@c>ignoredir.fmpp file). Also, if a source directory contains a file named <@c>createdir.fmpp (file content is irrelevant) then the corresponding output directory will be created, regardless of the <@c>alwaysCreateDirectories setting (unless, again, <@c>ignoredir.fmpp is also present)

It is possible to tell FMPP to process only certain files and directories of the source root, not all of them; see the <@s>sources setting.

<@sect title="Source and output files"> <@setting name="sources" type="sequence (of paths)" default="" merging=true /> <@setting name="outputFile" type="string (path)" default="" clShort="o" merging=false />

Be default FMPP processes all files in the source root directory. But if you use the <@s>sources setting, FMPP will process only the files and/or directories listed there. Relative paths in this setting are resolved relatively to the source root directory, not to the configuration base (unless you use <@s>outputFile setting).

If you use the <@s>outputFile setting, then FMPP switches to single file mode. In this mode, it will process only 1 files, and store its output in the file specified by the <@s>outputFile setting. You must use <@s>sources, and it must list exactly 1 file. If a relative path is given in the <@s>sources, it is resolved relatively to configuration base, not to the source root. If you didn't specified <@s>outputRoot or <@s>sourceRoot, it will default to the parent directory of the output file or source file respectively.

The user interface of front-ends tend to require you to use some special way to specify the value <@s>sources setting. Please read the <@a href="frontends.html">documentation of the front-end you use about this. Note that configuration files are front-end independent, so there you always simply set <@s>sources be assigning value to the <@c>sources key.

<@sect title="Text encoding issues"> <@setting name="sourceEncoding" type="string" default="ISO-8859-1" clShort="E" merging=false /> <@setting name="outputEncoding" type="string" default="source" merging=false /> <@setting name="urlEscapingCharset" type="string" default="output" merging=false />

People use different encodings to store text in binary form, often referred as charsets. Examples of charsets are: <@c>ISO-8859-1, <@c>ISO-8859-2, <@c>CP852, <@c>CP1250, <@c>Shift_JIS, <@c>UTF-8. FMPP internally uses UNICODE everywhere, but when it has to read a text file or write a text file, it must deal with charsets to correctly decode/encode the text. To read text files, FMPP uses the source encoding. This is be default ISO-8859-1. Also, a FreeMarker template has the ability to tell its own encoding with <@c><#ftl encoding="<@r>something">, and this overrides the source encoding for the individual template file.

To write text files, FMPP uses the output encoding. This is be default holds the special value <@c>source, which means that FMPP will use the encoding of the source text file (template file). If you change the value of the setting to a concrete charset, such as UTF-8, then text files will be always written with that encoding. However, templates can set the encoding of the output file with <@c><@pp.setOutputEncoding encoding="<@r>something"/>, and this overrides the encoding dictated by the settings.

The <@s>urlEscapingCharset specifes the name of the charset (encoding) used for URL escaping. It defaults to <@c>output, which means that the output encoding will be used for URL escaping. URL escaping happens for example when you use FreeMarker's <@c>url built-in (e.g. <@c><a href="foo.cgi?id=<#noparse>${id?url}">) or the <@a href="pphash.html#key_urlPathEnc"><@c>pp.urlPathEnc method.

All of these settings understands the special charset <@c>host, which means the default encoding of the host operating system.

The set of supported charsets (and their preciese names) depends on the Java platfrom implementation you run FMPP on.

<@sect title="Processing mode choosing" anchor="processingMode"> <@setting name="modes" type="sequence (of function calls)" default="ex:empty" clShort="M" merging=true /> <@setting name="ignoreCvsFiles" type="boolean" default="true" merging=false /> <@setting name="ignoreSvnFiles" type="boolean" default="true" merging=false /> <@setting name="ignoreTemporaryFiles" type="boolean" default="true" merging=false />

When FMPP has to process a file, it has to decide how to process that. That is, it has to choose a "processing mode" for the file. The processing mode can be one of:

First, if the <@s>ignoreCvsFiles setting is true, and the file name is <@c>.cvsignore or matches <@c>.#?*, or the file is inside a sub-directory of the source root that is called <@c>CVS, then it chooses the "ignore" processing mode. Also, if the <@s>ignoreSvnFiles setting is true, and the file is inside a sub-directory of the source root that is called <@c>.svn, then it chooses the "ignore" processing mode (note that it doesn't ignore conflict files, i.e., <@c>*.mine and <@c>*.r<@r>number). Also, if <@s>ignoreTemporaryFiles setting is true, and the file name matches <@c>?*~ or <@c>~?* or <@c>#?*# or <@c>%?*% or <@c>_.?*, or the extension (the part after the last dot in the file name) after converting to lowercase matches <@c>bak or <@c>~* or <@c>*~ then it chooses the "ignore" processing mode. Note that the FMPP Ant task always sets these settings to <@c>false, so it does not interfere with the <@c>defaultExcludes parameter of Ant.

Then, the processing mode is chosen with a sequence of <@a href="pathpattern.html">path patterns, which is defined by the <@s>modes setting. The first path pattern in the sequence that matches the <@a href="overview.html#virtualPath">virtual path of the file, chooses the processing mode. If no matching path were found, then FMPP chooses the processing mode automatically:

The <@s>modes setting is a list of TDD functions, where the function name is either <@c>execute, <@c>copy, <@c>renderXml, or <@c>ignore. The arguments to the functions are one or more path patterns of virtual paths in the source file system. For example this (in a configuration file):

<@prg> modes: [ ignore(**/tmp/) copy(foo/**/*.html, foo/**/*.htm) execute(**/*.html, **/*.htm, **/*.xhtml) copy(**/*) ]

will produce this processing mode chooser sequence:

Path patternProcessing mode
<@c>**/tmp/ignore
<@c>foo/**/*.htmlcopy
<@c>foo/**/*.htmcopy
<@c>**/*.htmlexecute
<@c>**/*.htmexecute
<@c>**/*.xhtmlexecute
<@c>**/*copy

Note that processing modes are only applicable to files, not to directories. Say, you can't tell FMPP to ignore a directory, but to ignore all files in the directory (as <@c>**/tmp/ above). The end result will be that the directory will not be created, as it contains no output file.

<@sect title="Header and footer choosing"> <@setting name="borders" type="sequence (of function calls)" default="ex:empty" merging=true />

With these settings you can insert a header before templates, and insert a footer after templates (templates = files processed in "execute" processing mode). The insertion of header and footer happens only in the memory of the computer, and does not modify the source files. This can be used to add common headers and footers to the templates without actually typing them again and again. Also, you can change the header/footer of many templates at once.

The intent of headers and footers is not to show something at the top and bottom of pages. Rather it is to insert FTL directives that import or include commonly used macros, or to place the page inside a block, as <@c><@myLayout><@r>...</myLayout>. For concrete examples please see <@example 'border' />.

<@note>Unfortunately the inserted header displace the error locations (column, row) in the error messages (I can't fix it in FMPP; FreeMarker improvements are needed to address this). However, if the header doesn't contain line-break, then this unwanted effect is limited to the first line of the template. So it's strongly recommended to not use line-break in headers.

Footers and headers are chosen with similar mechanism to processing modes (see <@s>modes). There are two independent sequence of path-pattern to text entry mappings (so called "choosers"), one for choosing headers, and one for choosing footers. When FMPP loads a template file, it checks if the <@a href="overview.html#virtualPath">virtual path of the file matches to an entry in the header chooser sequence, and if so, it uses the header specified in the first such entry. Also, it does the same with the sequence of footers choosers, to choose a footer.

There is a single setting to build both sequences at once: <@s>borders. You give a sequence of <@c>header, <@c> footer and <@c>border functions in it. The first argument to <@c>header and <@c> footer functions is the text of header and footer respectively, and the further arguments are the path patterns of virtual paths in the source file system. If you omit the path patterns, that's the same as if you give <@c>** (i.e. match all files). <@c>border is convenience function: <@c>border(<@r>a, <@r>b, <@r>paths...) is equivalent with <@c>header(<@r>a, <@r>paths...), footer(<@r>b, <@r>paths...). Example:

<@prg><#noparse> header("<#import '/lib/css.ftl' as css>", **/*.css) border("<#import '/lib/page.ftl' as p><@p.myLayout>", "", **/*.html, **/*.htm)

This build these sequences:

Only the first matching entry of the sequence is used for a file, the later entries are ignored. But sometimes you want to choose multiple headers/footers for the same file. In that case, you can define multiple independent sequences, so said, layers. Layers are separated with <@c>layer(). For example, modify the above example, so it imports <@c>/lib/common.ftl at the top for all files, without disabling the other headers/footers:

<@prg><#noparse> # The 1st (implicit) layer starts here header("<#import '/lib/common.ftl' as c>", **/*.css, **/*.html, **/*.htm), layer() # The 2nd layer starts here header("<#import '/lib/css.ftl' as css>", **/*.css), border("<#import '/lib/page.ftl' as p><@p.myLayout>", "", **/*.html, **/*.htm)

Here we have two independent header chooser sequences, so both CSS and HTLM files will import <@c>lib/common.ftl, and additionally CSS files will import <@c>lib/css.ftl, and HTML files will import <@c>lib/page.ftl have the <@c>@p.myLayout block. You can have any number of layers.

A header chosen from an earlier layer will be used earlier in the template file than headers chosen from later layers. A footer chosen from an earlier layer will be used later in the template file than footers chosen from later layers. For example:

<@prg> borders: [ border('L1(', ')L1') layer() border('L2{', '}L2') layer() border('L3[', ']L3') ]

If the content of a template file is <@c>content, its output will be:

<@prg> L1(L2{L3[content]L3}L2)L1 <@sect title="Output file name deduction"> <@setting name="removeExtensions" type="sequence (of strings)" default="ex:empty" clShort="R" merging=true /> <@setting name="removePostfixes" type="sequence (of strings)" default="ex:empty" merging=true /> <@setting name="replaceExtensions" type="sequence (of strings)" default="ex:empty" merging=true /> <@setting name="removeFreemarkerExtensions" type="boolean" default={'0.9.15': 'false', '0.9.15': 'true'} merging=false since='0.9.16' />

Initially the name of the output file is the same as the name of the source file. These settings allow you to change the output filename somewhat, by removing and replacing parts of it.

The precise meaning of the settings:

  1. <@s>removeExtensions: If the source file name ends with an exension in this sequence, then it will be removed from the output file name. For example, if <@c>ftl is in the sequence (note that there is no dot before the <@c>ftl), then the output file for <@c>example.html.ftl will be <@c>example.html. The extension to remove can contain dots (as <@c>tar.gz).
  2. <@s>removePostfixes: If the source file name before the first dot ends with a string in this sequence, then it will be removed from the output file name. For example, if <@c>_t is in the sequence, then the output file for <@c>example_t.html will be <@c>example.html. If the file name does not contains dot, then it still works: <@c>example_t will become to <@c>example.
  3. <@s>replaceExtensions: This sequence is used to replace the file extensions with another extensions. For example, if the sequence is this:
    <@c>ftlh, html, ftlx, xml
    then the <@c>ftlh extension will be replaced with <@c>html (i.e. the output file name for source file <@c>foo.ftlh will be <@c>foo.html), and the <@c>ftlx extension will be replaced with <@c>xml. The 1st, 3rd, 5th, etc. sequence elements are the extensions to replace, and the 2nd, 4th, 6th, etc. sequence elements are the new extensions (so <@c>html extension will not be replaced with <@c>ftlx). Also, only one extension replacement will occur for the same file name, so in the case of
    <@c>x, y, y, z
    <@c>x will not become to <@c>z.
  4. <@s>removeFreemarkerExtensions: When set to <@c>true, and the file extension is one of the standard FreeMarker template file extensions (<@c>ftl, <@c>ftlh, and <@c>ftlx) then the file extension is removed from the output file name. The typical usage is that you have file names like <@c>foo.txt.ftl or <@c>bar.html.ftlh, and then the output file names will be <@c>foo.txt and <@c>bar.html respectively. You could achieve the same with <@s>removeExtensions too, but this is more convenient, and most importantly, if <@s>recommendedDefaults is set to at least 0.9.16, this defaults to <@c>true.

These settings are applied in the order as they are listed above. Each setting is applied only once on the same file name.

Note that output file name deduction only applies to files, not to directories.

<@sect title="Skipping unchanged files"> <@setting name="skipUnchanged" type='string' default="none" clShort="-U" merging=false />

This setting specifies that the processing of which source files can be skipped, if the source file was not modified after the last modification time of the output file. The value of setting can be one of:

If the output does not exist, the source file will be always processed.

This feature will not work for templates that rename or drop the original output file during the template execution, because in the next processing session FMPP will believe that the output files for those files are missing, and thus it will process them again.

<@sect title="Turn choosing"> <@setting name="turns" type="sequence (of function calls)" default="ex:empty sequence" merging=true />

When FMPP has to process multiple files in the same processing session (for example, when you process a whole directory), then the order in which the files will be processed, is undefined. This is a problem in certain use cases, where it must be ensured that certain files will be processed later than others. For example, if a page contains the alphabetic index of keywords occur in other pages, then that page must be processed for the last, because the information is collected during the processing of the other pages. This is what turns are about: to guarantee the order of the processing of files.

The processing session is divided up into, so called, turns. Turns are identified with the turn number, which is simply the order of the turn. The session starts with turn 1, then comes turn 2, and then comes turn 3, etc. FMPP puts all files that will be processed into exactly one of the turns, based on the turn chooser sequence.

The turn chooser sequence is a sequence of path-pattern -> turn-number pairs. For each source file, the <@a href="overview.html#virtualPath">virtual path of the source file is compared with these <@a href="pathpattern.html">path patterns, and the first pattern of the sequence that matches determines the turn in which the file will be processed. If there is no matching pattern in the sequence for the file, then the file will be processed in turn 1.

For example, if <@c>config.fmpp contains this line: <@prg> turns: [turn(3, main_idx.html), turn(2, **/*_idx.html)]

then all files where the file name ends with <@c>_idx.html will be processed in turn 2, except <@c>main_idx.html, which will be processed in turn 3. All other files will be processed in turn 1.

There is no upper limit of the turn number (except a technically limit, somewhere near 2 thousand million). Simply, the last turn will be the turn with the highest number, which is mentioned in the turn chooser sequence, or 1, if the sequence is empty. The first turn is always the turn 1. It is not a problem if a turn contains no file processing.

See <@example 'session' /> for a working example, or the FMPP task call in the <@c>build.xml.

<@sect title="Data model building" anchor="data"> <@setting name="data" type="hash" default="" clShort="D" merging=true /> <@setting name="localData" type="sequence" default=""merging=true /> <@setting name="templateData" type="string (Java class name)" default="" merging=false deprecated="Use <@s\glocalData

As you may <@fma href="dgui_quickstart_basics.html">know from the FreeMarker manual, FreeMarker generates the output by merging a template with a data model, and the data model is a hash variable, the root hash. With FMPP terminology, it is usually just referred as "the data". In FMPP, the population of the root hash happens in two places:

  1. Session level data: Once per processing session, at the very beginning of it (before any file processing is stared), the root hash is filled with variables based on the <@s>data setting. This is what happened in the <@a href="qtour.html">Quick Tour, when we have loaded the colors and the table of birds. These variables will be constant during the whole session, and visible for all templates. They must not be modified while the processing session is executing, even if you find a technical way to do that. Note that <@fma href='dgui_misc_var.html'>FreeMarker uses multiple variable layers, so you doesn't modify these variables with <@c><#assign <@r>...> or <@c><#global <@r>...>, just hide them for the time of the template execution, which is OK (the effect will not be visible for the files processed later).
  2. Local data (file processing level data): For each processed file, just before FMPP starts to proccess the file, some extra variables are put into the root hash that are specific for that file. These variables will be present in the root hash only while that file is being processed (hence "local data"), so the next file processing will start with the original session level data in the root hash again. The local data is built in three steps, in this order:
    1. Variables created based on the <@s>localData setting. (See details <@a href="#localData">later...)
    2. Deprecated: User written Java object of class specified by <@s>templateData adds an arbitrary set of variables. This feature is deprecated and will be removed later.
    3. The FMPP core adds the <@a href="pphash.html"><@c>pp hash.
    Variable added later will overwrite the variable of similar name added earlier. Also, variable that is local data will hide (seemingly overwrite) the variable of similar name that is session level data.

From the view point of FreeMarker templates, variables that are part of the session level data and the part of the local data are not different. They are equal parts of the data model.

<@sect title="ex:More about the <@s\gdata

When you use <@a href="tdd.html">TDD syntax for defining the hash for <@s>data, TDD function calls are interpreted as <@a href="dataloader.html">data loader invocations. For reminder, here is the relevant part of <@c>config.fmpp from <@example path="qtour_step4" />:

<@prg> data: { tdd(data/style.tdd) birds: csv(data/birds.csv) }

TDD syntax makes it possible to enter values directly as well, without using data loaders. For example, you could directly enter the "birds" table with TDD (altoguh it is not too convenient): <@prg> data: { tdd(data/style.tdd) birds: [ { name: arctic-tern description: "Flies very long distances all years." favoriteFood: sardine } { name: house-sparrow description: "Don't you say you don't know it..." favoriteFood: sunflower } { name: sakeret description: "Great hunter of the sky." favoriteFood: pigeon } ] } <#-- more about data --> <@sect title="ex:More about the <@s\glocalData

Let's start with a simple example. We have a variable <@c>bgColor in the session level data with value <@c>green. We want to override this with value <@c>yellow for the source files that are in directory <@c>sub (or in its subdirectories, ...etc.):

<@prg> data: { bgColor: green } localData: [ case(sub/**, {bgColor: yellow}) ]

Complicate it a bit... now set the <@c>bgColor if the file is in directory <@c>sub or <@c>sub2:

<@prg> localData: [ case(sub/**, sub2/**, {bgColor: yellow}) ]

Now do the same as earlier, except for files that are in directory <@c>sub/sky, where the <@c>bgColor is always <@c>blue:

<@prg> localData: [ case(sub/sky/**, {bgColor: blue}) case(sub/**, sub2/**, {bgColor: yellow}) ]

The rule is that the first <@c>case(<@r>...) where one of the path patterns matches the source file path will specify the local data (specified as the last argument), and the further <@c>case(<@r>...)-s are ignored. There can be any number of <@c>case(<@r>...)-s listed (note that <@c>localData is a sequence), and a <@c>case(<@r>...) can have any number of path patterns (but 0).

Tricky example: do the same as earlier, but don't override the color if the file name starts with <@c>foo:

<@prg> localData: [ case(**/foo*, {}) case(sub/sky/**, {bgColor: blue}) case(sub/**, sub2/**, {bgColor: yellow}) ]

Assume that you want to set variable <@c>author to <@c>Joe for all files where the file name contains <@c>_j., and to <@c>Amy for all files contains <@c>_a.. But, you want to do this independently of setting <@c>bgColor. In this case you have to use layers:

<@prg> localData: [ # The 1st (implicit) layer starts here case(**/foo*, {}) case(sub/sky/**, {bgColor: blue}) case(sub/**, sub2/**, {bgColor: yellow}) layer() # The 2nd layer starts here case(**/*_j.*, {author: Joe}) case(**/*_a.*, {author: Amy}) ]

The rule is that layers are separated with a <@c>layer() function call. You can have any number of layers. The <@c>case(<@r>...)-list of each layer will be searched for the first match independently. If more layers put the same variable into the data model, the higher layer (earlier layer) wins (hence "layers"). Layers are calculated starting with the lowest layer. Empty layers are allowed (can be practical when you are using setting merging).

The last parameter of the case can be:

Here's an example of using of the <@c>bsh function: It will execute a BeanShell script file for each HTML to add local data. For example, the script file for source file <@c>foo/bar.html should be <@c>foo/bar.html.bsh. If there is no script for the HTML file, it will not consider that as an error.

<@prg> modes: ignore(**/*.bsh) localData: [ case(**/*.htm, **/*.html, bsh({ignoreMissing})) ]

A possible <@c>.bsh file, that adds local variables <@c>x and <@c>y:

<@prg> res = new HashMap(); res.put("x", "Just for test: " + templateEnvironment.getData("author")); res.put("y", "Blah..."); return res;

For a working example see <@example 'local_data' />.

<#-- more about localData --> <@sect title="Auto-escaping"> <@setting name="outputFormat" type="string" default='"undefined"' merging=false since="0.9.16" /> <@setting name="outputFormatsByPath" type="sequence (of case function calls)" default="[]" merging=true since="0.9.16" /> <@setting name="mapCommonExtensionsToOutputFormats" type="boolean" default={'0.9.15': 'false', '0.9.16': 'true'} merging=false since="0.9.16" />

Auto-escaping means that in values printed with interpolations (with <@c>${'$'}{<@r>expression}, not with <@c><@directive />, nor with static text), the parts that have special meaning in the output format (like <@c>& and <@c>< have if the output format is HTML) are replaced with an escaped form (with <@c>&amp;, <@c>&lt; in this case). What patterns will be escaped and how depends on the output format, like <@c>HTML, <@c>XML, <@c>RTF, etc.

Output formats and auto-escaping is a FreeMarker template language feature. See the <@fma href="dgui_misc_autoescaping.html">related section in the FreeMarker documentation for more details.

In FMPP, the output format of a template is decided as follows, in this order:

  1. If the file extension is <@c>ftlh or <@c>ftlx, and the <@s>freemarkerIncompatibleImprovements setting is at least 2.3.24 (if <@s>recommendedDefaults is at least 0.9.16 then that's true by default), then template files with <@c>ftlh file extension will have <@c>HTML output format, and template files with <@c>ftlx file extension will have <@c>XML output format. This is enforced by FreeMarker, so the FMPP settings below can't override it. (Note that these file extensions can be removed/replaced in the output file names using the <@s>removeExtensions/<@s>replaceExtensions settings.)
  2. Otherwise, if an entry in <@s>outputFormatsByPath matches the template file path (see later), then the output format specified there is used.
  3. Otherwise, if <@s>mapCommonExtensionsToOutputFormats is <@c>true (if <@s>recommendedDefaults is at least 0.9.16 then that's true by default), and the template file extension (the part of the file name after the last dot, always case-insensitive) is one of the common extensions (see them later), then the output format associated with that extension is used. Furthermore, if the file name ends with <@c>.ftl (always case-insensitive), then we ignore that ending, so for example for <@c>example.rtf.ftl we check if <@c>rtf is a common extension, not if <@c>ftl is one.
  4. Otherwise, if the <@s>outputFormat setting is set, then the output format specified there is used.
  5. Otherwise, the output format will be the one called <@c>"undefined", which doesn't do automatic escaping.

Example:

<@prg> outputFormat: HTML outputFormatsByPath: [ case(legacy/, undefined) case(**/*.xfoo, **/*.xbar, XML) ]

With this all templates inside the <@c>legacy directory will have <@c>undefined output format, and template files that have <@c>xfoo or <@c>xbar file extension will have <@c>XML output format. The output format is decided by the first matching <@c>case(...), so for example <@c>legacy/example.xfoo will have <@c>undefined output format, despite that it matches <@c>**/*.xfoo. If there's no match in <@s>outputFormatsByPath, and we assume for simplicity that <@s>mapCommonExtensionsToOutputFormats is <@c>false, then the output format will be <@c>HTML according the <@s>outputFormat setting.

The <@c>case function in <@s>outputFormatsByPath has 2 or more arguments. The last argument is the name of the output format. The arguments before that are the <@a href="pathpattern.html">path patterns that will be matched against the <@a href="overview.html#virtualPath">virtual path of the template, in logical or relation.

The valid output format names can be found in the <@fma href="dgui_misc_autoescaping.html">FreeMarker documentation.

The common extension used by <@s>mapCommonExtensionsToOutputFormats are the following (in this format: Associated output format: case-insensitive file extensions):

<@sect title="Locale"> <@setting name="locale" type="string (locale)" default="en_US" clShort="A" merging=false />

Set the locale (language, country) used in templates. It has significance because different countries write numbers differently, sort text differently, etc.

The value is a string which consist of a language code (lowercase two-letter ISO-639 code) plus optional county code (uppercase two-letter ISO-3166 code) separated from the language code with underscore, and if we have specified the country then an optional variant code (not standardized) separated from the country with underscore. Examples of valid values: <@c>en, <@c>en_US, <@c>en_US_MAC. FreeMarker will try to use the most specific available locale, so if you specify <@c>en_US_MAC but that is not known, then it will try <@c>en_US, and then <@c>en, and then the default locale of the computer.

Also, the special value <@c>host can be used to ask FMPP to use the default locale of the host operating system. However, for most applications it is not recommended to depend on the host locale, since then the output will depend on where you run the generation (and not on what people will use the output).

If you don't know what your locale string would be, use the <@c>--print-locales option of the command-line tool. Note that unfortunately, the codes printed here are far the superset of locales that Sun's Java platform implementation actually correctly handles.

Note that the initial value of the setting is <@c>en_US, because it is the locale that formats things similarly as a programmer would expect.

<@sect title="Number format"> <@setting name="numberFormat" type="string" default="0.############" merging=false />

This specifies the default format of numbers when FreeMarker has to convert numbers to strings. For example, if you change this setting to <@c>0.00 then:

<@prg><#noparse>${1}, ${1.1}, ${1.245}

will print (if the locale setting is <@c>en_US):

<@prg>1.00, 1.10, 1.25

Note that you can override the effect of this setting in the templates with <@c><#setting number_format="<@r>something">, also you can override this for each interpolations with <@c>?string("<@r>something").

The syntax and semantic of the format string is as <@c>java.text.DecimalFormat defines it. For convenience I quote a part from the documentation of <@c>java.text.DecimalFormat:

Pattern Syntax

 pattern     := pos_pattern{';' neg_pattern}
 pos_pattern := {prefix}number{suffix}
 neg_pattern := {prefix}number{suffix}
 number      := integer{'.' fraction}{exponent}
 prefix      := '\u0000'..'\uFFFD' - special_characters
 suffix      := '\u0000'..'\uFFFD' - special_characters
 integer     := min_int | '#' | '#' integer | '#' ',' integer
 min_int     := '0' | '0' min_int | '0' ',' min_int
 fraction    := '0'* '#'*
 exponent    := 'E' '0' '0'*
  
 Notation:
   X*       0 or more instances of X
   { X }    0 or 1 instances of X
   X | Y    either X or Y
   X..Y     any character from X up to Y, inclusive
   S - T    characters in S, except those in T
 

Special Pattern Characters

Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. They must be quoted, unless noted otherwise, if they are to appear in the prefix or suffix as literals.

The characters listed here are used in non-localized patterns. Localized patterns use the corresponding characters taken from this formatter's DecimalFormatSymbols object instead, and these characters lose their special status. Two exceptions are the currency sign and quote, which are not localized.

SymbolLocationLocalized?Meaning
0NumberYDigit
#NumberYDigit, zero shows as absent
.NumberYDecimal separator or monetary decimal separator
-NumberYMinus sign
,NumberYGrouping separator
ENumberY Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
;Subpattern boundaryY Separates positive and negative subpatterns
%Prefix or suffixYMultiply by 100 and show as percentage
\u2030Prefix or suffixY Multiply by 1000 and show as per mille
¤
(\u00A4)
Prefix or suffixN Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator.
'Prefix or suffixN Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".
<@sect title="Boolean format"> <@setting name="booleanFormat" type="string" default="true,false" merging=false since='0.9.15' />

This setting specifies how boolean values will be converted to text or from text inside FreeMarker templates (not in <@a href="dataloader.html">data loaders). However, confusingly enough, when this is <@c>true,false (the default) then something like <@c>${'$'}{myBoolean} is an error, because FreeMarker denies using <@c>"true,false" for implicit boolean to text conversion. So to utilize this setting, set it to something different, like <@c>Y,N, and then it will work as expected. Where you want to print <@c>true/<@c>false, write <@c>${'$'}{myBoolean?c} (note the <@c>?c), which will always print <@c>true/<@c>false, regardless of the <@s>booleanFormat setting.

This setting directly correspond to the FreeMarker setting with similar name, so find the full documentation there: <@fma "ref_directive_setting.html#topic_date_format_settings">FreeMarker settings.

Example: <@c>"Yes,No" means that <@c>${'$'}{myBoolean} will print <@c>Yes or <@c>No. <@sect title="Date/time format"> <@setting name="dateFormat" type="string" default="" merging=false /> <@setting name="timeFormat" type="string" default="" merging=false /> <@setting name="datetimeFormat" type="string" default="" merging=false /> <@setting name="timeZone" type="string" default="" merging=false /> <@setting name="sqlDateAndTimeTimeZone" type="string" default="" merging=false since='0.9.15' />

These settings specify how date/time/date-time values will be converted to text or from text inside FreeMarker templates (not in <@a href="dataloader.html">data loaders, unless said otherwise).

These settings directly correspond to the FreeMarker settings with similar name, so find their full documentation there: <@fma "ref_directive_setting.html#topic_date_format_settings">FreeMarker settings.

Examples of <@s>datetimeFormat-s: <@c>"dd.MM.yyyy HH:mm:ss" (where <@c>HH means 0-23 hours) or <@c>"MM/dd/yyyy hh:mm:ss a" (where <@c>a means AM or PM, if the current language is English), <@c>"iso" (ISO 8601:2004 format), <@c>"xs" (XML Schema format).

Examples of <@s>timeZone-s: <@c>"GMT", <@c>"GMT+2", <@c>"GMT-1:30", <@c>"CET", <@c>"PST", <@c>"America/Los_Angeles", <@c>"JVM default"

When a format setting isn't set, the default format of the current locale (country) will be used, which are specified by the Java installation you run FMPP on. If the <@s>timeZone isn't set, the time zone of the host computer will be used (specified by the Operating System).

<@sect title="Handling errors"> <@setting name="stopOnError" type="boolean" default="true" clShort="s, c" merging=false />

Be default when FMPP encounters problem during the processing of a source file, it terminates the whole processing session with the error. It can be annoying if you have many bad files, because you have to restart the whole session and wait until the session reaches another bungled template (or other kind of problematic source file), again and again, until you have fixed all of them. If you change this setting to <@c>false, FMPP will not stop on the errors, just skips the problematic source file and continues the processing session with the next source file. You should use <@s>logFile together in this case, so you can later digest all problems occured during the processing session.

Note that this settings will only suppress errors that occur during the processing of source files. It will not suppress errors like, for example, bad data files (unless it's loaded in a template with <@c>pp.data) or invalid setting values.

<@sect title="Expert mode"> <@setting name="expert" type="boolean" default="false" clShort="x" merging=false />

This setting is to enable suspicious situations, when the engine or the tool suspects that you have miss-configured something, and thus an accidental data loss can happen. It is recommended to leave this setting false, until it actually blocks something that you want to do.

Please note that overwriting a file in general is a normal situation for FMPP; no expert mode required to do that.

<@sect title="Case sensitive path comparison"> <@setting name="caseSensitive" type="boolean" default="false" merging=false />

This setting tells if FMPP should differentiate upper- and lower-case letters when it compares paths for equality, or when it matches paths to path patterns. Regardless of this setting, FMPP always tries to keep the case of file names (i.e. the output of <@c>Foo.txt will be <@c>Foo.txt, and not <@c>foo.txt or <@c>FOO.TXT), as far as the host operating system does not prevent this.

<@sect title="Logging" anchor="logging"> <@setting name="logFile" type="string (path)" default="" clShort="L" merging=false /> <@setting name="appendLogFile" type="boolean" default="" merging=false />

If these settings are supported or not, depends on the front-end you use. If a setting is not supported, the front-end must silently ignore it.

If the <@s>logFile setting is set, the front-end should record information about the processing session into the file, such as the warning messages and errors occurred.

If <@s>appendLogFile is <@c>false, then already existing log file (possibly left from the previous processing session) is deleted and restarted. This is the recommended default behavior, however a front-end may chooses something different. If <@s>appendLogFile is <@c>true, then old log file should be continued.

Please read the documentation of <@a href="frontends.html">the front-end you use for the precise behavior of these settings.

<@sect title="Showing the progress and other messages"> <@setting name="quiet" type="string" default="" clShort="q, v, Q" merging=false /> <@setting name="echoFormat" type="string" default="" clShort="F" merging=false /> <@setting name="columns" type="integer" default="" merging=false /> <@setting name="printStackTrace" type="boolean" default="false" merging=false /> <@setting name="snip" type="boolean" default="true" merging=false />

If these settings are supported or not, depends on the front-end you use. If a setting is not supported, the front-end must silently ignore it.

The <@s>quiet setting tells the front-end if how much should it show the progress of the processing session on the screen. The accepted values are <@c>true, <@c>false (of type string or boolean), and <@c>reallyQuiet. Also, empty string is equivalent with <@c>true. (Values <@c>-1, <@c>0, <@c>1 are also supported for backward compatibility.) The precise meaning of values is front-end specific.

The <@s>echoFormat setting specifies how to display the progress of the processing session on the screen. The meaning of values and the set of understood values are front-end specific, but values <@c>verbose, <@c>normal, <@c>terse and <@c>quiet should be understood, also the shorthands of them: <@c>v, <@c>n, <@c>t and <@c>q. The front-end must not stop with error if it doesn't understand the value that comes from a configuration file.

The <@s>columns setting specifies the number of columns on the console (terminal), which is used for text wrapping. This is only applicable if you are using a command line interface for FMPP (or something similar). If you are using the provided shell script to invoke the command line interface, that will try to auto-detect the actual value (since 0.9.15), so you shouldn't set this setting, unless the auto-detection gives incorrect result.

The <@s>printStackTrace setting specifies if the front-end should print stack trace to the screen on error, or a terser error description. <@s>snip is deprecated, and now it's just the inverted alias of <@s>printStackTrace.

Please read the documentation of <@a href="frontends.html">the front-end you use for the precise behavior of these settings.

<@sect title="Meta settings" anchor="metaSettings"> <@setting name="configurationBase" type="string (path)" default="" merging=false /> <@setting name="inheritConfiguration" type="string (path)" default="" merging=false />

These settings influence the interpretation of the configuration file they are stored in. Although front-ends may support the specification of these settings outside configuration files, with the front-end specific interface, the meta setting specified in this way is used to emulate that the setting is present in the configuration file the front-end loads.

The <@s>configurationBase setting sets the <@a href="configfile.html#configurationBase">configuration base for the setting values stored in the same configuration file. If the <@s>configurationBase itself is a relative path, then it is resolved relatively to the directory of the configuration file.

If <@s>inheritConfiguration is present in a configuration file, then the configuration will <@a href="configfile.html#inheritance">inherit the configuration file pointed by the value of this setting. If <@s>inheritConfiguration is a relative path, then it is resolved relatively to the configuration base, which is already overridden by <@s>configurationBase if that's persent in the configuration file.

<@sect title="XML related settings" anchor="xml"> <@setting name="xmlCatalogFiles" type="sequence (of paths)" default="" merging=true /> <@setting name="xmlCatalogPrefer" type="string" default="public" merging=false /> <@setting name="validateXml" type="boolean" default="false" merging=false /> <@setting name="xpathEngine" type="string" default="dontSet" merging=false /> <@setting name="xmlRenderings" type="sequence (of hashes)" default="ex:empty" merging=true /> <@sect title="Catalogs">

Catalog files are (primarily) used to map public identifiers (and system identifiers) to local files. For example, you want to load an XML file that starts with this:

<@prg>

Whenever you try to load this XML file, the XML parser will need the DTD requested by the DOCTYPE, so it will try to download it from <@c>http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd (and all other files the DTD will refer to), which is obviously a bad joke. The standard solution is that you obtain the DTD file (and the further files it refers to) and store it locally on your computer, and also you write a catalog file that maps public identifiers (as <@c>-//W3C//DTD XHTML 1.0 Transitional//EN) to the local paths of the files. Then, you have to specify the catalog file(s) for FMPP with the <@s>xmlCatalogFiles setting.

FMPP supports the "widely known" catalog formats: OASIS plain text TR9401 catalog files, OASIS XML Catalogs, and XCatalogs. Delegate entries are supported. Don't panic if you can't undestand a word of it! :) Just look at <@example 'xml_validating' />. For most people it's enough to know (copy-paste...) what (s)he sees there. If you still need more information, please visit the Web page of the OASIS Entity Resolution Technical Committee: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=entity.

The meaning of <@s>xmlCatalogPrefer should be clean if you are familiar with OASIS catalogs. If you are not, just left it unchanged. The allowed values of this setting are <@c>system, <@c>public, and <@c>globalDefault.

Both catalog related settings has a global (Java virtual machine level) default. Please find the documentation of <@c>org.apache.xml.resolver package on the Internet about this. In the case of <@s>xmlCatalogFiles, the global default will be appended at the end of the list of catalog files. In the case of <@s>xmlCatalogPrefer, the global default is used when the value of the setting is <@c>globalDefault. Attention! If you don't use the <@s>xmlCatalogFiles FMPP setting, then the catalog feature is disabled, so you must specify this setting (even an empty sequence) to use the global defaults.

<@sect title="Validation">

The <@s>validateXml setting specifies if, by default, XML files are validated (i.e. checked against the DTD) or not. With "by default" I mean that this can be overridden for individual files, as with the <@c>validate option of the <@a href="dataloader.html#key_xml">xml data loader.

<@sect title="XPath engine">

The <@s>xpathEngine setting specifies which XPath engine will FreeMarker use when you access XML data (see <@a href="dataloader.html#key_xml">XML dataloader). This setting accepts these values:

If you embed FMPP into your application, then you have to know that XPath engine choosing is a VM level setting (static field) of FreeMarker. Whenever you execute a processing session, FMPP will aggressively set this FreeMarker setting according the <@s>xpathEngine FMPP setting. Thus, if you don't want FMPP to interfere with other FreeMarker dependent components in the same VM, you should keep value <@c>dontSet.

<@sect title="XML rendering" anchor="xmlRendering">

XML rendering is similar to the typical XSLT usage pattern, if you know that. The source file, for which <@c>renderXml processing mode is choosen (see the <@s>modes setting), will be parsed as XML file. Then, this XML document will be rendered to one or more output files with a FreeMarker template, which is choosen based on the value of the <@s>xmlRenderings setting. The template gets the XML documents with the <@a href="pphash.html#key_doc"><@c>pp.doc variable. Since the template shouldn't be executed in itself, it should be an ignored file (for example it should be stored in a directory that has an <@c>ignoredir.fmpp file).

For an example of this pattern check <@example 'xml_rendering'/>.

<@note>Sometimes you rather want to handle XML files as data than as source files. In this case use <@s>data, <@s>localData, or <@a href="pphash.html#key_loadData"><@c>pp.loadData with the <@a href="dataloader.html#key_xml">XML data loader, not XML rendering.

The <@s>xmlRenderings setting stores a sequence of XML rendering configurations. An XML rendering configuration is a hash that stores the options of an XML rendering. The options are:

Example:

<@prg><#noparse> xmlRenderings: [ { ifDocumentElementIs: product template: renderer/product.html xmlns: {D: http://example.com/xmlns/products} } { ifDocumentElementIs: book template: renderer/book.html index: { element: [part, chapter] attribute: ppFile numbering: hierarchical value: '%e_%n.html' } } ]

When <@c>renderXml processing mode is chosen for a source file (see <@s>modes), then the first matching XML rendering configuration of the sequence will be used. A configuration is matching if nor the <@c>ifSourceIs, nor the <@c>ifDocumentElementIs option excludes the XML file. (Thus, if a configuration doesn't use any of the <@c>if<@r>... options, it will be used for all source files, unless an earlier configuration matches the source file too.)

<@sect title="FreeMarker links (external includes)"> <@setting name="freemarkerLinks" type="hash (of sequence of paths)" default="" merging=true />

FreeMarker links is a dirty hack to satisfy a frequent demand: <@c><#include ...>/<@c><#import ...> files that are outside the source root directory, as common FTL macro libraries used in multiple projects.

Assume you store your commonly used FreeMarker includes in the <@c>c:\user\freemarker\include directory. But, this directory is outside the <@s>sourceRoot, so you can't reach it with <@c><#include ...>/<@c><#import ...>. To solve this, add this to the FMPP configuration file:

<@prg><#noparse> freemarkerLinks: { inc: c:/user/freemarker/include }

Now you can include files of that external directory like this:

<@prg><#noparse> <#include "/@inc/foo.ftl">

Here, FreeMarker will actually read <@c>c:\user\freemarker\include\foo.ftl. The seeming <@c>@inc entry in the source root directory (seeming, as there is no such file or directory there in reality) acts as an alias, a transparent link to <@c>c:\user\freemarker\include. (Note that in the configuration file I have used <@a 'overview.html#realPath'>slash instead of backslash for convenience.)

It is important that link entries (as <@c>@inc above) are visible only for the predefined FreeMarker directives that use template paths (in FreeMarker 2.3, these are <@c><#include ...> and <@c><#import ...>), or for user defined directives that internally use those predefined directives. They are not visible for anything else. Thus, they are not visible for the functions and directives of the <@c>pp hash, nor FMPP will try to process the <@c>@inc directory (since it doesn't see it at all).

As you have seen, a link is defined by associating a name (<@c>inc in the last example, but you can use anything else you prefer) with a path. You can have more links with different names. The link is visible in the source root (never in its subdirectories) as a directory (or file) of name <@c>@<@r>name (where <@c><@r>name is the link name). Regarding the associated path, the rules are the same as with <@s>sourceRoot, <@s>outputRoot, ...etc: it is a <@a 'overview.html#realPath'>real path, so if it is relative, then it will be interpreted relatively to the <@a 'overview.html#realPath'>configuration base.

For example, assume, that you also have project specific include files, and you store them outside the source root (because you have multiple source roots in your project), in the <@c>include subdirectory of the same directory, where you stores the FMPP configuration files for your project. Use this in the FMPP configuration file:

<@prg><#noparse> freemarkerLinks: { inc: /home/joe/freemarker/include projInc: include }

Note that the path associated with <@c>projInc is a relative path, so it will be resolved relatively to the directory of the configuration file (unless you have overridden the configuration base, of course...). Now you can do things like this:

<@prg><#noparse> <#include "/@projInc/header.html"> <#include "/@inc/foo.ftl"> <#import "/@projInc/forms.ftl" as f>

If the configuration file that contains the above is <@c>/home/joe/projects/foo/cfg3.fmpp, then <@c><#include '/@projInc/header.html'> will read <@c>/home/joe/projects/foo/include/header.html.

In the generic case, a FreeMarker link is associated with a list of paths. For example:

<@prg><#noparse> freemarkerLinks: { inc: [/home/joe/freemarker/include, /home/kate/freemarker/include] }

When you use <@c><#include '/@inc/foo.ftl'> in a template, then FMPP will check if <@c>/home/joe/freemarker/include/foo.ftl exist, and if not, it will try <@c>/home/kate/freemarker/include/foo.ftl.

Files that are really in the source root directory have priority over files that are accessible through FreeMarker links. For example, if you invoke <@c><#include '/@inc/foo.ftl'>, and the source root directory has a subdirectory called <@c>@inc, and that subdirectory has a file called <@c>foo.ftl, then that file will be used, without considering that the <@c>@inc in the path possibly refers to a FreeMarker link. If a subdirectory called <@c>@inc exists, but it doesn't contain <@c>foo.ftl, then the <@c>inc link will be used.

A FreeMarker link can point to files as well, not only to directories. For example:

<@prg><#noparse> freemarkerLinks: { footer: /home/joe/footers/gpl.html }

and then in a template you can do this:

<@prg><#noparse> <#include "@footer">

The merging of the <@s>freemarkerLinks settings is differs a bit from the merging of other hash settings: when the two hashes to merge contains the same key (i.e. the same link name), then the lists of paths for that key will be concatenated. For example, if <@c>common.fmpp is:

<@prg><#noparse> freemarkerLinks: { a: c:/user/fm/libs1 b: [inc1, inc2] }

and <@c>config.fmpp is:

<@prg><#noparse> inheritConfiguration: common.fmpp ... freemarkerLinks: { a: c:/user/fm/libs2 b: [inc3, inc4] c: foo } ...

then the resulting setting value is equivalent with:

<@prg><#noparse> freemarkerLinks: { a: [c:/user/fm/libs2, c:/user/fm/libs1] b: [inc3, inc4, inc1, inc2] c: foo }

Note that the name of the links doesn't start with <@c>@; the <@c>@ is used only to refer to the links. To protect users from mistakes regarding this, it is not allowed to start a link name with <@c>@.

<@sect title='Activating fixes/improvements' anchor="freemarkerIncompatibleImprovements"> <@setting name="recommendedDefaults" type="string (version number)" default="0.9.15" merging=false since='0.9.16' /> <@setting name="freemarkerIncompatibleImprovements" type="string (version number)" default={ '0.9.15': '2.3.0', '0.9.16': '2.3.28' } merging=false since='0.9.15' />

<@s>recommendedDefaults influences the default value of other settings. The setting value defaults will be those recommended as of the specified FMPP version. When you start a new project, set it to the current FMPP version (${pp.version} currently). In older projects changing this setting can break things, so check how the defaults change:

The lowest allowed <@s>recommendedDefaults value is 0.9.15, and the highest allowed is the version of the FMPP release that you are using.

<@s>freemarkerIncompatibleImprovements enables the FreeMarker fixes/improvements that are not 100% backward compatible, and were implemented in the FreeMarker version given in this setting. In older projects using the highest available <@c>2.3.<@r>x usually works fine, but check what changes <@a href="freemarker/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-">in the documentation. New projects should definitely use the maximum, which is the version of the FreeMarker used (<@c>fmpp --version will print that, also, the current FMPP version was built with FreeMarker ${pp.freemarkerVersion}). See <@a href="freemarker/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-"><@c>Configuration(Version) in the FreeMarker API for more information, such as what fixes/improvements are activated.

The format of both these settings is <@c><@r>major.<@r>minor.<@r>micro, where each part is a positive integer without padding 0-s.

<@sect title="Object wrapping" anchor="objectWrapping"> <@setting name="objectWrapper" type="string (BeanShell expression)" default={ '0.9.15': '"b = new BeansWrapperBuilder(freemarkerIncompatibleImprovements); b.setSimpleMapWrapper(true); return b.build();"', '0.9.16': '"b = new DefaultObjectWrapper(freemarkerIncompatibleImprovements); ...; return b.build(); /* See fmpp.Engine constructor JavaDocs */"' } merging=false />

The <@s>objectWrapper setting is for FreeMarker "experts" who want to use a customized <@c>ObjectWrapper. The value of the setting is a BeanShell expression that must result in an object whose class extends the <@c>freemarker.ext.beans.BeansWrapper class. The value can be a simple expression like <@c>"new com.example.MyWrapper()", or multiple instructions ending with a <@c>return statement.

The <@c>freemarker.template.ObjectWrapper, <@c>freemarker.template.DefaultObjectWrapper, <@c>freemarker.template.DefaultObjectWrapperBuilder, <@c>freemarker.ext.beans.BeansWrapper, and <@c>freemarker.ext.beans.BeansWrapperBuilder classes are automatically imported, so you don't have to use full-qualified class name for them. Also, a non-<@c>null <@c>freemarkerIncompatibleImprovements value is exposed, which corresponds to the effective value of the similarly named FMPP setting.

The <@c>ObjectWrapper is created before other setting values (or the <@c>fmpp.Engine instance for that mater), so the BeanShell expression has no access to any setting values, except to <@s>freemarkerIncompatibleImprovements, as it was shown.

The default value shown is actually only used when <@s>freemarkerIncompatibleImprovements is at least <@c>2.3.21. For more information please consult <@a href="api/fmpp/Engine.html#Engine-freemarker.template.Version-freemarker.template.Version-freemarker.ext.beans.BeansWrapper-">the JavaDoc of the <@c>fmpp.Engine constructor.

<@sect title="Template syntax" anchor="templateSyntax"> <@setting name="tagSyntax" type="string" default='ex:<@c>angleBracket' merging=false />

The <@s>tagSyntax setting determines the syntax of tags in the templates (angle bracket syntax like <@c><#include "foo"> VS square bracket syntax like <@c>[#include "foo"]) that has no <@c>ftl directive in it. If the template uses <@c>ftl directive (like it starts with <@c><#ftl> or <@c>[#ftl]), then the syntax of the <@c>ftl tag determines the syntax of the template, and the <@s>tagSyntax setting is ignored.

The possible values of this setting are <@c>angleBracket, <@c>squareBracket and <@c>autoDetect. The recommended value is <@c>autoDetect, which will auto-detect the syntax of each template independently, by choosing the syntax of the first FreeMarker tag in the template. For example when it finds a <@c>[@ in the template, it will choose square bracket syntax.

<@setting name="interpolationSyntax" type="string" default='ex:<@c>legacy' merging=false since="0.9.16" />

The <@s>interpolationSyntax setting determines the syntax of the interpolations (where you insert a value, like <@c><#noparse>${<@r>name}) in templates.

The possible values of this setting are <@c>legacy (like <@c><#noparse>${<@r>expression} and the deprecated <@c><#noparse>#{<@r>numericExpression}), <@c>dollar (means <@c><#noparse>${<@r>expression} only), and <@c>squareBracket (like <@c>[=<@r>expression]. The recommended value is <@c>dollar, unless the <@c><#noparse>${ pattern clashes with the static parts that you need to generate (like when you generate JSP or shell script), in which case use <@c>squareBracket. The default is <@c>legacy (as far as that's the default of FreeMarker).