Data Binding Overview

Database content can be bound to elements in the DOM tree of a page using the repeater concept. There are four ways to bind data:

  • Flow
  • REST Query
  • Cypher Query
  • Function Query

The data binding dialog can be found in the Pages section when opening the properties dialog of a node. The data will then be bound to that node and it (and its subtree) will be repeated for every item found/returned.

In the context of this article, we will always use the same basic example: We will list the available projects in the database sorted by name. In each iteration the current element is made available via scripting as the defined data key (proj in these examples). Building on this, more complex data bindings can be created.

Every node returned from the database is checked for access grants. Only if the user viewing the page is allowed to see the node, the node is included in the collection which is bound to the repeater node.

Flow

The flow repeater selector lists all available flows. The return value of the selected flow is used for data binding.

REST Query

The REST repeater configuration allows entering a REST URI and supports all query features a regular REST query supports. This includes sort, order, page, pageSize, range queries etc.

It is not necessary to include the REST base path /structr/rest/.
Further, it is not necessary to create resource access grants for these REST queries as they are run internally.

Cypher Query

The cypher repeater uses the return value of a given cypher query as its data source. Depending on the return value the object accessible via the dataKey (proj in this case) may be wrapped in an object.

Function Query

In the function repeater the complete contents of the text area are interpreted as a script. By default as StructrScript but by adding { before and } after the code, it will be interpreted as JavaScript. All options described in the scripting guide are available in this scripting context.

The scripting context must return a single object or a collection of objects. If a single primitive or a collection of primitives (or a mixed collection) is returned, the result must be wrapped in an object by using the to_graph_object() builtin function. The primitives will be made available under the key value.

StructrScript

In the StructrScript context all built-in functions can be used to collect, filter, sort, etc. the data for the repeater.

JavaScript

In the JavaScript context the same built-in functions are available as in the StructrScript context but a lot of convenient JavaScript functionality is available as well.

Advanced examples

Script expressions inside the REST query and the Cypher Query are evaluated for more flexibility. Using this functionality a more advanced repeater configuration can be created.

If you are evaluating request parameters inside a cypher repeater there is a risk of cypher injection as the parameters can only be used inline. A better solution would be to use a function query repeater with the cypher() function and real parameters.