Basics / Views

Template Engine

Archery features a powerful, Blade-inspired templating engine that allows you to create dynamic, reusable HTML documents with a clean and expressive syntax.

Displaying Data

Archery templates use curly braces to display data passed to the view.

Escaped Output

By default, Archery escapes all variables to protect against cross-site scripting (XSS) attacks.

NOTE: Use double curly braces syntax.

Hello, { name }.

Unescaped Output

If you need to render raw HTML, use the "bang" syntax. Use this with caution!

{!! raw_html_content !!}

Layouts and Sections

Layouts allow you to define a common structure for multiple pages (e.g., a header and footer).

Defining a Layout

In your layout file (e.g., layouts/app.html):

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

Extending a Layout

In your page view:

@layout('layouts.app')

@section('content')
    <h1>Welcome to Archery</h1>
    <p>This content is injected into the layout's yield.</p>
@endsection

Control Structures

Archery provides familiar directives for conditionals and loops.

Conditionals

@if(user.is_admin)
    <p>Welcome, Admin!</p>
@else
    <p>Welcome, { user.name }!</p>
@endif

Loops

<ul>
    @foreach(user in users)
        <li>{ user.name }</li>
    @endforeach
</ul>

Including Subviews

Use the @include directive to insert a partial view into another.

@include('partials.header')

<!-- Passing additional data -->
@include('partials.alert', {"type": "success", "message": "Done!"})

Forms and CSRF

When defining POST forms in Archery views, include the @csrf directive to generate a hidden token input required for security.

<form method="POST" action="/profile">
    @csrf
    ...
</form>

Rendering Views

From your route handler or controller, return a view response:

router.get('/', (req) async {
  return req.view('home', {'name': 'Archer'});
});

Archery looks for templates in lib/src/http/views/ and expects files to have an .html extension. Use dot-notation to reference nested files (e.g., req.view('auth.login') maps to lib/src/http/views/auth/login.html).