Ekit Template Syntax — Developer Guide (DSL Reference)

This guide documents the Ekit templating language, based on Handlebars and extended with domain-specific helpers, data sources, and context-aware IntelliSense. The editor assists you by automatically suggesting helpers, datasources, fields, and i18n keys while you type.

---

1. Datasources (ekdata)

All template data is exposed through the global object ekdata.

Datasources are declared in the YAML frontmatter:

---
datasources:
  articles:
    from: articles
    limit: 10
---

Usage:

{{ekdata.articles}}

IntelliSense: after typing ekdata. the editor automatically suggests all available datasources.

---

2. Looping with #each

Iterate through a list of records:

{{#each ekdata.articles}}
  <h2>{{this.title}}</h2>
  <p>{{this.description}}</p>
{{/each}}

• this refers to the current record in the loop.

Field access:

{{this.author}}
{{this.first-name}}

Note: if a field name contains special characters (like -), and you encounter parsing issues, you can use:

{{lookup this "first-name"}}

IntelliSense: after typing this. the editor proposes all fields of the current datasource.

---

3. Accessing a Single Record (#single)

Declare a datasource returning a single record using either a slug or a uid.

Using a slug (recommended for SEO-friendly URLs):

datasources:
  featured-article:
    from: articles
    slug: "{{params.slug}}"

Slugs are typically used with route parameters (e.g. {{params.slug}}) to resolve dynamic pages.

Using a UID:

datasources:
  featured-article:
    from: articles
    uid: "ARTICLE_UID"

Usage:

{{#single ekdata.featured-article}}
  <h1>{{this.title}}</h1>
  <p>{{this.description}}</p>
{{/single}}

• Inside the block, this represents the single resolved record.

---

4. Partials ({{> partialName}})

Include reusable template fragments:

{{> header}}
{{> components/article-card}}

With context:

{{> card this}}

IntelliSense: available partials are automatically suggested after typing {{>.

---

5. Public Assets ({{ekasset "path"}})

Resolve a public/static asset path:

<img src="{{ekasset "images/logo.png"}}" alt="Logo">

✨ IntelliSense

• All available public assets are automatically suggested by the editor.
• After typing {{ekasset " the editor proposes existing asset files and paths.
• Adding or removing an asset updates the suggestions instantly.

---

6. Translations / i18n ({{ektrans "key"}})

ektrans displays a translated string from the i18n dictionaries (e.g. fr.json, en.json).

Usage

{{ektrans "WELCOME"}}

How it works

• The key is looked up in the active language file.
• The helper returns the translated string.

✨ IntelliSense

• All available translation keys are automatically suggested by the editor.
• Adding a new key to fr.json (or any language file) makes it immediately available in IntelliSense after {{ektrans ".

Example

{
  "WELCOME": "Bienvenue",
  "CTA_START": "Commencer"
}

<h1>{{ektrans "WELCOME"}}</h1>
<button>{{ektrans "CTA_START"}}</button>

---

7. Database Assets ({{ekdbasset this.field}})

ekdbasset resolves an asset stored in the database (image, file, etc.) from an asset field of the current record.

Recommended usage

<img src="{{ekdbasset this.image}}" alt="">

Expected parameter

• An asset field object (for example this.image, this.cover, this.file).
• The helper receives the resolved object directly (not just an ID).

Example inside a loop

{{#each ekdata.articles}}
  <img width="200" src="{{ekdbasset this.cover-image}}" alt="">
{{/each}}

✨ IntelliSense (context-aware)

• After typing {{ekdbasset this. the editor proposes the fields of the current record.
• You can restrict suggestions to asset-type fields for a cleaner authoring experience.

---

8. Displaying Values

{{this.title}}
{{this.first-name}}

---

9. YAML Frontmatter Reference

---
layout: default          # layouts/layout.hbs — or the name of another file in layouts/

metas:
  title: '{{record.title}}'
  description: '{{i18n.HOME_DESCRIPTION}}'
  og:
    type: article

datasources:
  articles:
    from: articles
    limit: 20
    sort:
      field: date
      dir: desc          # asc | desc

  featured-article:
    from: articles
    uid: "12345"

  answer:                # data from a server-side Method
    type: method
    method: open-ai-answer
    inputs:
      prompt: '{{query.q}}'
---

Key	Description
layout	Layout file of layouts/ (without extension). Omitted or default: layouts/layout.hbs. An unknown name falls back to layouts/layout.hbs.
datasources	Data available as ekdata.<alias> — see Advanced datasource options and Methods.
metas	SEO tags: title, description, canonical, robots, og.*, twitter.*, alternates.hreflang.
cache.ttlSeconds	Lifetime of the cached page, in seconds (default 300, 0 = never cached) — see Page cache.

The editor completes and checks this block as you type — see Editor IntelliSense.

---

10. Complete Example

YAML

---
layout: default

datasources:
  authors:
    from: authors
    limit: 10

  featured-author:
    from: authors
    uid: "69381978dbccb28748829f17"
---

Template

<h1>Authors</h1>

<ul>
  {{#each ekdata.authors}}
    <li>{{this.first-name}} {{this.lastName}}</li>
  {{/each}}
</ul>

<h2>Featured</h2>

{{#single ekdata.featured-author}}
  <strong>{{this.first-name}}</strong> — {{this.lastName}}
{{/single}}

---

11. Summary of Ekit Helpers

Helper	Purpose	Example
#each	Loop through a datasource	{{#each ekdata.articles}}…{{/each}}
#single	Access a single record	{{#single ekdata.featured}}…{{/single}}
ekasset	Resolve public asset path	{{ekasset "images/logo.png"}}
ekdbasset	Resolve database asset (image/file)	src="{{ekdbasset this.image}}"
ektrans	Translate an i18n key	{{ektrans "WELCOME"}}
> partial	Include a partial template	{{> header}}
this	Current record in context	{{this.title}}

All helpers (text, dates, logic, JSON…) and the variables available in templates are listed in the Helpers & variables reference.

---

Editor assistance: Ekit provides a guided authoring experience. Helpers, datasources, fields, partials, and i18n keys are automatically suggested by IntelliSense, making templates easier to write and safer to maintain.