Skip to content
This repository was archived by the owner on Oct 26, 2026. It is now read-only.

Temme options

Jump to bottom
Oussama Essamadi edited this page Oct 25, 2026 · 16 revisions

Options

Options define a hierarchy object’s structure and behavior. They describe what element Temme should create, what content and metadata it should apply, and how that hierarchy participates in inheritance and templating.

Below is the fully normalized shape Temme works with after validation and sanitization:

{
  ref: "",
  name: "div",
  id: "",
  content: {
    type: "text",
    value: ""
  },
  temmeIds: [],
  templates: [],
  classes: [],
  childNodes: [],
  attributes: {},
  dataset: {},
  from: {
    ref: "",
    mode: "append",
    children: {
      allow: false,
      placement: "after"
    },
    include: ["attributes", "childNodes", "classes", "content", "dataset", "id", "name"],
    exclude: []
  }
}

Each hierarchy object gets its own copy of these defaults. Templates get the same shape, minus name, childNodes and templates.

All options and sub-options are case-sensitive, and their value types are strict. If a hierarchy contains invalid option names, invalid sub-option names, invalid types, or invalid values, Temme will reject the hierarchy during validation.

In practice, you usually provide only the options you care about, and Temme fills in the rest with defaults.

temmeIds

Data type Default value Accepted value(s)
string[] Assigned internally. Generated by Temme only.

temmeIds is an internal identifier chain assigned by Temme. It is not meant to be authored manually.

Temme uses these IDs to track hierarchy relationships internally and to distinguish rendered nodes from templates.

Notes:

  • rendered hierarchy objects receive a generated ID segment of length 6
  • templates receive a generated ID segment of length 4
  • the full temmeIds array represents ancestry/context, not just a single ID

ref

Data type Default value Accepted value(s)
string "" Any valid string that does not begin with @ for local references.

ref gives a hierarchy object or template a reusable reference name so it can be inherited from later.

Notes:

  • use ref on templates when you want them to be reusable
  • use ref on rendered nodes when other nodes should inherit from them
  • local ref values must not begin with @
  • in from.ref, values beginning with @ are treated as external DOM selectors

id

Data type Default value Accepted value(s)
string "" Any valid HTML id string.

The id to assign to the parsed HTML element.

name

Data type Default value Accepted value(s)
string "div" Any valid HTML tag name or custom element name.

The HTML tag name Temme should create, such as div, h1, button, section, or a custom element tag.

classes

Data type Default value Accepted value(s)
string[] [] Any valid array of class names.

The CSS classes assigned to the parsed element.

Temme normalizes this array by:

  • removing duplicates
  • sorting values

attributes

Data type Default value Accepted value(s)
Record<string, string | number | boolean> {} Any object representing HTML attributes; values are stringified.

A map of HTML attributes to apply to the parsed element.

Example:

attributes: {
  title: "Tooltip",
  role: "button",
  tabindex: "0"
}

dataset

Data type Default value Accepted value(s)
Record<string, string | number | boolean> {} Any object representing data-* values; values are stringified.

A map of dataset values that will be written to the element’s dataset.

Example:

dataset: {
  userId: "42",
  state: "active"
}

childNodes

Data type Default value Accepted value(s)
object[] [] Any valid array of hierarchy objects.

The child hierarchy objects that Temme should parse and append beneath the current node.

Each item in childNodes is itself another hierarchy object with the same option model.

templates

Data type Default value Accepted value(s)
object[] [] Any valid array of template objects.

Template objects are reusable hierarchy definitions meant for inheritance.

Important behaviors:

  • templates are validated like normal hierarchies
  • templates are not rendered into the DOM
  • templates can inherit from other templates
  • rendered nodes can inherit from templates
  • templates cannot inherit from rendered nodes, but can inherit from outer elements (@selector)

content

Data type Default value Accepted value(s)
object { type: "text", value: "" } Object with valid type and value sub-options.

Controls the parsed element’s textual or HTML content.

content.type

Data type Default value Accepted value(s)
string "text" "text" or "html"

Determines how the content should be applied:

  • "text" → uses textContent
  • "html" → uses innerHTML

content.value

Data type Default value Accepted value(s)
string "" Any string.

The actual content value to assign.

Example:

content: {
  type: "text",
  value: "Hello world"
}

Or:

content: {
  type: "html",
  value: "<strong>Hello world</strong>"
}

from

Data type Default value Accepted value(s)
object See normalized example above. Valid inheritance configuration.

The from option controls inheritance. It tells Temme which hierarchy or template to inherit from and how that inheritance should be applied.

from.ref

Data type Default value Accepted value(s)
string "" A valid local reference or an external selector prefixed with @.

Specifies what to inherit from.

Accepted patterns:

  • a local hierarchy/template reference such as "base-card"
  • an external DOM selector such as "@#app" or "@.card"

Notes:

  • local references must point to a valid in-scope hierarchy or template
  • selector references are resolved with querySelector(...) on the target's document; they honor include and exclude, but never provide a tag name or child nodes

from.mode

Data type Default value Accepted value(s)
string "append" "append" or "override"

Controls how inherited values are merged.

  • append: preserve existing primitive values, merge arrays, append object keys without overwriting existing ones
  • override: replace primitive values, replace arrays, and overwrite matching object keys

from.include

Data type Default value Accepted value(s)
string[] ["attributes", "childNodes", "classes", "content", "dataset", "id", "name"] Valid inheritable option names only.

Restricts inheritance to only the specified option names.

If include is present, only those options are inherited.

from.exclude

Data type Default value Accepted value(s)
string[] [] Valid inheritable option names only.

Excludes specific option names from inheritance.

If exclude is present, everything except those listed options is inherited.

Important:

  • include and exclude cannot restrict inheritance together
  • Temme throws an InvalidReferencingOptionError if both are non-empty at the same time

from.children

Data type Default value Accepted value(s)
object { allow: false, placement: "after" } Valid child inheritance configuration.

Controls whether childNodes inheritance is enabled and where inherited children should be placed.

from.children.allow

Data type Default value Accepted value(s)
boolean false true or false

Enables or disables child node inheritance.

When true, the referencing hierarchy can inherit the referenced hierarchy’s childNodes.

from.children.placement

Data type Default value Accepted value(s)
string "after" "before" or "after"

Controls where inherited child nodes are inserted relative to the inheriting hierarchy’s own childNodes.

  • "after": inherited children are appended after local children
  • "before": inherited children are inserted before local children

Notes on defaults and validation

Temme fills in missing values automatically during sanitization, but only after the provided hierarchy passes validation.

Validation checks include:

  • invalid option names
  • invalid sub-option names
  • invalid types
  • invalid accepted values
  • invalid references
  • invalid template usage
  • invalid inheritance combinations such as non-empty include and exclude together
  • references to elements out of scope (nested deeper than the referencing object)
  • circular inheritance, such as a inheriting from b inheriting from a

Because of that, the recommended approach is:

  1. provide only the options you actually need
  2. use validate(hierarchy) if you want to check the structure first
  3. call parse(...) once the hierarchy is valid

Example

const hierarchy = {
  ref: "card",
  name: "article",
  classes: ["card"],
  attributes: {
    role: "article"
  },
  dataset: {
    kind: "profile"
  },
  content: {
    type: "html",
    value: "<h2>Profile</h2>"
  },
  childNodes: [
    {
      name: "p",
      content: {
        value: "This card was generated with Temme."
      }
    }
  ]
};

This example defines a rendered article element with classes, attributes, dataset values, HTML content, and a child paragraph node.

Clone this wiki locally