Templates

Overview

The Templates module lets you define reusable content templates and render them with dynamic data at runtime. Each template is identified by a human-readable key, supports versioning through automatic new version creation on every update, and declares expected variable fields for validation.

Use templates to generate email bodies, notification messages, document snippets, or any text content that requires dynamic data injection. The module handles template parsing, execution, and version history so you can maintain an audit trail of changes.

A single resource type exists: the Template object. Each template stores its content body, format (HTML, Markdown, or plain text), and a list of field names that the template expects. The module also exposes a dedicated Render endpoint that parses a template and injects data in a single call.

Before You Start

You need at least one access method configured:

• CLI – install the Oblax CLI (obx) and authenticate with obx login. See: Getting Started with the CLI.
• REST API – you need a valid Authorization: Bearer <token> header and a oblax-client-appid header. See: API Authentication & Requests.
• SDK – install the Oblax JavaScript SDK and initialize it with your project credentials. See: SDK Installation & Initialization.

All requests must include the project’s application credentials. The REST API uses oblax-client-appid for the API key and Authorization for the bearer token. The CLI handles these automatically after login.

When to Use

Use the Templates module when you need to:

• Generate email or notification content from reusable templates with dynamic variables
• Maintain version history for content templates across your project
• Separate presentation logic from application code by storing templates externally
• Provide a template editing workflow for non-developer team members through the CLI
• Render the same template structure with different data sets at different points in a workflow

How It Fits

    flowchart LR
  F[Flux Scripts] --> T[Templates]
  A[Auth] --> T
  T --> FM[File Manager]
  T --> N[Notifications]
  T --> FR[Forms]
  

Flux Scripts trigger template rendering from event-driven workflows. Auth supplies user data for personalized template content. Templates feed rendered output into File Manager for storage, Notifications for messaging, and Forms for dynamic document generation.

Works Well With

• Flux Scripts – trigger template rendering from event-driven scripts and use the output in subsequent workflow steps
• Auth – templates can reference authenticated user data for personalized content generation
• File Manager – store rendered template output as files for distribution or archival
• Notifications – use templates as the content source for email and notification messages
• Forms – generate dynamic confirmation pages or response documents from form submissions

Quick Example

The following example shows the full lifecycle of a template: initialization, creation on the platform, and rendering with data.

Creating a template

Create a new template with content and declared fields.

obx app templates init "Welcome Email" --format html
obx app templates push welcome_email_html

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { templates } from "@oblax/templates";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [templates()],
});

const template = await oblax.templates.template.create({
  display_name: "Welcome Email",
  format: "html",
  content: "<h1>Welcome, {{.Name}}!</h1><p>Your account is ready.</p>",
  fields: ["Name"],
});

POST /api/v1/templates

{
  "display_name": "Welcome Email",
  "format": "html",
  "content": "<h1>Welcome, {{.Name}}!</h1><p>Your account is ready.</p>",
  "fields": ["Name"]
}

{
  "id": "tpl_welcome_email_html",
  "key": "welcome_email_html",
  "display_name": "Welcome Email",
  "format": "html",
  "content": "<h1>Welcome, {{.Name}}!</h1><p>Your account is ready.</p>",
  "fields": ["Name"],
  "versions": 1
}

Rendering the template with data

Execute the template by providing values for its declared fields.

const output = await oblax.templates.template.render("welcome_email_html", {
  Name: "Jane Doe",
});

POST /api/v1/templates/welcome_email_html/render

{
  "Name": "Jane Doe"
}

{
  "output": "<h1>Welcome, Jane Doe!</h1><p>Your account is ready.</p>"
}

Errors

Best Practices

• Use obx app templates init to scaffold new templates with the correct file structure and metadata format.
• Always declare template variables in the fields array to document expected data contracts.
• Use the push command for both creation and update – the platform automatically versions on update.
• Choose the format that matches your output target: html for rich content, md for Markdown, text for plain text.
• Store template content in separate files alongside their JSON metadata for clean version control.
• Use the Render endpoint instead of manually fetching and executing templates when you only need the output.
• Use the --override flag with pull when you want to overwrite a local copy of a template.

Related Modules

Auth, Flux Scripts, File Manager, Notifications, Forms