Templating and Views

Templating in WordPress should be delightful -- Mantle hopes to make it that way.

Views

WordPress template parts can be returned for a route.

routes/web.php

Route::get( '/', function () {
  return response()->view( 'template-parts/block', [ 'variable' => '123' ] );
} );

PHP Templates

Mantle supports normal PHP template partials. The view() helper function will automatically from any of the configured view locations.

ExampleController.php

class ExampleController {
  public function example() {
    return view( 'template-parts/block', [ 'variable' => '123' ] );
  }
}

template-parts/block.php

<div>
  <h1><?php echo esc_html( $variable ); ?></h1>
</div>

Blade Templates

Mantle also supports loading Laravel's Blade template parts. Blade and WordPress template parts can be used interchangeably. Mantle uses the illuminate/view package directly to provide complete compatibility with Blade templating.

Hello, {{ $name }}

Blade templates can be used interchangeably with PHP templates. Mantle will automatically detect the file extension and load the appropriate template engine.

View File Location

By default WordPress will only load a template part from the active theme and parent theme if applicable. Mantle supports loading views from a dynamic set of locations. Mantle support automatically register the current theme and parent theme as view locations. Additional paths can be registered through View_Loader.

use Mantle\Facade\View_Loader;

View_Loader::add_path( '/path-to-add' );

// Optionally provide an alias for easy referencing.
View_Loader::add_path( '/another-path', alias: 'vendor-views' );

// Remove a path.
View_Loader::remove_path( '/path-to-remove' );

Adding additional view locations will allow you to use templates that aren't located in the theme directory. This can be useful for loading templates from a plugin which WordPress doesn't natively support.

Default View Locations

• Active Theme
• Parent of Active Theme (if applicable)
• {root of mantle site}/views

Loading Views

Views can be loaded using the view() helper function. This function will automatically detect the file extension and load the appropriate template engine.

echo view( 'template-parts/block', [ 'variable' => '123' ] );

Views will be loaded from the configured view locations in the order they were registered. If a view is found in multiple locations the first one found will be used.

To load a view from a specific location you can prefix the view name with the alias of the location in the format @{alias}/{path to view}:

echo view( '@vendor-views/template-parts/block', [ 'variable' => '123' ] );

Passing Variables to Views

Frequently you will need to pass variables down to views from controllers and routes. To ensure a global variable isn't overwritten the variables are stored in the helper method mantle_get_var().

// Call the view with a variable.
echo view( 'view/to/load', [ 'foo' => 'bar' ] );

// Inside the view...
echo mantle_get_var( 'foo' );

Inside of Blade Templates variables can access the variables directly. Blade will automatically escape the contents of a variable when using {{ ... }}.

Hello {{ $foo }}!

Passing Global Variables

Service Providers and other classes in the application can pass global variables to all views loaded. This can be very handy when you want to pass template variables to a service provider without doing any additional work in the route.

use Mantle\Facade\View;

// Pass 'variable-to-pass' to all views.
View::share( 'variable-to-pass', 'value or reference to pass' );

Setting the Global Post Object.

Commonly views need to set the global post object in WordPress for a view. This will allow WordPress template tags such as the_ID() and the_title() to work properly.

Route::get( '/article/{article}', function ( App\Article $article ) {
  // Supports passing a model, ID, or core WordPress object.
  return View::make( 'template-parts/block', [ 'post' => $article ] )->set_post( $article );
} );

template-parts/block.blade.php

<article>
  <h1>{{ the_title() }}</h1>
  <div>{{ the_content() }}</div>

  {{-- Use the passed variable. --}}
  <p>{{ $post->post_title }}</p>
</article>

View Helpers

loop()

Loop over a collection/array of post objects. Supports a collection or array of WP_Post objects, Mantle Models, post IDs, or a WP_Query object. The post object will be automatically setup for each template part. We don't have to while ( have_posts() ) : the_post(); ... endwhile;, keeping our code nice and DRY.

$posts = Post::all();
echo loop( $posts, 'view-to-load' );

iterate()

Iterate over a collection/array of arbitrary data. Each view is passed index and item as a the current item in the loop.

echo iterate( [ 1, 2, 3 ], 'view-to-load' );

View Shortcuts

When inside of a partial, you can prefix your path slug with _ to load a sub-partial, appending everything after the _ to the current partial's file name (with a dash separating them).

template-parts/homepage/slideshow.php

<div class="slideshow">
  @foreach ( $slides as $slide )
    @include( '_slide', [ 'text' => $slide->text ] )
  @endforeach
</div>

template-parts/homepage/slideshow-slide.php

echo mantle_get_var( 'text', "Slide data!" );