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.10: 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. ">") before the file is inserted. | true | No |