tpl/syntax
< >

return function () {
    $self = url('/@object/@action/' . urlencode('tpl/syntax'));
    $tour = _class('docs')->_sample('tpl_syntax');
    $example = $tour->example($_GET['example'] ?? null);
    $info = $tour->EXAMPLES[$example];
    $p = $tour->params($example, $_GET);
    $data = $tour->data($example, $p);

    $intro = '<p class="docs-demo-intro">A tour of the template syntax of the yf driver: each example shows the template, the PHP
        that renders it with <code>tpl()->parse_string()</code> and the output, as HTML and as its source. The templates are
        fixed; some examples let you change a few values (text keeps letters, digits and <code>. , ! ? \' -</code>, numbers
        and choices come from fixed ranges). Template files work the same through <code>tpl()->parse(\'module/name\', $replace)</code>.
        Classes: <code>yf_tpl</code>, <code>yf_tpl_driver_yf</code>.</p>';

    $links = '';
    foreach ($tour->EXAMPLES as $key => $ex) {
        $links .= '<a class="btn btn-sm ' . ($key === $example ? 'btn-primary active' : 'btn-default btn-outline-primary') . '" href="' . $self . '?example=' . $key . '">' . _prepare_html($ex['title'], 0) . '</a> ';
    }

    $form = '';
    if ($info['fields']) {
        $inputs = '';
        foreach ($info['fields'] as $name => $field) {
            $value = (string) $p[$name];
            if ($field[0] === 'enum') {
                $options = '';
                foreach ($field[2] as $choice) {
                    $options .= '<option value="' . $choice . '"' . ($choice === $value ? ' selected' : '') . '>' . $choice . '</option>';
                }
                $control = '<select name="' . $name . '" class="form-control form-select">' . $options . '</select>';
            } elseif ($field[0] === 'int') {
                $control = '<input type="number" name="' . $name . '" class="form-control" min="' . $field[2] . '" max="' . $field[3] . '" value="' . $value . '">';
            } else {
                $control = '<input type="text" name="' . $name . '" class="form-control" maxlength="' . $tour->MAX_TEXT_LEN . '" value="' . _prepare_html($value, 0) . '">';
            }
            $inputs .= '<label>' . $name . ' ' . $control . '</label>';
        }
        $form = '<form method="get" action="' . $self . '" class="docs-demo-tpl-form"><input type="hidden" name="example" value="' . $example . '">'
            . $inputs . '<button type="submit" class="btn btn-primary">Render</button></form>';
    }

    $source = '<div class="row"><div class="col-md-6"><h4>Template</h4><pre class="docs-demo-tpl"><code class="html">' . _prepare_html($info['stpl'], 0, 0) . '</code></pre>';
    if ($example === 'blocks') {
        $source .= '<h4>' . _prepare_html($tour->PARTIAL_NAME, 0) . '</h4><pre class="docs-demo-tpl"><code class="html">' . _prepare_html($tour->PARTIAL, 0, 0) . '</code></pre>';
    }
    $source .= '</div><div class="col-md-6"><h4>PHP</h4><pre class="docs-demo-tpl"><code class="php">' . _prepare_html($tour->code($example, $data), 0, 0) . '</code></pre></div></div>';

    // sources print entities as written (< stays visible): plain htmlspecialchars, not the smart variant that skips them
    $out = '';
    foreach ($tour->render($example, $data) as $label => $html) {
        $out .= '<div class="row docs-demo-tpl-out"><div class="col-md-6"><h4>' . _prepare_html($label, 0) . '</h4><div class="docs-demo-tpl-render">' . $html . '</div></div>'
            . '<div class="col-md-6"><h4>HTML</h4><pre class="docs-demo-tpl"><code class="html">' . _prepare_html(trim(preg_replace('~\n\s*\n~', "\n", $html)), 0, 0) . '</code></pre></div></div>';
    }

    css('.docs-demo-tpl-examples .btn { margin:0 4px 6px 0; }
        .docs-demo-tpl-about { margin:6px 0 12px; }
        .docs-demo-tpl-form { display:flex; flex-wrap:wrap; align-items:center; gap:8px 14px; margin-bottom:12px; }
        .docs-demo-tpl-form label { font-weight:normal; margin:0; }
        .docs-demo-tpl-form .form-control { display:inline-block; width:auto; max-width:200px; margin-left:4px; }
        .docs-demo-tpl-form input[type=number] { width:80px; }
        section.page-contents pre.docs-demo-tpl { font-size:12px; }
        pre.docs-demo-tpl code { white-space:pre-wrap; word-break:break-word; }
        .docs-demo-tpl-render { border:1px solid #ddd; border-radius:4px; padding:12px 15px; margin:10px 0 20px; min-height:42px; }
        .docs-demo-tpl-render > :last-child, .docs-demo-tpl-render .docs-demo-tpl-card { margin-bottom:0; }
        .docs-demo-tpl-render ul { padding-left:20px; }
        .cssfw-bs5 .docs-demo-tpl-render { border-color:var(--bs-border-color); }');
    return $intro
        . '<p class="docs-demo-tpl-examples">' . $links . '</p>'
        . '<h3>' . _prepare_html($info['title'], 0) . '</h3><p class="docs-demo-tpl-about">' . $info['about'] . '</p>'
        . $form . $source . $out;
};

A tour of the template syntax of the yf driver: each example shows the template, the PHP that renders it with tpl()->parse_string() and the output, as HTML and as its source. The templates are fixed; some examples let you change a few values (text keeps letters, digits and . , ! ? ' -, numbers and choices come from fixed ranges). Template files work the same through tpl()->parse('module/name', $replace). Classes: yf_tpl, yf_tpl_driver_yf.

Variables and filters Conditions Loops Translations Include, catch, comments Escaping Links

Escaping

By default a variable prints as it is, so text from users needs |_prepare_html. With AUTO_ESCAPE on ($PROJECT_CONF['tpl']['AUTO_ESCAPE'] = true, planned as the default of 4.0) every variable is escaped and |raw opts out. The same template, rendered both ways:

Template

<p>Plain: {comment}</p>
<p>Filtered: {comment|_prepare_html}</p>
<p>Opt-out: {comment|raw}</p>

PHP

$replace = [
    'comment' => '<b>Tom</b> & "Jerry"',
];
// tpl()->AUTO_ESCAPE = true;
echo tpl()->parse_string($stpl, $replace);
// from a file: tpl()->parse('module/name', $replace)

AUTO_ESCAPE off (the default)

Plain: Tom & "Jerry"

Filtered: <b>Tom</b> & "Jerry"

Opt-out: Tom & "Jerry"

HTML

<p>Plain: <b>Tom</b> & "Jerry"</p>
<p>Filtered: &lt;b&gt;Tom&lt;/b&gt; &amp; &quot;Jerry&quot;</p>
<p>Opt-out: <b>Tom</b> & "Jerry"</p>

AUTO_ESCAPE on

Plain: <b>Tom</b> & "Jerry"

Filtered: <b>Tom</b> & "Jerry"

Opt-out: Tom & "Jerry"

HTML

<p>Plain: &lt;b&gt;Tom&lt;/b&gt; &amp; &quot;Jerry&quot;</p>
<p>Filtered: &lt;b&gt;Tom&lt;/b&gt; &amp; &quot;Jerry&quot;</p>
<p>Opt-out: <b>Tom</b> & "Jerry"</p>