Kirby Blade Templates

plugin
template
blade

#1

Laravel Blade template component for Kirby CMS.

Blade is the simple, yet powerful templating engine provided by Laravel. Unlike other popular PHP templating engines, Blade does not restrict you from using plain PHP code in your views. In fact, all Blade views are compiled into plain PHP code and cached until they are modified, meaning Blade adds essentially zero overhead to your site.

Blade view files use the .blade.php file extension and are typically stored in the site/templates directory.

This component extends Kirby’s built-in templating engine. Any regular .php template will continue to works as usual.

Basic Usage

Blade Templates works out of the box without requiring any configuration. You just need to add .blade.php files to site/templates.

Defining a Layout

Blade uses the concept of template inheritance and sections. You can define master layouts which are extended by child views. Check out how a master layout would look like in Kirby:

<!-- Stored in site/templates/layouts/master.blade.php -->

<html>
    <head>
        <title>@yield('title') | {{ $site->title() }}</title>
    </head>
    <body>
        <h1>@yield('title')</h1>

        <div class="sidebar">
            @section('sidebar')
            <h2>Description:</h2>
            @show
        </div>

        <div class="container">
            @yield('content')
        </div>
    </body>
</html>

As you can see, this file contains typical HTML markup. However, take note of the @section and @yield directives. The @section directive, as the name implies, defines a section of content, while the @yield directive is used to display the contents of a given section.

Extending a Layout

When defining a child view, use the Blade @extends directive to specify which layout the child view should “inherit”. Views which extend a Blade layout may inject content into the layout’s sections using @section directives. Remember, as seen in the example above, the contents of these sections will be displayed in the layout using @yield:

<!-- Stored in site/templates/default.blade.php -->

@extends('layouts.master')

@section('title', $page->title())

@section('sidebar')
    @parent

    {{ $page->description()->kirbytext() }}
@endsection

@section('content')
    {{ $page->text()->kirbytext() }}
@endsection
Show rendered HTML

<html>
    <head>
        <title>Services | Company Name</title>
    </head>
    <body>
        <h1>Services</h1>

        <div class="sidebar">
            <h2>Description:</h2>
            <p>Service description</p>
        </div>

        <div class="container">
            <p>Sum inusa commolu ptatent mossend elignam volenim quiam quiaspe riaessenis plisita ecaboribus.</p>

            <p>Ecaborenis molupta spiene recepudam, quostium reprem rereprat.</p>
        </div>
    </body>
</html>

Displaying Data

You may display data passed to your Blade views by wrapping the variable in curly braces.

{{ $page->title() }}

You don’t have use the html() method to escape special characters because Blade’s {{ }} statements are automatically sent through Kirby’s html() helper function to prevent XSS attacks. The example above is the same as:

<?php echo html($page->title()) ?>

If you do not want your data to be escaped, you may use the following syntax:

{!! snippet('posts', $posts, true) !!}

While this example shows how you can use a regular snippet with Blade, take note that Blade’s @include directive allows you to include a Blade view from within another view. All variables that are available to the parent view will be made available to the included view as well.


Check out the plugin on Github!


#2

without having read much about blade… what makes it better to use than kirby modules or php mustache? I read the part about the zero overhead.


#3

Blade is a superior alternative (in my opinion) to Twig, Pug (Jade), Mustache, etc. It has nothing to do with the Kirby Modules plugin.

From the docs:

Blade is the simple, yet powerful templating engine provided by Laravel. Unlike other popular PHP templating engines, Blade does not restrict you from using plain PHP code in your views. In fact, all Blade views are compiled into plain PHP code and cached until they are modified, meaning Blade adds essentially zero overhead to your site.

Besides many useful directives like @if, @foreach, @each, @forelse, @unless, @inlude, and so on, it allows you to easily display data by wrapping the variable in curly braces:

{{ $page->title() }}

Is the same as:

<?php echo $page->title()->html() ?>

So with Blade you can have this expressive syntax while being able to continue using plain PHP, if needed. Blade comes with little to zero performance overhead because it’s views are always cached in plain PHP.

There’s a lot more helpful directives, check out the docs. It’s really worth taking a look and trying out for yourself.


#4

In my opinion, there are three main reasons for using a templating language with Kirby:

  1. Syntax that might be less verbose than PHP templating.
  2. Features such as extending a base template, or on-by-default escaping.
  3. Familiarity, if you’re also working with codebases which already use that templating language (Laravel for Blade, Symfony or Drupal 8 for Twig).

If you don’t like the different syntax and are not already familiar with a given templating language, then there is not much appeal. Good to have options though.


#5

Just one question with this - what happens to snippets? How do i use those? Do i have rename those as a Blade file?


#6

My Bad - didnt notice your note at the bottom about snippets. They work fine if the snippet contains plain html, however if it contains Kirby code, it throws an exception. What am i doing wrong? Do i need to convert the snippets code to Blade style?


#7

i moved the snippets to layouts/partials and works great :ok_hand: or https://github.com/pedroborges/kirby-blade-template#displaying-data


#8

Hi @pedroborges,
thanks for your plugin, I would like to give it a try.
But I cant get it running.
The debugger always returns:

 Exception
 The template could not be found 

I have one further questions?

  1. how does the blade template works with controllers
    thanks for help

#9

@pedroborges,
Sorry my mistake, there still was a twig plugin in the plugins folder and although not registered it was interfering with blade. But still asking myself how to work with controllers or where to put some logic instead?


#10

The same thing happens to me, how did you solve it?


#11

Could you open an issue on https://github.com/fvsch/kirby-twig for the “twig plugin interferring although not registered”, to describe how it was set up? This might be a bug, or at least interesting information for improving the plugin’s API.

Regarding controllers, given how Kirby’s Template component works (and that both Twig and Blade plugins are extending it) your Kirby controllers should run normally, and if they return data this data should be available in the .blade.php templates.


#12

Yes Controllers run normally, but you need to return an array:
either this way @fvsch shows in his documentation for twig,
https://github.com/fvsch/kirby-twig/blob/master/doc/guide.md:

<?php // site/controllers/blog.php

return function($site, $pages, $page) {
  $data = [];
  $data['posts'] = $site->find('blog')->children()
    ->filterBy('status', 'published')
    ->sortBy('date', 'desc');
  return $data;
}; 

or this way:

<?php // site/controllers/blog.php

return function($site, $pages, $page) {
  $posts = $site->find('blog')->children()
    ->filterBy('status', 'published')
    ->sortBy('date', 'desc');

  return compact('posts');
};

@fvsch I just did open an issue on https://github.com/fvsch/kirby-twig.


#13

I love the idea of using a templating engine.

Has anyone bothered to translate the langkit to blade? Or would it be of use for anyone if I would do that?


#14

Blade Template plugin was still tagged as beta even thought it’s been stable for almost a year now, so I just tagged v1.0.0.

A nice addition to this release is you can add custom Blade directives via the blade.directives option:

c::set('blade.directives', [
    'kirbytext' => function ($text) {
        return "<?php echo kirbytext($text) ?>";
    }
]);

All directives registered with this option will be available in your Blade views:

@kirbytext("This is Kirby's special flavor of **markdown**.")

Checkout the changelog.