Views #

A view in Varv is a component that renders a user interface with which users can interact. An example for a view is the DOM (document object model). Views are largely independent of the concept language and event flow of Varv and connect to the even engine in two ways: view triggers and templates.

Multiple views can be used and connected at the same time to a single event engine. Currently, we have the DOM View available for Varv but imagine adding new views for, e.g., 3D scenes or IoT environments.

View Triggers #

Triggers: Triggers are explained in the concept language section of the user guide.

View triggers are triggers that emit events coming from a view and mostly handle user interactions like—in the case of the DOM view—mouse and key inputs. View triggers are implemented as part of the view and are dependent on the view. A full list of view triggers from the DOM view is available on the Triggers section of the user guide.

Templates #

A template is used to specify how state should be represented in a view by referring to concepts in properties in them. Templates are dependent on the view and each view requires their own type of templates. In the DOM View, we use HTML as the language for the templates. In other views like, for instance, a 3D scene view, other templates like scene graphs might be required.

The view then takes these templates and retrieves the state from the event engine and generates a user interface.

The DOM View #

The DOM View is our main view for Varv at the moment. It allows to create user interfaces for Varv applications using HTML. Templates in the DOM View use specific HTML tags and attributes to add state to regular HTML. The following sections document the available tags and attributes including examples.

DOM View Template Tags #

<dom-view-template> Template Tag #

This tag is used to define which parts of the DOM of a website are part of the DOM View. When generating the view from a template inside such a tag, Varv leaves the original template untouched and creates a <varv-view> tag underneath the element, which is connected to the <dom-view-template> tag and updates automatically on any changes to the template.

It is possible to have multiple <dom-view-template> tags inside a document. When using Varv in Webstrates with Codestrates v2, for example, different templates can be placed in different body paragraphs.

Attributes:

Example:

<dom-view-template target-element="#my-view-location">
    <div concept="myConcept">{myProperty}</div>
</dom-view-template>

<div id="my-view-location"></div>

<varv-template> Template Tag #

This tag allows to create a template in Varv, which can then be referred and reused in other parts of a Varv template. It is not rendered by the DOM View and needs to be used with a <template-ref> which is explained below.

A <varv-template> needs to be named. If multiple templates with the same name exist, templates further down in the DOM will overwrite earlier ones.

Attributes:

Example:

<dom-view-template>
    <varv-template name="todo">
        <div class="todo">
            <span class="text">{text}</span>
        </div>
    </varv-template>
</dom-view-template>

<template-ref> Template Tag #

This tag allows to reference <varv-template> tags and embed them.

Attributes:

Note: The template-hook attribute only works when using the varv-domdiff-view package.

Example:

<dom-view-template>
    <varv-template name="todo">
        <div class="todo">
            <span class="text">{text}</span>
        </div>
    </varv-template>

    <div concept="todoList">
        <h3>Todos</h3>
        <div class="list">
            <div property="todos" class="todos">
                <template-ref template-name="todo"></template-ref>
            </div>
        </div>
    </div>
</dom-view-template>

DOM Text Nodes #

Curly Braces {property} Notation #

Inside tags with the concept or property attributes, the curly braces notation can be used to refer to properties of the current instance of a concept. For instance, the property "text" of a todo item can be referred to as {text}.

Example:

<dom-view-template>
    <div concept="todo">{text}</div>
</dom-view-template>

DOM View Template Attributes #

concept Template Attribute #

This attribute indicates that the element with the attribute should be rendered for each instance of the given concept.

Example:

<dom-view-template>
    <div concept="todo">This is a todo.</div>
</dom-view-template>

if Template Attribute #

This attribute can be used to render an element depending on the value of a Boolean property or type of a concept. This can be used to, for instance, hide elements depending on a property or to make use of rendering different elements depending on the concept type when using polymorphism.

Example:

{
    "concepts": {
        "shape": {
            "schema": { "visible": "boolean" }
        },
        "rectangle": {},
        "circle": {}
    },
    "extensions": [
        { "concept": "rectangle", "inject": "shape" },
        { "concept": "circle", "inject": "shape" }
    ]
}

<dom-view-template>
    <div concept="shape">
        <p>This is rendered for each shape, rectangle, and circle.</p>
        <p if="visible">This is rendered for each shape, rectangle, and circle which property "visible" is true.</p>
        <p if="concept rectangle">This is rendered for each rectangle.</p>
        <p if="concept circle">This is rendered for each circle.</p>
    </div>
</dom-view-template>

property Template Attribute #

This attribute indicates that the element with the attribute should be rendered for each instance of the given property of a concept. This means that property can only be used within a tag with the attribute concept.

The attribute can take properties with the types "array" or another "anotherConceptName" (see Schema).

An Array of Primitive Types #

If the array property handed to the attribute contains items of type "boolean", "number", or "string", then the values for each item can be accessed using the suffix .value in the curly braces notation. The element with the property attribute is rendered once for each item in the array.

Example:

{
    "concepts": {
        "myColors": {
            "schema": { "colorOptions": { "array": "string" }}
        }
    }
}

<dom-view-template>
    <div concept="myColors">
        <div property="colorOptions">{colorOptions.value}</div>
    </div>
</dom-view-template>

A Single or an Array of Concepts #

If the property handed to the attribute is a reference to another concept or an array of concepts, the properties of these instances can be accessed using the normal curly braces notation.

In case only a single concept referred, e.g., the favoriteTodo in the example below, then only one instance of the element with the property attribute is created. If it refers to an array, it renders one for each item.

Example:

{
    "concepts": {
        "todo": {
            "schema": { "text": "string" }
        },
        "todoList": {
            "schema": { "favoriteTodo": "todo" },
            "schema": { "todos": { "array": "todo" }}
        }
    }
}

<dom-view-template>
    <div concept="todoList">
        <div property="favoriteTodo">{text}</div>
        <div property="todos">{text}</div>
    </div>
</dom-view-template>

view Template Attribute #

This attribute allows to make certain elements in the DOM addressable in view triggers of the DOM View, e.g., "click".

This is useful for UI elements that do not carry state but need to be distinguishable from the way a concept is rendered in the view, e.g., in the example below we do not want to delete a todo instance if we click it anywhere but only when we click the delete button on it.

Example:

{
    "concepts": {
        "todo": {
            "schema": { "text": "string" },
            "actions": {
                "deleteOnClick": {
                    "when": { "click": { "view": "deleteButton" }},
                    "then": "remove"
                }
            }
        }
    }
}

<dom-view-template>
    <div concept="todo">
        <span class="text">{text}</span>
        <span view="deleteButton">Delete</span>
    </div>
</dom-view-template>

value Template Attribute #

This attribute makes it possible to synchronize the state of a property of a concept with the value of an input element in the DOM. This works for the following types:

Checkboxes #

This synchronizes the state of a checkbox with a Boolean property.

<input type="checkbox" value="{myBooleanProperty}">

Text Inputs #

This synchronizes the state of a input with a string property.

<input value="{myStringProperty}">

Selections #

This synchronizes the state of a checkbox with a Boolean property.

<select value="{myStringProperty}">
    <option value="optionA">Option A</option>
    <option value="optionB">Option B</option>
    <option value="optionC">Option C</option>
</select>

This can also be combined with an enum and a derived property to make a selection for an enum:

{
    "concepts": {
        "todo": {
            "schema": {
                "color": {
                    "string": {
                        "enum": [ "white", "yellow", "red", "blue" ],
                        "default": "white"
                    }
                },
                "colorOptions": {
                    "array": {
                        "items": "string",
                        "derive": {
                            "properties": [ "color" ],
                            "transform": [ { "enums": "color" } ]
                        }
                    }
                }
            }
        }
    }
}

"enum" Action: The "enums" action returns an array of elements that contains all options that are defined in the "enum" parameter of a string property.

<select class="color" value="{color}">
    <option property="colorOptions" value="{colorOptions.value}">{colorOptions.value}</option>
</select>