Template Context API

Every admin page receives a structured context object built by the ContextBuilder. When overriding templates, you can access any of these variables in your Handlebars templates.

Top-Level Keys

Base Context (Every Page)

crap — App Metadata

{{crap.version}}      {{!-- "0.1.0" --}}
{{crap.build_hash}}   {{!-- Git commit hash at build time --}}
{{crap.dev_mode}}     {{!-- true/false --}}
{{crap.auth_enabled}} {{!-- true if any auth collection exists --}}

page — Page Info

{{page.title}}  {{!-- "Edit Post", "Dashboard", etc. --}}
{{page.type}}   {{!-- "collection_edit", "dashboard", etc. --}}

{{#each page.breadcrumbs}}
  {{#if this.url}}
    <a href="{{this.url}}">{{this.label}}</a>
  {{else}}
    <span>{{this.label}}</span>
  {{/if}}
{{/each}}

Page Types

nav — Navigation

Available on all authenticated pages. Auth pages use ContextBuilder::auth() which does not include nav.

{{#each nav.collections}}
  <a href="/admin/collections/{{this.slug}}">{{this.display_name}}</a>
  {{!-- Also available: this.is_auth, this.is_upload --}}
{{/each}}

{{#each nav.globals}}
  <a href="/admin/globals/{{this.slug}}">{{this.display_name}}</a>
{{/each}}

Each nav collection entry:

Each nav global entry:

user — Current User

Present when the user is authenticated (JWT session valid). Absent on auth pages and error pages.

{{#if user}}
  Logged in as {{user.email}} ({{user.collection}})
{{/if}}

Collection Pages

collection — Collection Definition

Available on all collection page types (collection_items, collection_edit, collection_create, collection_delete, collection_versions).

{{collection.slug}}
{{collection.display_name}}
{{collection.singular_name}}
{{collection.title_field}}
{{collection.timestamps}}       {{!-- boolean --}}
{{collection.is_auth}}          {{!-- boolean --}}
{{collection.is_upload}}        {{!-- boolean --}}
{{collection.has_drafts}}       {{!-- boolean --}}
{{collection.has_versions}}     {{!-- boolean --}}

collection.admin

{{collection.admin.use_as_title}}          {{!-- field name or null --}}
{{collection.admin.default_sort}}          {{!-- e.g., "-created_at" or null --}}
{{collection.admin.hidden}}                {{!-- boolean --}}
{{collection.admin.list_searchable_fields}} {{!-- array of field names --}}

collection.upload

null unless the collection has upload enabled.

{{#if collection.upload}}
  Accepts: {{collection.upload.mime_types}}
  Max size: {{collection.upload.max_file_size}}
  Thumbnail: {{collection.upload.admin_thumbnail}}
{{/if}}

collection.versions

null unless the collection has versioning enabled.

{{#if collection.versions}}
  Drafts: {{collection.versions.drafts}}
  Max versions: {{collection.versions.max_versions}}
{{/if}}

collection.auth

null unless the collection is an auth collection.

{{#if collection.auth}}
  Local login: {{#if (not collection.auth.disable_local)}}enabled{{/if}}
  Email verification: {{collection.auth.verify_email}}
{{/if}}

collection.fields_meta

Array of raw field definitions. Useful for JavaScript conditional logic or embedding metadata.

{{#each collection.fields_meta}}
  {{this.name}} — {{this.field_type}}
  Required: {{this.required}}, Localized: {{this.localized}}
  Label: {{this.admin.label}}
{{/each}}

{{!-- Serialize to JSON for JavaScript --}}
<script>
  const fields = {{{json collection.fields_meta}}};
</script>

Each entry in fields_meta:

Dashboard

Page type: dashboard

Additional keys:

{{#each collection_cards}}
  <a href="/admin/collections/{{this.slug}}">
    {{this.display_name}} ({{this.count}} items)
  </a>
{{/each}}

{{#each global_cards}}
  <a href="/admin/globals/{{this.slug}}">{{this.display_name}}</a>
{{/each}}

Collection card fields: slug, display_name, singular_name, count, last_updated, is_auth, is_upload, has_versions.

Global card fields: slug, display_name, last_updated, has_versions.

Collection Items (List)

Page type: collection_items

Additional keys beyond collection:

docs

{{#each docs}}
  <tr>
    <td>{{this.title_value}}</td>
    <td>{{this.status}}</td>
    <td>{{this.created_at}}</td>
    <td>{{this.updated_at}}</td>
    {{#if this.thumbnail_url}}
      <td><img src="{{this.thumbnail_url}}" /></td>
    {{/if}}
  </tr>
{{/each}}

Each doc:

pagination

{{#if pagination.has_prev}}
  <a href="{{pagination.prev_url}}">Previous</a>
{{/if}}
<span>Page {{pagination.page}} of {{pagination.total_pages}}</span>
{{#if pagination.has_next}}
  <a href="{{pagination.next_url}}">Next</a>
{{/if}}

Collection Edit

Page type: collection_edit

Additional keys beyond collection:

document

{{document.id}}
{{document.created_at}}
{{document.updated_at}}
{{document.status}}        {{!-- "published" or "draft" --}}

{{!-- Raw field values --}}
{{document.data.title}}
{{document.data.category}}

Draft loading: When a collection has drafts enabled and the latest version is a draft, the edit page loads the document from the draft version snapshot. This means document.data contains the draft values, including block and array data — not the published main-table values.

fields

Processed field context objects used by the {{render_field}} helper or custom form rendering. See Field Context below.

versions

{{#each versions}}
  v{{this.version}} — {{this.status}}
  {{#if this.latest}} (latest) {{/if}}
  Created: {{this.created_at}}
{{/each}}
{{#if has_more_versions}}
  <a href="/admin/collections/{{collection.slug}}/{{document.id}}/versions">View all</a>
{{/if}}

Each version entry: id, version (number), status ("published" or "draft"), latest (boolean), created_at.

upload

Present only on upload collection edit/create pages.

{{#if collection.is_upload}}
  {{#if upload.preview}}
    <img src="{{upload.preview}}" />
  {{/if}}
  {{#if upload.info}}
    {{upload.info.filename}}
    {{upload.info.filesize_display}}  {{!-- e.g., "2.4 MB" --}}
    {{upload.info.dimensions}}        {{!-- e.g., "1920x1080" --}}
  {{/if}}
  {{#if upload.accept}}
    <input type="file" accept="{{upload.accept}}" />
  {{/if}}
{{/if}}

Collection Create

Page type: collection_create

Same structure as collection edit, with these differences:

• editing is false
• document is absent
• versions, has_more_versions are absent
• Password field is added for auth collections (required)

Collection Delete

Page type: collection_delete

Collection Versions

Page type: collection_versions

Full version history page with pagination.

Collection List

Page type: collection_list

Each entry: slug, display_name, field_count.

Global Edit

Page type: global_edit

global

{{global.slug}}
{{global.display_name}}
{{#each global.fields_meta}}
  {{this.name}} — {{this.field_type}}
{{/each}}

Auth Pages

Auth pages use a minimal context builder (ContextBuilder::auth()) — no nav or user.

Login (auth_login)

Forgot Password (auth_forgot)

Reset Password (auth_reset)

Error Pages

Error pages receive the base context (crap, nav, page) plus:

Page types: error_403, error_404, error_500.

<h1>{{page.title}}</h1>
<p>{{message}}</p>

Locale Context

When localization is enabled in crap.toml, edit/create pages receive additional keys merged into the top level:

{{#if has_locales}}
  {{#each locales}}
    <option value="{{this.value}}" {{#if this.selected}}selected{{/if}}>
      {{this.label}}
    </option>
  {{/each}}
{{/if}}

Each locale entry: value (e.g., "en"), label (e.g., "EN"), selected (boolean).

When editing a non-default locale, non-localized fields are rendered as readonly (locale-locked).

Editor Locale (Content Locale)

In addition to the UI translation locale (has_locales/current_locale/locales), edit/create pages also receive content editor locale variables when locale is enabled:

These control which content locale is being edited, separate from the admin UI translation locale.

Field Context

The fields array contains processed field context objects, one per field. These are used by {{{render_field field}}} or can be iterated manually.

Common Fields

Every field context object has:

Select Fields

Additional keys:

Each option: label, value, selected (boolean).

Checkbox Fields

Date Fields

Relationship Fields

Each option: value (document ID), label (title field value), selected (boolean).

Upload Fields

Each option: value, label, selected, thumbnail_url (if image), is_image (boolean), filename.

Group Fields

Sub-field name is formatted as group__subfield (double underscore).

Array Fields

Each row: index (integer), sub_fields (array of field contexts with indexed names like items[0][title]), custom_label (string/null — computed label from row_label or label_field).

The <fieldset> element includes a data-label-field attribute when label_field is set, enabling JavaScript to update row titles live as the user types.

Blocks Fields

Each block definition: block_type, label, label_field (string/null — per-block-type label field), fields (array of sub-field contexts).

Each row: index, _block_type, block_label, custom_label (string/null — computed label from row_label, block label_field, or field label_field), sub_fields (array of field contexts with indexed names like content[0][heading]).

Handlebars Helpers

In addition to the standard Handlebars helpers, these custom helpers are available:

Logic Helpers

Comparison Helpers

Utility Helpers

Translation Helper

Supports interpolation:

{{t "welcome"}}                     {{!-- simple lookup --}}
{{t "greeting" name="World"}}       {{!-- replaces {{name}} in translation string --}}

Truthiness

Helpers like not, and, or, and default use Handlebars truthiness:

• Falsy: null, false, 0, "" (empty string), [] (empty array)
• Truthy: everything else (including empty objects {})

Composition

Helpers can be composed as sub-expressions:

{{#if (and (not collection.is_auth) (gt pagination.total 0))}}
  Showing {{pagination.total}} items
{{/if}}

{{#if (or collection.has_drafts collection.has_versions)}}
  This collection supports versioning
{{/if}}

<a href="{{concat "/admin/collections/" collection.slug "/create"}}">New</a>

before_render Hook

You can inject custom data into every admin page context using the before_render hook:

-- init.lua
crap.hooks.register("before_render", function(context)
  context.custom = {
    announcement = "Maintenance tonight at 10pm",
    feature_flags = { new_editor = true },
  }
  return context
end)

Then in your templates:

{{#if custom.announcement}}
  <div class="announcement">{{custom.announcement}}</div>
{{/if}}

{{#if custom.feature_flags.new_editor}}
  {{!-- show new editor --}}
{{/if}}

The before_render hook:

• Fires on every admin page render (GET and POST error re-renders)
• Receives the full template context as a Lua table
• Must return the (possibly modified) context
• Has no CRUD access (no database operations) — keeps it fast
• Use the custom key by convention for injected data
• Can read and modify any context key (not just custom), but modifying built-in keys may break default templates
• On error: logs a warning and returns the original context unmodified

Example: Conditional Navigation

crap.hooks.register("before_render", function(context)
  -- Add environment indicator
  local env = crap.env.get("APP_ENV") or "development"
  context.custom = context.custom or {}
  context.custom.environment = env
  context.custom.is_production = (env == "production")
  return context
end)

{{#if custom.is_production}}
  <div class="env-badge env-badge--production">PRODUCTION</div>
{{else}}
  <div class="env-badge">{{custom.environment}}</div>
{{/if}}

Full Example: Custom List Template

A complete example overriding the items list to add a custom column:

{{!-- <config_dir>/templates/collections/items.hbs --}}
{{#> layout/base}}

<h1>{{page.title}}</h1>

{{#if custom.announcement}}
  <div class="alert">{{custom.announcement}}</div>
{{/if}}

<table>
  <thead>
    <tr>
      <th>Title</th>
      <th>Status</th>
      {{#if collection.is_upload}}<th>Preview</th>{{/if}}
      <th>Updated</th>
    </tr>
  </thead>
  <tbody>
    {{#each docs}}
      <tr>
        <td>
          <a href="/admin/collections/{{../collection.slug}}/{{this.id}}">
            {{this.title_value}}
          </a>
        </td>
        <td>{{this.status}}</td>
        {{#if ../collection.is_upload}}
          <td>
            {{#if this.thumbnail_url}}
              <img src="{{this.thumbnail_url}}" width="40" />
            {{/if}}
          </td>
        {{/if}}
        <td>{{this.updated_at}}</td>
      </tr>
    {{/each}}
  </tbody>
</table>

{{#if pagination.has_prev}}
  <a href="{{pagination.prev_url}}">Previous</a>
{{/if}}
{{#if pagination.has_next}}
  <a href="{{pagination.next_url}}">Next</a>
{{/if}}

{{!-- Embed field metadata for client-side use --}}
<script>
  const collectionDef = {{{json collection}}};
</script>

{{/layout/base}}