Views

The view system is the backbone of how Mythic handles templates. It's all controlled by the Hybrid\View\View class in the Hybrid Core framework.

This tutorial will give you a primer on how it actually works.

View class

The View class handles everything behind the scenes. So, let's take a look at it just to understand some of the internal things happening.

When creating a new view, it'd look like the following:

$view = new Hybrid\View\View( $name, $slugs = [], \Hybrid\Tools\Collection $data = null );

• $name - That's the name/ID of the template. It's actually used as a folder name. It's also used to build out filter hooks.
• $slugs - The slugs can be a string or array of strings. These are the actual file names (without the .php part) to look for in the $name folder.
• $data - This is a collection of custom data that you can pass into your template to use. You don't need to utilize the Collection class if you use one of the wrapper functions (see below) and can pass in an array.

Functions

There are three functions that you may want to use:

• display() - Renders a view template output to the page.
• render() - Returns the view template output as a string.
• view() - Returns a new view object (see View class above).

All three of these functions accept the same parameters as the View class. The only difference is that you can pass an array as the $data parameter instead of an instance of a Collection class.

Unless doing something extremely custom and more complex than outputting a template, you'll only ever need the display() function. That's the use case that we'll cover here.

Rendering views

Let's get started displaying a basic view. By default, all views will be housed in your theme's /resources/views directory.

The following example will display the fruit/watermelon.php view.

Hybrid\View\display( 'fruit', 'watermelon' )

Pretty simple, right? Let's say that you wanted to search for multiple slugs and to display the first view template that was found.

Hybrid\View\display( 'fruit', [ 'watermelon', 'sweet' ] )

That would actually look for the fruit/watermelon.php template first. If not found, it'd look for the fruit/sweet.php template.

Actually, the hierarchy goes even deeper than that. Here's the order that those files would be searched for:

fruit/watermelon.php
fruit/sweet.php
fruit/default.php
fruit.php

The view system builds out the entire hierarchy for you and does all the hard work. You just have to pass in the names and slugs that you want to search for.

Passing in custom data

Remember that $data parameter above? If you're accustomed to get_template_part() in WordPress and similar functions, you've been missing out on one of PHP's coolest features -- passing custom data/variables into files.

Building off our first example, let's pass some custom data to our fruit/watermelon.php template.

Hybrid\View\display( 'fruit', 'watermelon', [ 'type' => 'jubilee' ] )

That will make the $type variable available within your template. Here's what your fruit/watermelon.php file might look like:

<?php if ( 'jubilee' === $type ) : ?>

	This is a Jubilee watermelon. They're popular and commonly grown in the U.S. South.

<?php endif ?>

You can also access $type via $data->type or $data['type']. Use the method that you prefer.

Helper functions

You'll likely notice three different helper functions for generating the slugs throughout the theme.

• Hybrid\Template\hierarchy() - Generates a list of slugs based on the global template hierarchy.
• Hybrid\Post\hierarchy() - Generates a list of slugs based on the $post object.
• Hybrid\Comment\hierarchy() - Generates a list of slugs based on the $comment object.

These are just helpers. You can use them or roll your own solution.

One common thing for some theme authors might be to replace the post hierarchy with the template hierarchy. That way, post view templates follow the same hierarchy as other templates. It really depends on what you want to do.

Hooks

There are three filter hooks available within the View class for altering things on the fly.

The hybrid/view/{$name}/slugs hook allows you to filter the array of slugs:

apply_filters( "hybrid/view/{$name}/slugs", $slugs, $view );

The hybrid/view/{$name}/data hook allows you to filter the Collection of data:

apply_filters( "hybrid/view/{$name}/data", $data, $view );

The hybrid/view/{$name}/hierarchy hook allows you to alter the hierarchy of PHP files to search for just before the search begins.

apply_filters( "hybrid/view/{$name}/hierarchy", $templates, $slugs );