Virtual Types#

Structr provides Virtual Types that allow filtering and mapping of JSON output and input via REST. The implementation is based on two entities, VirtualType and VirtualProperty. When a new VirtualType entity is created, Structr automatically creates new REST resource that matches the name property of the new entity.

A virtual type definition consists of a VirtualType instance and one or more VirtualProperty instances. A virtual type REST resource will behave like an (optionally) filtered version of the REST resource of its source type, with a fixed mapping from source property key to target property key. This mapping works in both directions, i.e. you can transform incoming JSON documents according to a given set of transformation rules and adapt it to your Structr data model, and vice-versa.

Configuration

The configuration is currently managed via the data section using the types VirtualType and VirtualProperty (a nicer interface is planned but not yet available).

VirtualType

The most important property of a virtual type is the sourceType property, which specifies the source type of the type mapping. The filterExpression property can be used to remove entities from the target collection, e.g. filter entities with invalid names etc. The filter expression is a StructrScript (*) expression that will be called for every entity in the source collection, with the current entity being available under the keyword this.

VirtualProperty

A virtual property represents the mapping of a property key from source to target, with an optional name mapping and a StructrScript (*) expression that can be used to create or transform source values. The virtual property is configured using the sourceName property, which specifies the property key of the source entity. The targetName property contains the desired target property name, or null. If the target property name is left empty, the source property name is used. A virtual property has a position attribute which specifies the position of the property in the output JSON document. The outputFunction property contains a StructrScript expression that creates or transforms the output value for the current property. It can be either a constant value, or a function that transforms the input value, which is provided using the keyword input.

* Using Serverside JavaScript is possible but may severely impact performance.

Example Configuration

VirtualType

A virtual type that maps the collection of Pages in Structr.

name:             Export
sourceType:       Page
filterExpression: and(not(empty(this.name)), not(this.hidden))

VirtualProperty 0

A simple mapping from id to page_id.

position:       0
sourceName:     id
targetName:     page_id
virtualType:    <Link to VirtualType entity>
inputFunction:  null
outputFunction: null

VirtualProperty 1

A simple mapping from name to page_name.

position:       1
sourceName:     name
targetName:     page_name
virtualType:    <Link to VirtualType entity>
inputFunction:  null
outputFunction: null

VirtualProperty 2

A virtual value that is created by a script call in outputFunction.

position:       2
sourceName:     null
targetName:     page_rank
virtualType:    <Link to VirtualType entity>
inputFunction:  null
outputFunction: calc_rank(input)

VirtualProperty 3

A constant value created by a script call.

position:       3
sourceName:     null
targetName:     const
virtualType:    <Link to VirtualType entity>
inputFunction:  null
outputFunction: 'CONSTANT STRING'

VirtualProperty 4

A mapped value that uses the graph structure.

position:       4
sourceName:     null
targetName:     owner_name
virtualType:    <Link to VirtualType entity>
inputFunction:  null
outputFunction: input.owner.name

Output

curl -i --silent -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/Export
{
        "query_time": "0.003512961",
        "result_count": 2,
        "result": [
                {
                        "page_id": "6bcdf8d2d56c4a3286de92e7ffa5aeae",
                        "page_name": "New Page 398433",
                        "page_rank": 123.0,
                        "const": "CONSTANT_STRING",
                        "owner_name": "admin"
                },
                {
                        "page_id": "847949d00a524a37a9d31a39e7b10a61",
                        "page_name": "Welcome",
                        "page_rank": 123.0,
                        "const": "CONSTANT_STRING",
                        "owner_name": "admin"
                }
        ],
        "serialization_time": "0.000137518"
}