Partials are template files that are included in other templates.
They are commonly used for small parts that are repeated among templates or layouts.
By default partials have access to all current context (template variables), but is possible to limit or completely disable access to it. It is also possible to pass partial-specific variables. See "Data / Pass Data to Templates" to know more on the topic.
Partials are inserted in a template using
<div id="sidebar"> <?= $this->insert('partials/sidebar') ?> </div>
insert() accepts as first argument the partial name to be inserted and returns its content.
So you need to echo what is returned by
insert() to make the content visible.
Partials are searched in all registered folders, just like standard templates. All the rules that apply to Foil engine methods
find() are valid for
insert() too: default extension, specific folders targeting, and so on.
See "Templates / Overview" to know more on the topic.
When you call
insert() with a non-existent template name an exception is thrown.
Sometimes may be desirable to insert a partial only if it exists, without any error if it isn't there.
That can be done with
insertif() that accepts exact same arguments of
insertif() returns nothing if template is not found, it can be easily used to output a default content when the partial doesn't exist:
<?= $this->insertif('header') ?: 'Default Header' ?>
Note that another partial can be used as default:
<?= $this->insertif('header') ?: $this->insertif('default-header') ?>
Sections Definition in Partials
Foil supports sections definition in partials (See "Templates / Inheritance" to know more about sections).
For example, let's assume in a layout, named
home.php, there's the following code:
<!DOCTYPE html> <html> <head> <title>My Awesome Page</title> </head> <body> <div id="main"> Welcome! </div> <div id="sidebar"> <?= $this->insert('partials/sidebar') ?> </div> </body> </html>
and in the partials
partials/sidebar.php there is the code:
<?php $this->section('sidebar-top') ?> <div> <h3>Sidebar</h3> </div> <?php $this->stop() ?> <?php $this->section('sidebar-main') ?> <div> <p>Default sidebar.</p> </div> <?php $this->stop() ?>
In a template that extends
home.php is possible to extends / replace the content of
sections even if they were defined in a partial:
<?php $this->layout('home') ?> <?php $this->section('sidebar-main') ?> <div> <p>Custom sidebar.</p> </div> <?php $this->replace() ?>