picea/docs/02-control-structure-view-include-block.md

Control structure - View (or include) / Block

There is three ways to include other views into your current view {% view %} / {% include %} or using {% block %}{% endblock %}.

The order of loading depends on the order given within your directory configuration; the first file found from it will be used.

Inline view (string $path, array|null $arguments = null)

You must provide a valid $path from which the template will be loaded. If no $arguments are provided, defined variables from the caller's scope will be given (from get_defined_vars()).

[PICEA] So, using this code:

path/base/nav.phtml

<nav>
    {% foreach $navigation as $index => $navItem %}
        {% view "path/base/nav-item", [ 'item' => $navItem, 'index' => $index] %}
    {% endforeach %}
</nav>

path/base/nav-item.phtml

<a href="{{ $item->anchor }}" tabindex="{{ $index }}">{{ $item->name }}"</a>

[HTML] Could render such as :

<nav>
    <a href="#top">Top</a>
    <a href="#bottom">Bottom</a>
    <a href="#left">Left</a>
    <a href="#right">Right</a>
</nav>

include (string $path) content from external file

Whenever you need to include a raw file from one of your view directories

Reusable block (string $path, ...$arguments) / endblock

A better way to achieve this behaviour could be to create a block which you can define as needed.

[PICEA] So, using this code:

path/base/nav.phtml

<nav>
    {% foreach $navigation as $index => $navItem %}
        {% block "path/base/nav-item-block", $navItem->name, $navItem->anchor, $index %}{% endblock %}
    {% endforeach %}
</nav>

path/base/nav-item-block.phtml

{% arguments string $name, string $anchor, int $index = 0 %}

<a href="{{ $anchor }}" tabindex="{{ $index }}">{{ $name }}"</a>

[HTML] Would render the same as the view example :

<nav>
    <a href="#top">Top</a>
    <a href="#bottom">Bottom</a>
    <a href="#left">Left</a>
    <a href="#right">Right</a>
</nav>

Extending a block using define and slot

You might need to define some custom content inside of a block.

You can do so by using define and slot.

[PICEA] So, using this code:

path/base/nav.phtml

<nav>
    {% foreach $navigation as $index => $navItem %}
        {% block "path/base/nav-item-block", $navItem->name, $navItem->anchor, $index %}
            {% slot "attributes" %} class="nav-item" href="{{ $anchor }}" {% endslot %}
        {% endblock %}
    {% endforeach %}
</nav>

path/base/nav-item-block.phtml

{% arguments string $name, string $anchor, int $index = 0 %}

{% define "attributes" %}

<a {% slot "attributes" %}{% endslot %} href="{{ $anchor }}" tabindex="{{ $index }}"{% endslot %}>{{ $name }}"</a>

[HTML] Would render the same as the view example :

<nav>
    <a href="#top">Top</a>
    <a href="#bottom">Bottom</a>
    <a href="#left">Left</a>
    <a href="#right">Right</a>
</nav>