<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>E.9 ReplaceTokensWithFile</title>
    <link rel="stylesheet" type="text/css" href="book.css">
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
    <link rel="home" href="index.html" title="Phing User Guide">
    <link rel="up" href="app.corefilters.html" title="Appendix E. Core filters">
    <link rel="prev" href="ReplaceTokens.html" title="E.8 ReplaceTokens">
    <link rel="next" href="ReplaceRegexp.html" title="E.10 ReplaceRegexp">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
    <table width="100%" summary="Navigation header">
        <tr>
            <th colspan="3" align="center">E.9 ReplaceTokensWithFile</th>
        </tr>
        <tr>
            <td width="20%" align="left"><a accesskey="p" href="ReplaceTokens.html">Prev</a> </td>
            <th width="60%" align="center">Appendix E. Core filters</th>
            <td width="20%" align="right"> <a accesskey="n" href="ReplaceRegexp.html">Next</a></td>
        </tr>
    </table>
    <hr>
</div>
<div class="sect1">
    <div class="titlepage">
        <div>
            <div><h2 class="title" style="clear: both"><a name="ReplaceTokensWithFile"></a>E.9 ReplaceTokensWithFile
            </h2></div>
        </div>
    </div>

    <p>The <code class="literal">ReplaceTokensWithFile</code> 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.</p>

    <p>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.</p>

    <p>If you for example want to replace <code class="literal">#!example1##</code> with the content of
        the file " <code class="code">example1.php</code> " you could do the following</p>
        <pre class="programlisting">&lt;filterchain&gt;
      &lt;replacetokenswithfile begintoken="#!" endtoken="##"
          dir="exampledir/" postfix=".php" /&gt;
      &lt;/filterchain&gt;</pre>
    <p>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 <code class="literal">dir</code> 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 <span class="emphasis"><em>all</em></span> found tokens will be
        replaced with the corresponding file. So in the example below even
        <code class="literal">#!example2##</code> will be replaced with the content of the file "
        <code class="code">example2.php</code> "</p>


    <div class="table"><a name="idp56784576"></a>

        <p class="formal-object-title"><span class="label">Table E.7: </span><span
            class="title"> Attributes for the <code class="literal">&lt;replacetokenswithfile&gt;</code> tag </span></p>

        <div class="table-contents">

            <table summary=" Attributes for the &lt;replacetokenswithfile&gt; tag " border="1">
                <colgroup>
                    <col class="name">
                    <col class="type">
                    <col class="description">
                    <col class="default">
                    <col class="required">
                </colgroup>
                <thead>
                <tr>
                    <th>Name</th>
                    <th>Type</th>
                    <th>Description</th>
                    <th>Default</th>
                    <th>Required</th>
                </tr>
                </thead>
                <tbody>
                <tr>
                    <td><code class="literal">begintoken</code></td>
                    <td><code class="literal">String</code></td>
                    <td>The string that marks the beginning of a token.</td>
                    <td>#@#</td>
                    <td>No</td>
                </tr>
                <tr>
                    <td><code class="literal">endtoken</code></td>
                    <td><code class="literal">String</code></td>
                    <td>The string that marks the end of a token.</td>
                    <td>#@#</td>
                    <td>No</td>
                </tr>
                <tr>
                    <td><code class="literal">prefix</code></td>
                    <td><code class="literal">String</code></td>
                    <td>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.
                    </td>
                    <td>''</td>
                    <td>No</td>
                </tr>
                <tr>
                    <td><code class="literal">postfix</code></td>
                    <td><code class="literal">String</code></td>
                    <td>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.
                    </td>
                    <td>''</td>
                    <td>No</td>
                </tr>
                <tr>
                    <td><code class="literal">dir</code></td>
                    <td><code class="literal">String</code></td>
                    <td>The directory where to look for the files to use as replacements for
                        the tokens
                    </td>
                    <td>'./'</td>
                    <td>No</td>
                </tr>
                <tr>
                    <td><code class="literal">translatehtml</code></td>
                    <td><code class="literal">Boolean</code></td>
                    <td>If true all html special characters (e.g. "&gt;") in the file to there
                        corresponding html entities (e.g. "&amp;gt;") before the file is
                        inserted.
                    </td>
                    <td><code class="literal">true</code></td>
                    <td>No</td>
                </tr>
                </tbody>
            </table>
        </div>
    </div>
    <br class="table-break">

    <div class="sect2">
        <div class="titlepage">
            <div>
                <div><h3 class="title"><a name="idp56816352"></a>E.9.1 Nested tags</h3></div>
            </div>
        </div>

        <p>None.</p>
    </div>
</div>
<div class="navfooter">
    <hr>
    <table width="100%" summary="Navigation footer">
        <tr>
            <td width="40%" align="left"><a accesskey="p" href="ReplaceTokens.html">Prev</a> </td>
            <td width="20%" align="center"><a accesskey="u" href="app.corefilters.html">Up</a></td>
            <td width="40%" align="right"> <a accesskey="n" href="ReplaceRegexp.html">Next</a></td>
        </tr>
        <tr>
            <td width="40%" align="left" valign="top">E.8 ReplaceTokens </td>
            <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
            <td width="40%" align="right" valign="top"> E.10 ReplaceRegexp</td>
        </tr>
    </table>
</div>
</body>
</html>
