VN-Designer Developer Documentation
03

Input fields (vn-parameters)

The <vn-parameters> block in the template: groups, every input type with an example, the background widget, attributes, conditions (condition), default values, naming rules and a complete parameter block.

Overview#

The <vn-parameters> block in the template describes the properties of a block: the fields in the properties panel, their groups, default values and conditions. Every field produces a value that the markup can use as {{name}} or in expressions (vn-if, vn-class …) and that the LESS can use as the variable @name.

html
<section class="mein-block">
  <vn-parameters>
    <header>Größe</header>
    <input type="range" title="Abstand oben" name="abstand" min="0" max="8" step="1" value="3">
    <input type="checkbox" title="Titel anzeigen" name="showTitel" checked>
  </vn-parameters>
  <h2 vn-if="showTitel">Überschrift</h2>
</section>

Rules for the block itself:

  • It sits inside the root element (a block placed before the root element prevents global from being detected, see Root attributes).
  • Only the direct children of <vn-parameters> are read. A field inside a wrapping <div> or <label> is ignored (checked).
  • Only the first <vn-parameters> block of the template is read. A second block is not evaluated and stays in the markup (checked).
  • When the block is drawn, the parameter block is removed from the markup; it never appears in the export.
  • Children without a name (except header and fieldset) and children of other tags (div, p …) produce no field.

Groups and order in the panel#

A heading in the panel. All fields up to the next heading belong to this group.

Syntax

html
<header>Farben</header>
<header condition="mode == 'liste'">Nur für die Liste</header>

Attributes

NameValueDefaultMeaning
(text)text–Title of the group (textContent, trimmed)
conditionexpression–The heading is only visible while the expression does not evaluate to false. The fields below are not affected: to hide them as well, write the same condition on each field

Example (from gallery-content/vn-kinetic-theme, shortened)

html
<header>Video-Hintergrund</header>
<select title="Hintergrund-Video" name="vidMode"> … </select>
<input type="text" title="Video-Datei (MP4/WebM)" name="videoFile" value="" condition="vidMode == 'file'">

Layout of the panel#

From top to bottom, the properties panel shows (checked on a block):

  1. A header row with the block name and the buttons ★ (save as user block), ⤓ (save as .vndext) and </> Code.
  2. For blocks with three or more own fields, the button "↓ Settings of this block", which jumps to the heading of the block's own fields.
  3. The automatic sections (see below): anchor ID, popup, CMS, free layers, menu controls, text size, text width, text position, video addresses.
  4. The heading "Settings of this block" (only with three or more fields) and below it your fields in the order of the <vn-parameters> block.
  5. If the template contains the word overlay and there is a background widget: the automatic overlay fields at the very end.

Automatic sections#

The program creates these sections for every block. They do not belong in <vn-parameters>:

SectionWhenStored as
Anchor ID (jump target for links/URLs)alwaysblock.anchorId (becomes the id of the root)
Popup, CMSalwaysblock.popup, block.cms
Free layers (images and text boxes)alwaysin the block
Menu font, hamburger color, dropdown colorsif the template contains navbar-nav or nav-link_menuFontPx, _brandFontPx, _togglerColor, _ddBg, _ddText, _ddHoverBg, _ddHoverText
Text size, text width, text position (up/down)always; width and position not on the Free Surface_textScalePct, _textWidthPct, _textOffsetYPx
Video address (YouTube, Vimeo or video file) with "Start automatically" and "Loop"for each element with vn-video in the template_videoUrl<i>, _videoAuto<i>, _videoLoop<i>

Input types#

The type of a field follows from the tag and the type attribute. Anything not listed in the table becomes a single-line text field.

Tag and typeField type in the panelValue in the template (JavaScript)Value in LESS
input type="text" (and any unknown type)text fieldtextquoted text
textareamulti-line text fieldtext with line breaksquoted text
input type="checkbox"switchtrue or falsetrue or false
input type="color"color pickertext #rrggbbcolor
input type="range"slider with number fieldtext (e.g. "4")number
selectselection listtext (the value of the option)quoted text
input type="image"image fieldtext (image address)quoted text
fieldset with image/color/videobackground widgetobject { type, value, parallax }see Background variables

text#

A single-line text field.

Syntax

html
<input type="text" title="Beschriftung des Knopfs" name="knopfText" value="Mehr erfahren">

Attributes

NameValueDefaultMeaning
nameidentifier– (required)Name of the value, see Names
titletextthe nameLabel in the panel
valuetextemptyDefault value
conditionexpression–Show the field only if the condition does not evaluate to false

The value is taken over with every keystroke and the block is redrawn.

Special names: videoFile, videoFile2 and subtitleFile additionally get a "Choose file…" button, see File and video fields. A field formFile suggests the forms of the project (VN Form Renderer).

textarea#

A multi-line text field, for example for data from a spreadsheet or a list with one entry per line.

Syntax

html
<textarea title="Vorteile (eine Zeile pro Punkt)" name="vorteile" rows="4">Schnelle Lieferung
Faire Preise</textarea>

Attributes

NameValueDefaultMeaning
name, title, conditionas for text
rowsinteger 2 to 305Height of the field in the panel. Smaller values are ignored, larger ones are cut to 30
(content)textemptyDefault value; line breaks are kept

Example (output with line breaks via LESS)

html
<p class="liste">{{vorteile}}</p>
less
.liste { white-space: pre-line; }

checkbox#

A switch. It usually controls vn-if, vn-class or a condition in the LESS.

Syntax

html
<input type="checkbox" title="Titel anzeigen" name="showTitel" checked>

Attributes

NameValueDefaultMeaning
name, title, conditionas for text
checkedswitchoffDefault "on". The attribute value is not read

The value is a real boolean: vn-if="showTitel" hides the element when it is off, and in LESS & when (@showTitel) { … } applies.

color#

A color picker.

Syntax

html
<input type="color" title="Akzentfarbe" name="akzent" value="#4f46e5">

Attributes

NameValueDefaultMeaning
name, title, conditionas for text
value#rrggbb#000000Default color

range#

A slider with a number field next to it. The user can also type the value; it is clamped to the range.

Syntax

html
<input type="range" title="Abstand oben" name="abstand" min="0" max="8" step="1" value="3">

Attributes

NameValueDefaultMeaning
name, title, conditionas for text
minnumber0smallest value
maxnumber100largest value
stepnumber1step size, decimals are allowed (0.05)
valuenumberminDefault value
inline––is not evaluated, see inline

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

html
<input type="range" inline="" title="Abdunklungs-Stärke" name="dimOpacity" min="0" max="1" step="0.05" value="0.4">

Grid: The slider snaps to min + n × step. If value is not on this grid, the panel shows the nearest grid value, but the stored value stays the default until the user moves the slider (checked: min=2, step=2, value=7 shows 8, the LESS sees 7). Choose defaults on the grid. A value outside min to max is clamped to the range; a non-numeric value shows the middle.

select and option#

A selection list.

Syntax

html
<select title="Ausrichtung" name="ausrichtung">
  <option value="left" selected>Links</option>
  <option value="center">Zentriert</option>
</select>

Attributes

NameValueDefaultMeaning
name, title, conditionas for text
option valuetext– (required)stored value. An option without value yields no usable value
option (text)text–Label in the list
selectedswitchfirst optionDefault. Without selected the first option applies

Example (evaluation)

html
<div class="karten" vn-class="{'karten-mitte': ausrichtung == 'center'}"> … </div>
less
& when (@ausrichtung = 'center') { text-align: center; }

image#

An image field with preview, file selection, image search and the list of the project's images.

Syntax

html
<input type="image" title="Foto" name="foto" value="../_images/foto.jpg">

Attributes

NameValueDefaultMeaning
name, title, conditionas for text
valueimage addressemptyDefault image. Use ../_images/<file>: the import places the file in the project, see Packages

The value is the image address as text, not an object. In the template you write <img src="{{foto}}">; such an image can be replaced by a click in the editor (data-vn-image-key, see Directly editable content). In LESS the value is text: background-image: url(@foto);.

fieldset (background widget)#

The background widget lets the user choose between color, image and (if provided) video. The image comes with a "Parallax effect" switch.

Syntax

html
<fieldset name="bg" title="Hintergrund">
  <input type="image" title="Bild" value="../_images/header.jpg" parallax>
  <input type="color" title="Farbe" value="#14151d" selected>
</fieldset>

Attributes on the fieldset

NameValueDefaultMeaning
nameidentifierbgName of the value
titletext"Background"Label in the panel
conditionexpression–Show the widget only if the condition does not evaluate to false (only effective if name is set)
type="background"––is not read; a marker in many packages without effect

Attributes on the inputs inside the fieldset

InputAttributeMeaning
input type="image"valueDefault image (rules as for image)
input type="image"parallaxThe parallax switch is on in advance. Only effective on this input: a parallax on the fieldset is not read (checked)
input type="color"valueDefault color, #000000 if omitted
input type="video"valueDefault address of the background video; enables "Video" in the type selection
any of the threeselectedthis kind is the default

Which kind is preselected:

  1. If the widget has a video and it carries selected (or there is neither image nor color), the default is video.
  2. Otherwise image, if an image input exists and carries selected or there is no color.
  3. Otherwise color.

If selected is missing on image and color, the default is therefore color.

Stored value ({{bg}} in the template, see Background variables for LESS)

Kindbg.typebg.valuebg.parallax
Colorcolortext #rrggbbfalse
Imageimageimage address (behaves in the template like text and has .url)true or false
Videovideoobject { url }false

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

html
<fieldset type="background" name="bg">
  <input type="image" title="Bild" value="../_images/header.jpg"/>
  <input type="color" title="Farbe" value="#14151d" selected/>
</fieldset>
html
<div class="deckel" style="background-image: url({{bg.value}});"></div>

video (in the background widget)#

input type="video" exists only inside a fieldset. It makes "Video" the third choice of the background widget (YouTube/Vimeo address or a video file from the project).

Syntax

html
<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>

Note on playback: The block carries the address in the attribute data-bg-video (see Root attributes); in the editor the block shows the fallback image, the video plays in the preview and on the finished page.

File and video fields#

Three text fields with fixed names get the buttons "Choose file…" and ✕ (remove) next to the input field in the panel. The file is copied into the project folder and its address is entered as the value; an address (https://…) can also be typed in.

NameFile kindAllowedTarget in the projectSize
videoFilevideomp4, webm, ogv, m4vassets/videos/up to 4 GB
videoFile2video (second version)as aboveassets/videos/up to 4 GB
subtitleFilesubtitlesvttassets/subtitles/up to 2 MB

Syntax

html
<input type="text" title="Video-Datei (MP4/WebM) — Adresse oder Datei wählen" name="videoFile" value="">
<input type="text" title="Untertitel-Datei (.vtt, optional)" name="subtitleFile" value="">

Example (from src/vn-video.js, the block "Video (self-hosted)")

html
<source vn-if="!!videoFile" src="{{videoFile}}">
<track vn-if="!!subtitleFile" kind="subtitles" src="{{subtitleFile}}" srclang="{{subLang}}" label="{{subLabel}}">

Other types#

number, email, url, tel, date, hidden, file, password, a missing type and every other unknown type produce a plain text field (type text): the browser checks nothing, min/max do not apply. For numbers use range.

html
<input type="number" title="Anzahl" name="anzahl" value="5">

becomes a text field with the text 5 in the panel. The value is text: calculate with Number(anzahl).

Attributes#

name#

The name of the value. Without name an input produces no field (only header and fieldset need none; the fieldset has the default name bg).

Rules (all checked)

  • Allowed are names made of letters (A–Z, a–z), digits and underscore that start with a letter: abstandOben, show_titel, col2.
  • The name is at the same time a JavaScript identifier (for {{…}} and conditions) and a LESS variable (@name). A name that is not a valid identifier in JavaScript makes every placeholder and every condition of the whole block come to nothing: {{…}} then yields empty text and vn-if no longer hides anything. This affects names with a hyphen (mein-name), a dot or a space, with a digit at the start (1abc) and reserved words (class, default, new, if …).
  • Names with an umlaut or $, on the other hand, break the LESS (the block gets the label "⚠ CSS error").
  • Two fields with the same name share one value; the default of the one that comes last applies.
  • Names starting with an underscore are reserved (Automatic sections).

title#

The label of the field in the panel. Without title (or with an empty title) the panel shows the name. With English or French as the program language, the panel label is translated if the German text is in the program's dictionary; otherwise it stays as written.

value#

The default value (for textarea the content, for select the option with selected, for checkbox the attribute checked). See Default values.

checked#

checkbox only: default "on".

min, max, step#

range only: range and step size. The values are read as numbers; if they are missing, 0, 100 and 1 apply.

rows#

textarea only: height in lines, 2 to 30.

selected#

On option: default of the selection list. On the inputs of a background widget: default kind.

inline#

The attribute inline (or inline="") appears on range fields in many packages. The program does not evaluate it: it has no effect on the display. Sliders always appear with a number field next to them. You may omit it.

condition#

Hides a field (or a heading, a widget) in the panel as long as a condition is not met.

Syntax

html
<input type="text" title="Video-Datei" name="videoFile" value="" condition="vidMode == 'file'">
<input type="range" title="Stärke" name="staerke" min="0" max="1" step="0.05" value="0.4"
       condition="overlay &amp;&amp; bg.type == 'image'">

Rules

  • The expression is JavaScript and sees all values of the block under their name (overlay, bg.type …). Helper functions such as vnEnc are not available here.
  • In an HTML attribute write && as &amp;&amp;, < as &lt; and > as &gt;. Swap quotation marks in the expression against those of the attribute (condition="mode == 'list'").
  • It is hidden only if the expression evaluates to exactly false. Everything else shows the field: true, a text, a number, also 0 and the empty text, and likewise an error (e.g. an unknown name) or undefined. For texts, therefore, write !!name or a comparison.
  • The condition affects only the display in the panel. The value is kept even if the field is hidden; markup and LESS still see it. A hidden field must therefore be taken into account by the markup itself with vn-if.
  • It is re-evaluated on every input in the panel.
  • condition works on header, input, select, textarea and fieldset (with name).

Examples

html
condition="showKnopf"
condition="mode == 'list'"
condition="anim != 'none' &amp;&amp; anim != 'swap'"
condition="bg.type !== 'color' || vidMode != 'off'"
condition="!fullWidth"

Default values#

When a block is inserted, each value arises from its default value. The table shows what applies when nothing is specified:

FieldDefaultType of the value
textvalue or emptytext
textareacontent or emptytext
checkboxtrue with checked, otherwise falseboolean
colorvalue or #000000text
rangevalue, otherwise min, otherwise 0text
selectvalue of the option with selected, otherwise of the first optiontext
imagevalue (cleaned) or emptytext
Background widgetsee fieldsetobject

More rules:

  • File addresses: An image default file:///… is kept only if it points to the project folder. Otherwise the import tries to copy the file from this computer into the project and leaves the field empty if that fails. In packages use ../_images/….
  • Grid: range defaults belong on the grid min + n × step (see range).
  • A default value changed later in the package does not change existing blocks: their values are stored.

Automatic overlay fields#

If the template contains the word overlay anywhere (for example in class="vn-overlay" or vn-if="overlay"), there is a background widget and the block declares no field of its own named overlay, the program adds this group at the end of the panel:

FieldNameTypeDefault
Show overlayoverlayswitchoff
Overlay coloroverlayColorcolor#000000
Overlay opacityoverlayOpacityslider 0 to 1, step 0.050.5

The group is called "Overlay". If the block declares its own fields overlay, overlayColor, overlayOpacity, only its fields and defaults apply (this is the case in almost all blocks of your own).

How values reach the template and the LESS#

Every value is available in three places:

PlaceNotationExample
Markup{{name}}style="padding-top:{{abstand}}rem"
Expressions (vn-if, vn-class, vn-style, condition)namevn-if="showTitel"
LESS@namepadding-top: (@abstand * 1rem);

The LESS is recompiled on every change of a value. Details: Placeholders, Directives, LESS: Variables.

Example: a complete parameter block#

A teaser block with all input types, groups, conditions and a background widget with darkening. It was imported as a package and checked in the editor and in the export.

template.html

html
<section class="tz-teaser" vn-class="{'tz-voll': fullWidth, 'tz-mitte': ausrichtung == 'center'}">
  <vn-parameters>
    <header>Größe</header>
    <input type="checkbox" title="Volle Breite" name="fullWidth">
    <input type="range" inline title="Abstand oben (rem)" name="abstandOben" min="0" max="10" step="1" value="4">
    <input type="range" inline title="Abstand unten (rem)" name="abstandUnten" min="0" max="10" step="1" value="4">
    <header>Inhalt</header>
    <select title="Ausrichtung" name="ausrichtung">
      <option value="left" selected>Links</option>
      <option value="center">Zentriert</option>
    </select>
    <input type="checkbox" title="Kleine Zeile anzeigen" name="showKicker" checked>
    <input type="checkbox" title="Knopf anzeigen" name="showKnopf" checked>
    <input type="text" title="Kleine Zeile über der Überschrift" name="kicker" value="Neu im Programm" condition="showKicker">
    <textarea title="Vorteile (eine Zeile pro Punkt)" name="vorteile" rows="4">Schnelle Lieferung
Faire Preise
Persönliche Beratung</textarea>
    <input type="image" title="Foto" name="foto" value="">
    <header>Farben</header>
    <input type="color" title="Textfarbe" name="textFarbe" value="#1f2937">
    <input type="color" title="Akzentfarbe" name="akzent" value="#4f46e5">
    <header>Hintergrund</header>
    <fieldset name="bg" title="Hintergrund">
      <input type="image" title="Bild" value="" parallax>
      <input type="color" title="Farbe" value="#f3f4f6" selected>
    </fieldset>
    <input type="checkbox" title="Bild abdunkeln" name="overlay" checked condition="bg.type == 'image'">
    <input type="color" title="Farbe der Abdunklung" name="overlayColor" value="#000000" condition="overlay &amp;&amp; bg.type == 'image'">
    <input type="range" inline title="Stärke der Abdunklung" name="overlayOpacity" min="0" max="1" step="0.05" value="0.4" condition="overlay &amp;&amp; bg.type == 'image'">
  </vn-parameters>
  <div class="vn-overlay" vn-if="overlay &amp;&amp; bg.type == 'image'" opacity="{{overlayOpacity}}" bg-color="{{overlayColor}}"></div>
  <div class="tz-inner" vn-class="{'container': !fullWidth, 'container-fluid': fullWidth}">
    <img class="tz-foto" vn-if="!!foto" src="{{foto}}" alt="">
    <div class="tz-text">
      <p class="tz-kicker" vn-if="showKicker">{{kicker}}</p>
      <h2>Unser Angebot</h2>
      <p class="tz-vorteile">{{vorteile}}</p>
      <a class="btn btn-primary" vn-if="showKnopf" href="#">Mehr erfahren</a>
    </div>
  </div>
</section>

style.less

less
position: relative;
padding-top: (@abstandOben * 1rem);
padding-bottom: (@abstandUnten * 1rem);
color: @textFarbe;

& when (@bg-type = 'color') { background-color: @bg-value; }
& when (@bg-type = 'image') {
  background-image: url(@bg-value);
  background-size: cover;
  background-position: center;
  & when (@bg-parallax = true) { background-attachment: fixed; }
}

.tz-inner { position: relative; z-index: 1; display: flex; gap: 2rem; align-items: center; }
.tz-foto { max-width: 40%; border-radius: 0.5rem; }
.tz-vorteile { white-space: pre-line; font-size: 1.1rem; }
&.tz-mitte .tz-inner { justify-content: center; text-align: center; }
.tz-text h2 { color: @akzent; }
.tz-text .btn-primary {
  background-color: @akzent !important;
  border-color: @akzent !important;
  color: #fff !important;
}
@media (max-width: 767px) {
  .tz-inner { flex-direction: column; }
  .tz-foto { max-width: 100%; }
}

What the panel makes of it: four groups ("Größe", "Inhalt", "Farben", "Hintergrund") plus the darkening fields, which are visible only with an image background; the "small line above the heading" field only while "Kleine Zeile anzeigen" is on. The field foto is empty, so the <img> is omitted thanks to vn-if="!!foto".