E.9 ReplaceTokensWithFile
Prev | Appendix E. Core filters | Next

## E.9 ReplaceTokensWithFile

The `ReplaceTokensWithFile` filter will replace certain tokens with the contents of a file. The name of the file to use as replacement is derived from the token name itself. Tokens are strings enclosed in special characters which are user selectable.

This filter could for example be used to insert code examples in documentation where the example code are real executable files kept outside the documentation.

If you for example want to replace `#!example1##` with the content of the file " `example1.php` " you could do the following

    <filterchain>
          <replacetokenswithfile begintoken="#!" endtoken="##"
              dir="exampledir/" postfix=".php" />
          </filterchain>

The filer above will replace all tokens within the begin and end token specified with the contents of the file whose base name is that of the token with the added postfix ".php". Only the directory specified in the `dir` attribute is searched. If the file is not found the token is left untouched and an error message is given. It is important to note that all found tokens will be replaced with the corresponding file. So in the example below even `#!example2##` will be replaced with the content of the file " `example2.php` "

Table E.7: Attributes for the `<replacetokenswithfile>` tag

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
`begintoken` | `String` | The string that marks the beginning of a token. | #@# | No
`endtoken` | `String` | The string that marks the end of a token. | #@# | No
`prefix` | `String` | A string that will be added in front of the token to construct the filename that will be used as source when replacing the token. | '' | No
`postfix` | `String` | A string that will be added to the end of the token to construct the filename that will be used as source when replacing the token. | '' | No
`dir` | `String` | The directory where to look for the files to use as replacements for the tokens | './' | No
`translatehtml` | `Boolean` | If true all html special characters (e.g. ">") in the file to there corresponding html entities (e.g. "&gt;") before the file is inserted. | `true` | No

### E.9.1 Nested tags

None.

Prev | Up | Next
E.8 ReplaceTokens | Home | E.10 ReplaceRegexp