Views, layouts, and partials
Render escaped data with Velvet, compose templates, and distinguish full views from safe content.
On this page
Render a view with explicit data
Application templates live under user/views by default and end in .velvet.php. Dot notation maps to folders: notes.index resolves notes/index.velvet.php.
Create user/views/notes/index.velvet.php:
<h1>{{ $title }}</h1>
<ul>
@foreach($notes as $note)
<li>{{ $note['title'] }}</li>
@endforeach
</ul>
Pass the values from a controller or route handler:
use Anvyr\Loom\Http\Response;
$response = Response::html(view('notes.index', [
'title' => 'Field notes',
'notes' => [['title' => 'A page in a file.']],
]));
view() returns a string; wrap it in an HTTP response when returning it from a handler. Template variables are the data keys you pass, plus shared engine variables. Ordinary PHP template execution is trusted application code, not an untrusted text sandbox.
Escape by default
{{ $title }} HTML-escapes the result. {!! $html !!} writes raw HTML and should only receive markup whose trust and sanitization you control. @{{ $title }} emits literal double-brace syntax without evaluating it in a full template.
<p>{{ $name }}</p>
<div>{!! $trustedHtml !!}</div>
<code>@{{ clientValue }}</code>
The example tests pass <script>alert(1)</script> as name and verify it becomes text, while the explicitly trusted HTML remains markup.
Share a layout
Create user/views/layouts/notes.velvet.php:
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>@yield('title', 'Notes')</title></head>
<body>
@yield('content')
@stack('scripts')
</body>
</html>
Create user/views/notes/show.velvet.php:
@extends('layouts.notes')
@section('title')Field note@endsection
@section('content')
@include('partials.note', ['label' => $title])
@endsection
@push('scripts')<script src="/notes.js" defer></script>@endpush
And user/views/partials/note.velvet.php:
<article><h1>{{ $label }}</h1></article>
Render notes.show with a title value. Partials inherit parent data; explicitly passed data overrides matching keys. @section fills a layout's @yield, while @push appends to a named @stack. Missing templates and missing layouts raise an exception rather than rendering a substitute.
Namespaces and module views
Modules can call loadViewsFrom($path, 'notes') from a BaseModule entry class. The engine also exposes namespace($name, $path) directly. A registered view namespace is rendered as notes::index.
Resolution checks application view overrides before the registered namespace path. For notes::index, the application can override user/views/notes/index.velvet.php while the module keeps its default template in its own view directory.
Forms and supported directives
Full views support @if, @elseif, @else, @foreach, @for, @while, @isset, @empty, and @unless, together with their matching ending directives. Composition uses @extends, @section, @yield, @include, @push, and @stack. @php blocks execute PHP.
@csrf emits the CSRF hidden field; @method('DELETE') emits a method override field. A form still needs the corresponding route and middleware. Outputting the field does not by itself install CSRF protection on a route.
Page layouts and safe content differ
The file-backed page controller first renders the page body, then passes that rendered content and the page object to layouts/<layout>. A page layout typically uses {!! $content !!} for the already rendered body. That flow differs from a child application view using @extends.
Untrusted page content uses ViewEngine::safe(): it strips PHP blocks, changes raw echoes to escaped echoes, and supports a smaller set of conditional/foreach directives. It is not the full view engine and is not a general expression sandbox. Set trusted: true only for page files you control that need full template behavior.
Compiled view files are cached by source path and modification time. Deploy source changes and manage writable cache storage; template variables are supplied at render time.
Verified against ViewEngine, its layout tests, and PageController. Every Velvet block above is also tested as literal code in this documentation page.