Customizing templates

Templates are how DeltaVault turns your metadata into runnable code. When you preview or generate a create-table statement, a load step, a data test, or an orchestration script, a template renders it. Most teams start on the templates DeltaVault ships, then tailor a few of them (change a naming convention here, add a header comment there) without rewriting everything. This guide covers the template workbench, how to read a template’s composition, and the ways to customize a template while keeping the rest of it tracking the version DeltaVault ships.

Where customization lives

Opening the Templates area launches the template workbench. The workbench shows a template as an ordered stack of cells rather than one large code editor. There are two kinds of cells:

Block cells represent the named {% block %} sections in the template, one cell per block. Each block is a self-contained, customizable region.
Glue cells represent the connective tissue between blocks: import statements, {% set %} preamble lines, and raw Jinja interludes that are not wrapped in a named block.

Every cell, whether a glue cell or a block cell, is a live syntax-highlighted editor. When a cell is editable (your organization’s fork, or an admin authoring a global), you type directly into it with no separate Edit or Save button per cell. When a cell is read-only (for example, your organization is viewing a global template), the cell is still syntax-highlighted and you can select and copy its content, but you cannot modify it in place.

A template that has no blocks at all renders as one full editor cell, letting you edit the entire body as a single unit.

The left tree lists every template available to you: the global templates DeltaVault ships alongside your organization’s forks. The badges on a row report what has happened to that template rather than who owns it. A fork badge marks one your organization copied from a global. upstream changed means the global it was forked from has moved since the fork. An overrides badge counts the block customizations on it, and stale counts the ones whose upstream block has changed underneath them. dangling rule means a binding rule points at a template that is no longer there, and Retired - resync marks a deployed copy sitting at a path the product bundle has since retired.

The Preview panel renders the whole composed template as you work. It updates live whenever you edit any cell, so you see the result of any change immediately.

Select a template in the tree to load its cells and the Preview.

Switching between Sections and Code view

A Sections | Code toggle sits at the top of the editor. It controls how the selected template is shown, and your choice is remembered the next time you open the workbench.

Sections is the default. It shows the template as the ordered stack of block and glue cells described above, with all the per-block customization actions.
Code shows the entire template as one continuous, syntax-highlighted editor. Use it to read or copy the whole template top to bottom, or to make edits that span several sections at once.

In Code view, an editable template (your organization’s fork, or an admin authoring a global) can be edited directly, and your changes flow straight back into the section cells when you switch back to Sections. A read-only global template shows its full text in Code view but cannot be edited there; use the per-block Customize action in Sections view to change a global.

In Code view you can collapse Jinja blocks so you can focus on one part of a large template. Hover over the gutter, just to the left of the line numbers, and a fold chevron appears beside the opening line of every multi-line block, loop, or conditional (a {% block %}, {% for %}, {% if %}, and similar paired tags). Click the chevron to collapse that section to its opening line, and click again to expand it. Nested sections fold independently, so you can collapse a whole block or just a loop inside it. Fold All and Unfold All are available to collapse or expand every section at once.

Working with a global template

Global templates are read-only: every cell is syntax-highlighted and selectable, but you cannot type into the cells directly. Three targeted actions let you customize without taking ownership of the whole file.

Customizing a block cell

When you only need to change one section of a global template, use Customize on that block cell. Customizing a block creates an override for just that one section: your version replaces the block’s default body, and a “customized” marker appears on the cell to confirm it is overridden. Every other cell in the template keeps tracking the upstream version DeltaVault ships.

To undo a block customization, use Revert on that cell. Revert drops the override and returns the cell to its upstream body. The “customized” marker disappears and the section behaves exactly as the shipped template does, picking up future improvements automatically.

Forking a helper from a glue cell

Some glue cells import a shared helper macro. When the change you want lives in a helper rather than in one template’s blocks, use Fork helper on that glue cell. This copies the helper’s current upstream body into an organization-owned version you can edit. Because the helper is shared, your change applies everywhere that helper is imported, not just in the template you have open.

Forking a helper is available on a read-only global template: you do not need to fork the whole template first.

Forking the whole template

When you want to add sections, remove sections, reorder sections, or convert glue content into a named block, fork the entire template first. Use Fork to my organization on a global template. This creates a complete organization-owned copy that appears in the left tree under your organization. A forked template is fully editable: see the next section for what you can do.

Working with your organization fork

An organization fork is fully editable. Every cell is a live syntax-highlighted editor you type into directly.

Editing a cell: Click into any block cell or glue cell and start typing. There is no per-cell Edit or Save button. The Preview updates as you type, so you can see the effect of every change immediately.

Adding a section: A dashed + Section control appears between cells. It fades in when you hover over any gap between cells, and it stays visible directly above and below whichever cell you are currently editing. Clicking it inserts a new block cell at that position immediately and opens its name for inline rename: type the name you want and press Enter to confirm. To back out, press Escape or use Cancel in the rename row, which removes the just-inserted section. There is no separate name prompt before insertion.

Deleting a section: Use Delete on a block cell’s header to remove it. Deleting a block on a global template warns first that organizations which customized it keep their override row but that the override will no longer apply. The warning appears every time rather than only when a customization exists, so read it as a statement of the consequence, not as evidence that somebody has customized this particular block.

Converting a glue cell: Use Convert into block in a glue cell’s header to turn it into a named block. The cell is given a name automatically and then opens immediately for the same inline rename: type the name you want and press Enter to confirm. To back out, press Escape or use Cancel in the rename row, which restores the original glue cell. The glue content becomes the block’s default body, and the new block is immediately available as a customization point.

Reordering sections: Drag block cells by their header to reorder them. The order of cells determines the order of output in the rendered template. The Preview reflects the new order live, so you can confirm the effect before saving.

Renaming a block: Click the block’s name in its header to open the inline rename field, then press Enter to confirm or Escape to cancel.

Saving: Save persists all your edits to the fork. Changes live on your current feature branch until that branch is committed, keeping your work isolated and reviewable the same way other metadata changes are.

Where a template applies

Open any template and switch the right panel from Preview to Where it applies to see the binding rules that route work to this template, and to add, change, or remove them without leaving the workbench.

Each row shows the output kind the rule renders (DDL, Load, Test, or Orchestration), the entity type it targets (or Any entity type when it applies to a whole layer), and a badge for its scope: Platform or Organization. A rule that is turned off carries a Disabled badge.

Use Add binding to create a rule that routes this template, or the edit and remove controls on a row to change or delete one. Adding or editing opens the binding-rule form with the template path already filled in and locked, so the rule can only point at the template you have open.

The scope follows where you are working:

In the platform workbench you author platform-default rules, and you can turn a rule on or off in one click.
In the organization workbench you author rules for your organization. Platform defaults still appear so you can see the full picture, but they are read-only here: you cannot change a platform default from an organization context.

Rules scoped to a single project are not shown here. To point a template at one project, use that project’s Templates tab instead.

Override a template for one table

Every committed table’s detail pane has a Preview tab that renders its generated code. A segmented control lets you switch between the three output kinds for that table: Create table, Load, and Test.

Below the segmented control, a readout line shows which binding matched for the currently selected output kind. It is worded “matched:” followed by the scope that resolved the binding: platform default, organization rule, project rule, or table override. The matched dimensions (target platform, data layer, and table type) appear in parentheses beside the scope label, and the resolved template is shown as a link so you can jump straight to it in the workbench. The readout appears only when a binding matches for the selected output kind; if nothing binds for that kind, neither the readout nor the override control is shown.

Pin a different template to this table

To route a different template to this one table for the selected output kind, use the small chevron (dropdown) button beside the resolved template link in the readout. Hovering it shows the label “Change template”. Opening the dropdown lists the available library templates as menu items; selecting one pins that template to this table for the selected output kind. The readout switches to table override to confirm it is in effect, and that override takes precedence over the project, organization, and platform rules for this table only. The four scopes, tightest first, are: table override, then project rule, then organization rule, then platform default.

The chevron button is available on a branch. On the main branch it is disabled (a tooltip explains why). Switch to a branch to author or remove an override.

Revert to the inherited template

Once a table override exists, a Revert to inherited option appears at the bottom of the same dropdown (below a separator). Selecting it removes the override: the readout returns to whichever scope now wins (project rule, organization rule, or platform default), and the table generates code from the inherited template again.

Where the override also appears

A table override you author from the Preview tab is also listed in that project’s Templates tab under the Table overrides section. The two surfaces reflect the same underlying override, so a change in one is immediately visible in the other. See Assign templates per layer and entity type for the full project-level view, including how to author or remove per-table overrides from the project side.

Who can customize, and where

Customizing a template requires editor permissions. Viewers can open the workbench and read a template’s cells (the cells are syntax-highlighted and selectable for copying), but only editors can customize a block, fork a helper, fork a whole template, or edit a fork.

Customization happens on a feature branch. Your changes are branch-scoped until that branch is committed, keeping them isolated and reviewable before they become part of shared state.

Assign templates per layer and entity type: assign a template from inside a project, including per entity type, and see all per-table overrides in one place under the Table overrides section (the four-scope defaults readout and per-table override controls work in tandem with the Preview tab)
Data tests and verification: defining the assertions that test templates render
Data Vault modeling: the layers and entities your templates generate code for
Custom attributes: define your own typed table and column attributes and read them as table.custom.<key>