Edge Templates
Edge is the template engine Windwalker uses for views. This page covers where templates live, how layouts inherit from each other, how partials are included, how output is escaped, and which directives Windwalker adds. Component tags are described in View Components.
For a quick syntax lookup, see Edge Components, Template Syntax, and Components.
Minimal Usage
Echo a value with . The value is escaped:
<h1>{{ $title }}</h1>Complete Example
A list page that uses a layout, a partial, a stack, and a permission check:
{{-- views/post/list.edge.php --}}
@extends('layouts.main')
@section('title', 'Posts')
@section('content')
<h1>{{ $title }}</h1>
@can('post.create', $user)
<a href="{{ $createUrl }}">New post</a>
@endcan
@foreach ($posts as $post)
@include('post.card', ['post' => $post])
@endforeach
@endsection
@push('scripts')
<script src="/js/post-list.js"></script>
@endpushTemplate Placement
Templates use the .edge.php extension. A layout name uses dots in place of folder separators, so layouts.main is found at layouts/main.edge.php inside a views folder.
Layout paths come from the renderer.paths and renderer.namespaces config keys. See Renderer for the search order.
Keep a page's templates close to its ViewModel:
src/Views/Post/
PostListViewModel.php
list.edge.phpLayout Inheritance
Extending a Layout
Use @extends to render a parent layout after the child template. The child defines content with @section, and the parent places it with @yield:
{{-- views/layouts/main.edge.php --}}
<html>
<head>
<title>@yield('title')</title>
</head>
<body>
@yield('content')
</body>
</html>{{-- views/post/list.edge.php --}}
@extends('layouts.main')
@section('title', 'Posts')
@section('content')
<h1>Posts</h1>
@endsectionSection Forms
Use @section(name, value) for a short inline value. It takes no block and no @endsection:
@section('title', 'Posts')Use @section(name) with @endsection for block content.
Default Content and Parent Content
Use @yield(name, default) in a parent to show a fallback when a child does not define the section:
@yield('sidebar', '<p>Default sidebar</p>')Use @show to end a section and yield it in the same place. Use @parent inside a child section to render the parent's content at that point:
@section('sidebar')
@parent
<p>Extra links for this page.</p>
@endsectionUse @overwrite instead of @endsection to replace the parent's section without rendering the parent's content.
INFO
A child template's variables are passed to the parent layout, so in a layout reads the child's $title.
Partials
Including a Partial
Use @include(name, data) to render a partial where it appears. The partial receives the data array and the variables of the including template:
@include('post.card', ['post' => $post])Optional Partials
Use @includeIf(name, data) to render nothing when the partial does not exist:
@includeIf('post.banner', ['post' => $post])Rendering a Collection
Use @each(name, items, iterator, empty) to render a partial once for each item. The iterator name sets the variable each item has in the partial. The optional fourth argument names a partial for an empty list:
@each('post.card', $posts, 'post', 'post.empty')TIP
Pass only the variables a partial needs. This keeps the partial reusable and easy to test.
Escaping
Escaped Output
escapes the value for HTML. Use it for all user-supplied text:
<p>{{ $post->title }}</p>Raw Output
{!! !!} prints the value without escaping:
{!! $post->renderedBody !!}WARNING
{!! !!} prints the value without escaping. Use it only with HTML that your code has already produced or sanitized, or the page is open to cross-site scripting.
Literal Tags
Put @ before a tag to print it as text, such as @.
Stacks
Pushing Content
Use @push(name) and @endpush to add content to a named stack from anywhere in the template tree:
@push('scripts')
<script src="/js/post-list.js"></script>
@endpushRendering a Stack
Use @stack(name) where the content should appear, such as the end of the layout's <head> or <body>:
@stack('scripts')Pushing Once
Use @pushOnce(name, id) to add the content only the first time that id is pushed. This is useful when a partial that needs a script is rendered many times in one page:
@pushOnce('scripts', 'chart-js')
<script src="/js/chart.js"></script>
@endPushOnceAnonymous Components
Use an <x-name> tag to render a template as a component. The tag name resolves to a view the Edge loader can find under that name:
<x-alert />Components that need a PHP class or a registered short name are described in View Components.
Windwalker Directives
Windwalker registers these directives in its Edge extension (core/src/Core/Renderer/Edge/WindwalkerExtension.php).
Language
@lang(key): translate a language key.@translate(key): an alias of@lang.@choice(...): choose a plural form for a language key.
<h2>@lang('post.list.title')</h2>Forms and Security
@csrfand@formToken: output the CSRF token field. They take no arguments.@nonce: output the Content Security Policy nonce attribute. It takes no arguments.
<form method="post">
@csrf
<button type="submit">Save</button>
</form>Attributes
@attr renders an array of HTML attributes, so you do not have to write each attribute by hand. Pass an array, or a name and a value:
<input @attr(['type' => 'checkbox', 'name' => 'agree'])>
<button @attr('disabled', $saving)>Save</button>
<div @attr([
'class' => 'card',
'data-id' => $post->id,
'hidden' => false,
])>
...
</div>The values follow these rules:
trueoutputs a bare attribute, such asdisabled.falseandnullomit the attribute.- Arrays and objects are encoded as JSON.
- Other values are escaped.
TIP
Use @attr for conditional attributes instead of wrapping the whole tag in @if.
Permissions
@can(policy, user, ...args)and@endcan: render the block when the user is allowed.@cannot(policy, user, ...args)and@endcannot: render the block when the user is not allowed.
The second argument is the user. Any further arguments are passed to the policy:
@can('post.edit', $user, $post)
<a href="{{ $editUrl }}">Edit</a>
@endcan
@cannot('post.edit', $user, $post)
<p>You cannot edit this post.</p>
@endcannotMessages
@messages: render the application's flash messages.
Debugging
@dd(...): dump values and stop.@die: stop the request.@debug/@enddebug: render the block only in debug mode.
WARNING
@dd and @die stop the request. Remove them before the page reaches production.
Related
- Renderer: the render API and global variables.
- View Components: class and anonymous components.
- Asset Management: loading CSS and JavaScript.