VN-Designer Developer Documentation
02

The template (template.html)

Structure of template.html: root element and its attributes, placeholders {{…}} with expressions and helper functions, images and links, Bootstrap, site-wide blocks and what happens in the editor and in the export.

Structure#

template.html describes the markup of one block. It consists of a root element that encloses everything else. Inside the root element come first the <vn-parameters> block (the input fields, see Input fields) and then the actual markup with placeholders and directives.

html
<section class="mb-karte">
  <vn-parameters>
    <header>Größe</header>
    <input type="range" title="Abstand" name="abstand" min="0" max="8" step="1" value="3">
  </vn-parameters>
  <div class="container">
    <h2>Willkommen</h2>
    <p vn-if="abstand > 1">Text mit Abstand {{abstand}}</p>
  </div>
</section>

The root element#

The first element of the file is the root (section; for menu and footer also nav or footer). The program adds to the root what marks the block as an instance:

  • the instance class vn-imp-<alias>-<block ID> (the block CSS is based on it, see LESS: Scope and root),
  • the id blk-<block ID>, or the anchor ID set by the user. If the root itself carries an id, it is kept.

The parameter block#

<vn-parameters> belongs inside the root (not before it) and is removed when drawing. Details: Input fields.

Markup#

Everything else is ordinary HTML5 with these additions:

  • Placeholders {{…}} insert values (Placeholders).
  • Directives (vn-if, vn-class, vn-style …) make elements depend on values (Directives).
  • Classes from Bootstrap 5 and Bootstrap Icons are available (Bootstrap).
  • Scripts (<script> without src) stay in the markup; see Scripts in blocks.
  • Texts, images, buttons and icons become automatically editable in the editor (Directly editable content).

Attributes on the root element#

The program evaluates these attributes on the root element.

global#

Makes the block site-wide: it exists once in the project and appears on every page (menu, footer).

Syntax

html
<nav global once="menu" class="navbar vn-menu"> … </nav>
<footer global once="footers" class="vn-footer"> … </footer>

Attributes

NameValueDefaultMeaning
globalswitch–Block is site-wide. Must be on the very first element of the file (checked: a <vn-parameters> block placed before it, or a wrapping div, prevents detection)

Everything else (groups, position in the export, replacement) is under Site-wide blocks.

once#

The name of the group of a site-wide block. Each group has at most one block in the project: a newly inserted one replaces the old one.

ValueMeaning
menugroup "Menu": in the export the block stands above the page content
footersgroup "Footer": the block stands below
other textgroup with this name; stands at the top if the name contains menu, nav or header (case does not matter), otherwise at the bottom

once without global has no effect (checked). Without once the group is called global.

group#

group="Content" on the root element appears in many packages. The program does not evaluate it. The category in the selection comes from _group in params.json (Names). You may omit the attribute.

plugins#

plugins="DropDown, TouchSwipe" names the plugin folders that a block from a Bootstrap 4 theme needs. It only has an effect in the project's Bootstrap theme mode and only on a <section>: the export then additionally loads the scripts of these plugins (see Bootstrap mode). It is superfluous for blocks on the bundled Bootstrap 5.

data-bs-version#

data-bs-version="5.1" marks a block as built for Bootstrap 5. Its only effect: if such a block enters a project that runs in Bootstrap theme mode (Bootstrap 4), the program shows a note that it may look different.

data-bg-video#

Carries the address of a background video for the whole block. The value is usually a placeholder that yields an address only when the video is chosen.

Syntax

html
<section class="mein-header" data-bg-video="{{bg.type == 'video' &amp;&amp; bg.value.url}}">
  <vn-parameters>
    <fieldset name="bg">
      <input type="video" title="Video" value="">
      <input type="image" title="Bild (Ersatzbild)" value="../_images/ersatz.jpg" selected>
      <input type="color" title="Farbe" value="#111111">
    </fieldset>
  </vn-parameters>
  …
</section>

Behavior (checked)

  • If the value is empty or false, undefined, null, 0, nothing happens (with another kind of background the HTML contains data-bg-video="false").
  • Otherwise the program inserts as the first child of the root a <div> layer for the fallback image (its class is listed under Older notations) and adds CSS: root position: relative; overflow: hidden, layer absolute and filling, .container/.container-fluid at z-index: 2. The rules are in :where(…) so that a theme CSS of your own takes precedence.
  • In the export the page loads vendor/vn-bgvideo/vn-bgvideo.js if at least one block carries a video address. The script builds the video (YouTube, Vimeo or file) in when the page is displayed. With VN Cookie Consent switched on, YouTube and Vimeo load from version 1.3.100 only after consent to "Marketing" (until then the fallback image stays in place; see Playback on the page). In the editor you only see the fallback image.

vn-strict-if#

A marker on the root (or any element) that makes vn-if strict in the whole block. See vn-strict-if.

id and class#

Own class values stay, the instance class is added. An own id is kept; without an id the program sets blk-<block ID> or the user's anchor ID. In references inside the block use {{vn-id}} (Placeholders), not fixed IDs: the same block may appear several times on a page.

Attributes that are not evaluated#

These attributes appear on the root element in older packages. The program ignores them; they stay in the markup and do no harm: group, always-top, not-draggable, position-absolute, data-app-selector, data-app-placeholder, data-toolbar.

Placeholders#

A placeholder {{expression}} is replaced by its result when drawing. This applies everywhere in the template: in text, in attributes, in <script> and <style>. The expression is JavaScript (Expressions) and knows all values of the block under their name.

{{name}}#

Inserts the value of a field.

Syntax

html
<h2>{{titel}}</h2>
<div style="min-height:{{hoehe}}vh"></div>
<img src="{{foto}}" alt="">

Example (from themes/vn-studio-src/components/header1)

html
<section class="vn-hero" vn-class="{'vs-fullscreen': fullScreen}" style="min-height:{{hoehe}}vh">

What becomes of the result (checked)

Result of the expressioninserted as
text, numberthe text
true, falsetrue, false
undefined, null (also on an error in the expression)empty text, without a message
list [1,2]1,2
object[object Object]

Expressions#

Between the braces any JavaScript expression may stand, not only a name.

html
<p>{{ n > 3 ? 'viel' : 'wenig' }}</p>
<div style="height:{{logoSize * 1.8}}rem"></div>
<a data-n="{{ Number(anzahl) + 1 }}">…</a>
  • Whitespace around the expression is removed.
  • In attributes the program converts &amp;&amp; (&&), &lt;, &gt;, &quot;, &#39; and &amp; back before evaluation: data-bg-video="{{bg.type == 'video' &amp;&amp; bg.value.url}}" works.
  • range values are text: {{n + 1}} yields the text 41 when n = "4"; {{n * 2}} yields 8 (checked).
  • The standard JavaScript objects (Math, String …) are available.
  • An error yields empty text; there is no error message. Check unusual expressions in the editor.

Object fields#

The background widget supplies an object. In the template these fields are available (name of the widget here bg):

ExpressionImageColorVideo
{{bg.type}}imagecolorvideo
{{bg.value}}the image address#rrggbb[object Object]
{{bg.value.url}}the image address–the video address
{{bg.parallax}}true/falsefalsefalse

For an image, bg.value behaves in the template like the address as text and has .url (checked): both notations url({{bg.value}}) and url({{bg.value.url}}) work.

html
<div class="deckel" style="background-image: url({{bg.value}});"></div>

See Background widget.

{{vn-id}}#

Yields the identifier of the instance: blk-<block ID> or the user's anchor ID. With it you build IDs that stay unique even with several identical blocks on a page. The replacement applies in the whole template, also in the text of <script>.

Syntax

html
<button class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#{{vn-id}}-nav"></button>
<div class="collapse navbar-collapse" id="{{vn-id}}-nav"> … </div>

vnEnc(text)#

Escapes a text for a data-… attribute: the result is encodeURIComponent(String(value)); undefined and null yield empty text. In the script you read it back with decodeURIComponent.

Syntax

html
<h1 data-swapwords="{{vnEnc(swapWords)}}">…</h1>
js
var worte = decodeURIComponent(h.getAttribute("data-swapwords") || "").split("|");

Example (from gallery-content/vn-kinetic-theme, block "Hero 1"): The words come from a text field in the panel that may contain any characters. More: Text data in attributes.

vnEmbed(address)#

Converts a YouTube or Vimeo address into the embeddable address; other addresses stay unchanged.

html
<iframe src="{{vnEmbed(videoUrl)}}" allowfullscreen></iframe>
InputResult
https://youtu.be/dQw4w9WgXcQhttps://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?rel=0&modestbranding=1&playsinline=1
https://vimeo.com/76979871https://player.vimeo.com/video/76979871
other addressunchanged

Placeholders in buttons#

In a button (<a class="btn …">) placeholders in text and href are not evaluated. The program rebuilds every button from its default value and the user's changes in the button dialog; the default value is the raw text from the template, so {{name}} appears literally on the page (checked in the editor and in the export).

html
<a class="btn btn-primary" href="{{ziel}}">{{beschriftung}}</a>   

What works: a placeholder in an ordinary link (<a href="{{ziel}}">Text {{x}}</a> without the class btn), in a <button> and in attributes such as title or alt. The user maintains the button text and the target on the button itself.

Placeholders in scripts and attributes#

The replacement happens on the text of the template, before it is read as HTML. It follows:

  • A placeholder also works in the content of <script> (var s = "{{n}}"; yields var s = "2";).
  • A value containing " breaks an attribute; a value containing < or > can change the markup. For texts from the panel use vnEnc or insert them only as text content.
  • Every {{ … }} in the template is evaluated as an expression, also in JavaScript code. A sequence {{ or }} in the script (for example function(){{…}} or a nested object expression) yields nonsense or empty text. Write braces in the script with spaces ({ {, } }) or on separate lines.

How images and links become replaceable in the editor is described in Directly editable content. For the template the following applies:

  • Image field: <img src="{{feld}}">, where feld is a field type="image". Exactly one placeholder as src (without further text) marks the image; a click on it opens the image selection for this field in the editor.
  • Background image: style="background-image: url({{bg.value}});" (in style or in vn-style) marks this element for the widget bg. In addition, with a background widget the root always carries this marker.
  • Fixed image: <img src="https://…"> or a style with background-image: url(…) without a placeholder is a free image and can be replaced by a click.
  • Links: Placeholders in href work for ordinary links (<a href="{{ziel}}">), not for buttons (see above).
  • File addresses: In the project, images appear as file:///…/assets/…. The export rewrites every such address in HTML and CSS to assets/… and copies the files along; only referenced files are included.

Bootstrap and classes#

The program supplies Bootstrap 5.0.1 (grid, utility classes, components) and the Bootstrap Icons. Both are available in the editor and in every exported page (vendor/bootstrap.min.css, vendor/bootstrap.bundle.min.js, vendor/bootstrap-icons/); blocks do not have to include anything.

  • Use the classes of Bootstrap 5 (container, row, col-md-6, d-flex, gap-3, btn, btn-primary …) and bi bi-<name> for icons.
  • jQuery is not available (only in Bootstrap theme mode for Bootstrap 4 themes).
  • Bootstrap JS components work through data-bs-… attributes (data-bs-toggle="collapse"). Attributes of version 4 (data-toggle, data-target …) are complemented on import by the data-bs-… counterpart (Bootstrap attributes).
  • Give your classes names with an abbreviation of the block (mb-karte, vnkn-hero). The block CSS is limited to the instance, but classes from theme CSS and Bootstrap are not.

Site-wide blocks#

Menu and footer belong on every page. A block with global on the root element does not lie in a page but in the list of global blocks; in the export it stands on every page, menu groups at the top, all others at the bottom, and its CSS only once in style.css. Everything else: Site-wide blocks: global and once.

Editor and export#

The same template is drawn twice: for the canvas and for the export. Both use the same drawing function (render); afterwards they differ.

EditorExport
<vn-parameters>removedremoved
{{…}}, directivesevaluatedevaluated (same result)
Texts, images, buttons, iconscontenteditable, identifiers data-vn-…, classes such as vn-editable-text; a click opens dialogschanges baked in, all editor identifiers removed
data-vn-editor-onlyvisibleremoved (Scripts)
<script> in the blockruns through stand-ins for window, document, timers; every redraw ends the old timersstays unchanged in the page (Scripts)
Videos with autoplaydo not startstart (muted)
Background video (data-bg-video)fallback imagevideo through vn-bgvideo.js
Image addressesfile:///…assets/…
CSS@layer vn-blocks, Bootstrap and theme in @scope (#canvas)one style.css, no layers (Precedence)
PHP (<script type="text/x-vn-php">)does not runis replaced by the raw PHP code; the page needs the extension .php (the program offers to rename it)
Popup, CMSframe and markingpopup container, CMS markers and PHP calls