Creating Your Site's Content

Blade Templates & Partials

One of the biggest benefits of a templating language is the ability to create reusable layouts and partials. Jigsaw gives you access to all the templating features and control structures of Blade that are available in Laravel (learn more about Blade layouts in the official Blade documentation).

Defining a Layout

Layouts themselves are just basic Blade templates that have one or more @yield calls where child templates can render their contents.

A basic master layout could look like this:

 1<!DOCTYPE html>
 2<html>
 3    <head>
 4        <title>The Amazing Web</title>
 5    </head>
 6    <body>
 7        <header>
 8            My Amazing Site
 9        </header>
10 
11        @yield('content')
12 
13        <footer>
14            <p>©{{ date('Y') }} Awesome Co</p>
15        </footer>
16    </body>
17</html>

Jigsaw provides a /source/_layouts directory out of the box with a basic master layout.

Extending a Layout

To extend a layout, create a template that specifies which layout to extend in an @extends directive, and which section(s) to populate using the @section directive:

1@extends('_layouts.master')
2 
3@section('content')
4    <div>
5        <p>The contents of my amazing homepage.</p>
6    </div>
7@endsection

Layouts and partials are referenced relative to the source directory using dot notation, where each dot represents a directory separator in the file name and the .blade.php extension omitted.

Partials

To include a template inside of another template, use the @include directive:

 1<!DOCTYPE html>
 2<html>
 3    <head>
 4        <title>The Amazing Web</title>
 5    </head>
 6    <body>
 7        @include('_partials.header')
 8 
 9        @yield('content')
10 
11        @include('_partials.footer')
12    </body>
13</html>

You can pass data to a partial by passing an associative array as a second parameter:

 1<!DOCTYPE html>
 2<html>
 3    <head>
 4        <title>The Amazing Web</title>
 5    </head>
 6    <body>
 7        @include('_partials.header', ['page_title' => 'My Amazing Site'])
 8 
 9        @yield('content')
10 
11        @include('_partials.footer')
12    </body>
13</html>

That data is then available in your partial as a normal variable:

1<!-- _partials/header.blade.php -->
2<header>
3    {{ $page_title }}
4</header>

Components

Jigsaw supports both class based and anonymous Blade components.

To display a component, you may use a Blade component tag within one of your Blade templates. Blade component tags start with the string x- followed by the kebab case name of the component class:

1<x-input />

In Jigsaw, views are auto-discovered from the source/_components directory; to create an anonymous <x--style components, you only need to place a Blade template within that directory.

Class-based components can be manually registered using $bladeCompiler->component(), as detailed in the Extending Blade with custom directives section below; or, they can be auto-discovered by using the Components namespace. To autoload class-based components that use the Components namespace, add an autoload entry to your composer.json file:

composer.json

1"autoload": {
2    "psr-4": {
3        "Components\\": "where/you/want/to/keep/component/classes/"
4    }
5}

... and then update Composer's autoload references by running composer dump-autoload in your terminal.

Preventing layouts, partials & components from rendering

Since it's important that layouts, partials and components are never rendered on their own, you need to be able to tell Jigsaw when a file shouldn't be rendered.

To prevent a file or folder from being rendered, simply prefix it with an underscore:

source
_assets
_layouts
master.blade.php
assets
index.blade.php
...

Jigsaw gives you a /_layouts directory by default, but you can create any files or directories you need; anything prefixed with an underscore will not be rendered directly to /build_local.

For example, if you wanted a place to store all of your partials, you could create a directory called _partials:

source
_assets
_layouts
_partials
footer.blade.php
header.blade.php
assets
index.blade.php
...

Since the _partials directory starts with an underscore, those files won't be rendered when you generate your site, but will still be available to @include in your other templates.

Extending Blade with custom directives

Jigsaw gives you the ability to extend Blade with custom directives, just as you can with Laravel. To do this, create a blade.php file at the root level of your Jigsaw project (at the same level as config.php), and return an array of directives keyed by the directive name, each returning a closure.

For example, you can create a custom @datetime($timestamp) directive to format a given integer timestamp as a date in your Blade templates:

blade.php

1return [
2    'datetime' => function ($timestamp) {
3        return '<?php echo date("l, F j, Y", ' . $timestamp . '); ?>';
4    }
5];

Alternatively, the blade.php file receives a variable named $bladeCompiler, which exposes an instance of \Illuminate\View\Compilers\BladeCompiler. With this, you can create custom Blade directives, aliased components, named @include statements, or other extended Blade control structures:

blade.php

 1<?php
 2 
 3/** @var \Illuminate\View\Compilers\BladeCompiler $bladeCompiler */
 4 
 5$bladeCompiler->directive('datetime', function ($timestamp) {
 6    return '<?php echo date("l, F j, Y", ' . $timestamp . '); ?>';
 7});
 8 
 9$bladeCompiler->aliasComponent('_components.alert');
10 
11$bladeCompiler->include('includes.copyright');

page.blade.php

 1<!-- Before -->
 2 
 3@component('_components.alert')
 4    Pay attention to this!
 5@endcomponent
 6 
 7@include('_partials.meta.copyright', ['year' => '2018'])
 8 
 9<!-- After -->
10 
11@alert
12    Pay attention to this!
13@endalert
14 
15@copyright(['year' => '2018'])

Specifying Blade hint paths

To use Blade hint paths/namespaces in your markup (for example, email:components::section), specify the path to the directory using the viewHintPaths key in config.php:

config.php

1<?php
2 
3return [
4    'viewHintPaths' => [
5        'email:templates' => __DIR__.'/source/_layouts',
6        'email:components' => __DIR__.'/source/_components',
7        'email:partials' => __DIR__.'/source/_partials'
8    ]
9];