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.
<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
globalfrom 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(exceptheaderandfieldset) and children of other tags (div,p…) produce no field.
Groups and order in the panel#
header#
A heading in the panel. All fields up to the next heading belong to this group.
Syntax
<header>Farben</header>
<header condition="mode == 'liste'">Nur für die Liste</header>Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
| (text) | text | – | Title of the group (textContent, trimmed) |
condition | expression | – | 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)
<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):
- A header row with the block name and the buttons ★ (save as user block), ⤓ (save as
.vndext) and</> Code. - 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.
- The automatic sections (see below): anchor ID, popup, CMS, free layers, menu controls, text size, text width, text position, video addresses.
- 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. - If the template contains the word
overlayand 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>:
| Section | When | Stored as |
|---|---|---|
| Anchor ID (jump target for links/URLs) | always | block.anchorId (becomes the id of the root) |
| Popup, CMS | always | block.popup, block.cms |
| Free layers (images and text boxes) | always | in the block |
| Menu font, hamburger color, dropdown colors | if 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 type | Field type in the panel | Value in the template (JavaScript) | Value in LESS |
|---|---|---|---|
input type="text" (and any unknown type) | text field | text | quoted text |
textarea | multi-line text field | text with line breaks | quoted text |
input type="checkbox" | switch | true or false | true or false |
input type="color" | color picker | text #rrggbb | color |
input type="range" | slider with number field | text (e.g. "4") | number |
select | selection list | text (the value of the option) | quoted text |
input type="image" | image field | text (image address) | quoted text |
fieldset with image/color/video | background widget | object { type, value, parallax } | see Background variables |
text#
A single-line text field.
Syntax
<input type="text" title="Beschriftung des Knopfs" name="knopfText" value="Mehr erfahren">Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
name | identifier | – (required) | Name of the value, see Names |
title | text | the name | Label in the panel |
value | text | empty | Default value |
condition | expression | – | 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
<textarea title="Vorteile (eine Zeile pro Punkt)" name="vorteile" rows="4">Schnelle Lieferung
Faire Preise</textarea>Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
name, title, condition | as for text | ||
rows | integer 2 to 30 | 5 | Height of the field in the panel. Smaller values are ignored, larger ones are cut to 30 |
| (content) | text | empty | Default value; line breaks are kept |
Example (output with line breaks via LESS)
<p class="liste">{{vorteile}}</p>.liste { white-space: pre-line; }checkbox#
A switch. It usually controls vn-if, vn-class or a condition in the LESS.
Syntax
<input type="checkbox" title="Titel anzeigen" name="showTitel" checked>Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
name, title, condition | as for text | ||
checked | switch | off | Default "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
<input type="color" title="Akzentfarbe" name="akzent" value="#4f46e5">Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
name, title, condition | as for text | ||
value | #rrggbb | #000000 | Default 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
<input type="range" title="Abstand oben" name="abstand" min="0" max="8" step="1" value="3">Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
name, title, condition | as for text | ||
min | number | 0 | smallest value |
max | number | 100 | largest value |
step | number | 1 | step size, decimals are allowed (0.05) |
value | number | min | Default value |
inline | – | – | is not evaluated, see inline |
Example (from themes/vn-studio-src/components/header1)
<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
<select title="Ausrichtung" name="ausrichtung">
<option value="left" selected>Links</option>
<option value="center">Zentriert</option>
</select>Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
name, title, condition | as for text | ||
option value | text | – (required) | stored value. An option without value yields no usable value |
option (text) | text | – | Label in the list |
selected | switch | first option | Default. Without selected the first option applies |
Example (evaluation)
<div class="karten" vn-class="{'karten-mitte': ausrichtung == 'center'}"> … </div>& 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
<input type="image" title="Foto" name="foto" value="../_images/foto.jpg">Attributes
| Name | Value | Default | Meaning |
|---|---|---|---|
name, title, condition | as for text | ||
value | image address | empty | Default 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
<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
| Name | Value | Default | Meaning |
|---|---|---|---|
name | identifier | bg | Name of the value |
title | text | "Background" | Label in the panel |
condition | expression | – | 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
| Input | Attribute | Meaning |
|---|---|---|
input type="image" | value | Default image (rules as for image) |
input type="image" | parallax | The parallax switch is on in advance. Only effective on this input: a parallax on the fieldset is not read (checked) |
input type="color" | value | Default color, #000000 if omitted |
input type="video" | value | Default address of the background video; enables "Video" in the type selection |
| any of the three | selected | this kind is the default |
Which kind is preselected:
- If the widget has a video and it carries
selected(or there is neither image nor color), the default is video. - Otherwise image, if an image input exists and carries
selectedor there is no color. - 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)
| Kind | bg.type | bg.value | bg.parallax |
|---|---|---|---|
| Color | color | text #rrggbb | false |
| Image | image | image address (behaves in the template like text and has .url) | true or false |
| Video | video | object { url } | false |
Example (from themes/vn-studio-src/components/footer1)
<fieldset type="background" name="bg">
<input type="image" title="Bild" value="../_images/header.jpg"/>
<input type="color" title="Farbe" value="#14151d" selected/>
</fieldset><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
<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.
| Name | File kind | Allowed | Target in the project | Size |
|---|---|---|---|---|
videoFile | video | mp4, webm, ogv, m4v | assets/videos/ | up to 4 GB |
videoFile2 | video (second version) | as above | assets/videos/ | up to 4 GB |
subtitleFile | subtitles | vtt | assets/subtitles/ | up to 2 MB |
Syntax
<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)")
<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.
<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 andvn-ifno 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
<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 && bg.type == 'image'">Rules
- The expression is JavaScript and sees all values of the block under their name (
overlay,bg.type…). Helper functions such asvnEncare not available here. - In an HTML attribute write
&&as&&,<as<and>as>. 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, also0and the empty text, and likewise an error (e.g. an unknown name) orundefined. For texts, therefore, write!!nameor 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.
conditionworks onheader,input,select,textareaandfieldset(withname).
Examples
condition="showKnopf"
condition="mode == 'list'"
condition="anim != 'none' && 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:
| Field | Default | Type of the value |
|---|---|---|
text | value or empty | text |
textarea | content or empty | text |
checkbox | true with checked, otherwise false | boolean |
color | value or #000000 | text |
range | value, otherwise min, otherwise 0 | text |
select | value of the option with selected, otherwise of the first option | text |
image | value (cleaned) or empty | text |
| Background widget | see fieldset | object |
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:
rangedefaults belong on the gridmin + 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:
| Field | Name | Type | Default |
|---|---|---|---|
| Show overlay | overlay | switch | off |
| Overlay color | overlayColor | color | #000000 |
| Overlay opacity | overlayOpacity | slider 0 to 1, step 0.05 | 0.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:
| Place | Notation | Example |
|---|---|---|
| Markup | {{name}} | style="padding-top:{{abstand}}rem" |
Expressions (vn-if, vn-class, vn-style, condition) | name | vn-if="showTitel" |
| LESS | @name | padding-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
<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 && 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 && bg.type == 'image'">
</vn-parameters>
<div class="vn-overlay" vn-if="overlay && 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
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".