Templates

Introduction

Doorstep uses the powerful Blade templating engine, provided by Laravel. As well as allowing normal PHP code (within tags), Blade has a simple syntax that is compiled into plain PHP code and cached. You can learn more about Blade on the Laravel Docs.

There are some basic Blade syntax rules:

  • All files end in .blade.php
  • Double "Curly" braces are used to echo variables Hello {{ $name }}
  • Echoing unescaped variables is done like Hello {!! $name !!}
  • @extends('layouts.default') at the top of the file uses that file as the layout @include('partials.header') injects another view (partial) within the current template

Inheritance

Doorstep is set up with some core templates and views as part of the framework. By default these are not included in your application, but you can view these in the folder vendor/doorstep/framework/resources/views.

You should never change any code in the vendor directory since this will be overwritten when you update the framework. Instead, Doorstep provides a convenient command that automatically copies all templates into your own project. Any files that exist in your resources/views directory are used before looking inside the framework.

To copy the Doorstep views run the command (within your main directory)

php artisan doorstep:views

You can pass --force on the end of the command to overwrite existing files.

Of course, any views which you don't intend to customise you can simply delete from your resources/views directory, and Doorstep will fallback to the core versions.

Layouts

In Blade, a master layout file can be used to set up the 'wrapper' for the child views. This usually contains the top and bottom html tags as well including any other sections (e.g. header and footer).

By default, Doorstep uses a main resources/views/layouts/default.blade.php file. This includes a separate header partial as well as a partials for css and javascript files.

Other views will extend this layout and inject their content into the layout's content section. For instance,

@extends('layouts.default')

@section('content')
    <div id="welcome">
        <h2>Welcome!</h2>
    </div>
@stop

You are welcome to modify the default layout after copying to your app's directory (see above), or you can create new layouts for different pages. If you rename the layout or create other layout files, be sure to update the @extends tag at the top of each separate view.

Partials

'Partials' are simply additional Blade view files which are included within other views or layouts.

Doorstep makes use of partials for repeating template code or sections that should be extracted from the main file.

For instance, the header.blade.php file is included in the master layout file and can be edited to change the markup for the top of the website.

Assets

All public-facing files, for instance css, javascript and images, should be stored in the public directory from the root install.

Doorstep has two partials that are included in the default, master layout - assets.blade.php and scripts.blade.php. You can modify these to include your own css and javascript files like so:

<link href="{{ asset('assets/default/css/style.css') }}" rel="stylesheet">

In the example above, the asset helper function prepends the full URL of your website, so would render as something like:

<link href="http://example.com/assets/default/css/style.css" rel="stylesheet">

Using this example, there would be an assets folder within your public directory containing the required files and subfolders.

Helper Methods

Laravel comes with various helpful methods that can be called inside your views, and these are used throughout Doorstep

The most common are listed below, but you can see a full list at the Laravel Docs.

asset()

Generate a URL for an asset using the current scheme of the request (HTTP or HTTPS):

$url = asset('img/photo.jpg');

url()

The url function generates a fully qualified URL to the given path:

url('properties')

auth()

The auth function returns an authenticator instance. You may use it instead of the Auth facade for convenience:

$user = auth()->user();

config()

The config function gets the value of a configuration variable. The configuration values may be accessed using "dot" syntax, which includes the name of the file and the option you wish to access. A default value may be specified and is returned if the configuration option does not exist:

$value = config('app.timezone');

$value = config('app.timezone', $default);