Creating templates

Separation of visual layer and application logic was always a problem while developing WordPress themes. The starter offers you some additional tools to solve this problem. Ability to share and pass data between divided templates give you a lot of flexibility.

Configuration

By default template files are stored inside resources/templates directory. You can control it inside config/app.php file with directories.templates option.

'directories' => [
  'templates' => 'resources/templates'
]

You may also customize extension of template files. By default, it is .tpl.php, however feel free to change it as you like in configuration file with templates.extension option.

'templates' => [
  'extension' => '.tpl.php'
]

Usage

It is recommended to use template() helper function to render your project template files. Let's take a look at the introductory example:

1. Create a .tpl.php file inside project templates directory.

<button><?= $title ?></button>

2. Render template with context using a template() function.

Visit the Template documentations for more completed API guides.

template('button', ['title' => 'Click me!']);

You can expect this output:

<button>Click me!</button>

Examples

Managing templates rendering with hooks is a great way for creating a reusable and easy to maintain a visual layer of your theme.

It's recomended to store template's rendering actions inside a app/Structure/templates.php file.

Rendering theme's single post view with help of hooks

Start with creating a template view for a single post. It is a standard loop with our custom theme/single/content action inside. Later, we will hook up to that action and render the content of a post.

<!-- @ resources/templates/single.tpl.php -->

<?php if (have_posts()) : ?>
  <main>
    <?php while (have_posts()) : the_post() ?>
      <?php do_action('theme/single/content') ?>
    <?php endwhile ?>
  </main>
<?php endif ?>

Inside the single.php controller file, we will simply render a template created above.

// @ single.php

namespace Tonik\Theme\Single;

use function Tonik\Theme\App\template;

template('single');

We can proceed and create a view file for a post content.

<!-- @ resources/templates/partials/content.tpl.php -->

<article>
  <header>
    <h1><?php the_title() ?></h1>
  </header>

  <p><?php the_content() ?></p>
</article>

Now, we can hook to a theme/single/content action, which are executed inside single.tpl.php file, and render previously created template for post content.

// @ app/Structure/templates.php

namespace Tonik\Theme\App\Structure;

use function Tonik\Theme\App\template;

function render_post_content()
{
  template('partials/post/content');
}
add_action('theme/single/content', 'Tonik\Theme\App\Structure\render_post_content');

Nothing blocks you from hooking template rendering handler to multiple actions. This allows you to reuse various template blocks, keep logic separation and still stay DRY. Great!

Rendering a sidebar with custom actions hooks

Start with a single.tpl.php post template with side content, but instead of immediately outputting the sidebar body, execute custom theme/single/sidebar action. You will later hook to that action in order to render actual sidebar.

<!-- @ resources/templates/single.tpl.php -->

<aside>
  <?php do_action('theme/single/sidebar') ?>
</aside>

Next, create the sidebar.tpl.php where you will output specified sidebar with dynamic_sidebar function.

<!-- @ resources/templates/partials/sidebar.tpl.php -->

<?php if (is_active_sidebar('sidebar')) : ?>
  <?php dynamic_sidebar('sidebar') ?>
<?php else: ?>
  <h5>Sidebar</h5>
  <p>Your sidebar is empty.</p>
<?php endif; ?>

We also need main controller file for sidebar itself. It should just render sidebar.tpl.php template.

// @ sidebar.php

namespace Tonik\Theme\Sidebar;

use function Tonik\Theme\App\template;

template('partials/sidebar');

Finally, hook to previously created action inside single.tpl.php and output sidebar (the sidebar.php file) with get_sidebar() function.

// @ app/Structure/templates.php

namespace Tonik\Theme\App\Structure;

function render_sidebar()
{
  get_sidebar();
}
add_action('theme/single/sidebar', 'Tonik\Theme\App\Structure\render_sidebar');