Built-in scripting functionsBuilt-In Functions

Returns the logical AND result of the given boolean values.

and(boolean1, boolean2,...)

${and(true, false)}

false

Returns a boolean value that indicates whether the given object is null or empty.

empty(obj)

${empty("")}
${empty("test")}
${empty(find("User"))}
${empty(find("NonExistentType"))}

true
false
false (if at least one user exists)
true

Returns a boolean value that indicates whether the values are identical.

equal(val1, val2)

${equal(2, 3)}

false

Returns a boolean value that indicates whether the numerical value val1 is greater than the numerical value val2. This method tries to convert its parameter objects into numerical values, i.e. you can compare strings numerically. It is often used in conjunction with size() to determine if a collection is empty or not.

gt(val1, val2)

${gt(1, 2)}

false

Returns a boolean value that indicates whether the numerical value val1 is greater than or equal to the numerical value val2. This method tries to convert its parameter objects into numerical values, i.e. you can compare strings numerically.

gte(val1, val2)

${gte(2, 3)}

false

Evaluates the given condition and executes trueExpression or falseExpression depending on the evaluation result. This method is often used in HTML attributes, for example to conditionally enable / disable CSS classes etc. To do this, you can enter a value of null in either trueExpression or falseExpression.

The is() function is a shortcut for if(condition, trueExpression, null).

if(condition, trueExpression, falseExpression)

${if(me.isAdmin, 'You have admin rights.', 'You do not have admin rights.')}

You have admin rights.

Evaluates the given condition and executes trueExpression if the evaluation result is true. If the expression evaluates to false, NULL is returned. This method is often used in HTML attributes, for example to conditionally select, check, disable form elements.

If used in other scripting contexts and the result is used further, a construct using if() is probably a better choice.

is(condition, trueExpression)

${is(equal(this.name, request.name), 'selected')}

'selected' (if the name of the current object and the requested name are equal)

Returns a boolean value that indicates whether the numerical value val1 is smaller than the numerical value val2. This method tries to convert its parameter objects into numerical values, i.e. you can compare strings numerically.

lt(val1, val2)

${lt(1, 2)}
${lt(now, now)}
${lt(now, date_add(now, 1))}

true
false
true

Returns a boolean value that indicates whether the numerical value val1 is smaller or equal than the numerical value val2. This method tries to convert its parameter objects into numerical values, i.e. you can compare strings numerically.

lte(val1, val2)

${lte(2, 2)}

true

Returns the logical negation of the given boolean argument.

not(boolean)

${not(true)}

false

Returns the logical OR result of the given boolean values.

or(boolean1, boolean2, ...)

${or(true, false)}

true

Evaluates a StructrScript expression for every element of a collection and returns true if the expression evaluates to true for all of the elements. The keyword data contains a reference to the loop variable. See also: any() and none().

all(collection, expression)

${all(user.groups, is_allowed(data, current, 'read'))}
${all(merge(6, 7, 8, 12, 15), gt(data, 10))}
${all(merge(6, 7, 8, 12, 15), gt(data, 4))}

true (if all of the users groups are allowed to read the 'current' object)
false
true

Evaluates a StructrScript expression for every element of a collection and returns true if the expression evaluates to true for any of the elements. The keyword data contains a reference to the loop variable.. See also: all() and none().

any(collection, expression)

${any(merge(6, 7, 8, 12, 15), gt(data, 10))}
${any(merge(6, 7, 8, 12, 15), gt(data, 20))}

${any(me.groups, is_allowed(data, current, 'read'))}

${any(find('User', me.id).groups, is_allowed(data, current, 'read'))}
${any(get(find('User', me.id), 'groups'), is_allowed(data, current, 'read'))}

true
false

true (if any of the users groups are allowed to read the 'current' object)

will result in an error because the dot-notation does not take precedence over the parameter parsing. The next example shows how it can be done
true (if any of the users groups are allowed to read the 'current' object)

Returns the result of removing the removeObjects from sourceList.

complement(sourceList, removeObjects...)

(1) ${complement(merge(3, 4, 2, 1, 5, 6), 5, 1, 3)}
(2) ${complement(merge(1, 2, 7, 4, 5, 6, 7, 8, 9), 1, merge(9, 7, 5), 3, merge(4, 6))}
(3) ${complement(merge(1, 2, 1), 1)}
(4) ${complement(merge(1, 2, 1), 2)}

(1) [4.0, 2.0, 6.0]
(2) [2.0, 8.0]
(3) [2.0]
(4) [1.0, 1.0]

Returns the sum of all the values in the given collection as a floating-point value. This method will most likely be used in combination with the extract() or merge() functions.

double_sum(collection)

${double_sum(merge(1, 2, 3, 4))}
${double_sum(extract(find('Product'), 'itemPrice'))}

10.0

Executes the given expression for each element in the given collection. The individual objects of the collection are passed into the filter expression sequentially, using the data key data. This method returns no content.

each(collection, eachExpression)

(1) ${each(find('User'), print(data.name))}
(2) ${each(get(first(find('User')), 'sessionIds'), print(data))}

(1) adminuser1user2user3
(2) all sessionIds for the first found user

This method iterates over the contents of the given entity collection and extracts the value for the given property key of each element. The return value of this method is a collection of extracted property values. It is often used in combination with find() and join() to create comma-separated lists of entity values.

extract(collection, propertyKey)

${extract(find('User'), 'name')}

[admin, user1, user2, user3]

Filters the given collection according to the given filter expression, returning a subset of the original collection. The filter expression can be any valid expression that returns a boolean value. This method can be used to remove single or multiple elements from an existing list of objects. The individual objects of the collection are passed into the filter expression sequentially, using the data key data.

The function will remove any object from the collection for which the filter expression returns false.

filter(collection, filterExpression)

${filter(find('User'), not(equal(data.name, 'admin')))}

unfiltered: [admin, user1, user2, user3]
filtered:   [user1, user2, user3]

Returns the first element from the given collection. This method is often used in conjunction with find() to return the first result of a query.

first(collection)

${first(find('User'))}

f02e59a47dc9492da3e6cb7fb6b3ac25

Returns the sum of all the values in the given collection as an integer value. This method will most likely be used in combination with the extract() or merge() functions.

int_sum(collection)

${int_sum(merge(1, 2, 3, 4))}

10

Returns a boolean value that indicates whether the given object is a collection.

is_collection(obj)

${is_collection(find('User'))}

true

Returns the list of property keys for the given entity or object in the given property view. Or, when used with a single parameter that is a map / non-entity object type: returns all the keys for which values are set in the given object.

keys(entity, propertyView)
keys(object)

${keys(page, 'public')}

[id, type, path, children, linkingElements, contentType, owner, cacheForSeconds, version, showOnErrorCodes, isPage, site, dontCache, pageCreatesRawData, enableBasicAuth, basicAuthRealm]

Returns the last element from the given collection. This method is often used in conjunction with find(). See also first().

last(collection)

${last(find('User'))}

f02e59a47dc9492da3e6cb7fb6b3ac25

Merges collections and objects into a single collection. This method can be used to add entities to a collection, or to merge multiple collections into a single one. All objects that are passed to this function will be added to the resulting collection. If a parameter is a collection, all objects of that collection are added to the resulting collection as well.

This method will not remove duplicate entries. Use merge_unique() for that.

merge(object...)

${merge(1, 2, 3, 4, merge(3, 4, 5, 6))}

[1.0, 2.0, 3.0, 4.0, 3.0, 4.0, 5.0, 6.0]

Merges collections and objects into a single collection, removing duplicates. This method is very similar to merge() except that the resulting collection will not contain duplicate entries.

merge_unique(object...)

${merge_unique(1, 2, 3, 4, merge(3, 4, 5, 6))}

[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]

Evaluates a StructrScript expression for every element of a collection and returns true if the expression evaluates to true for none of the elements. The keyword data contains a reference to the loop variable.

See also: any() and all().

none(collection, expression)

${none(user.groups, is_allowed(data, current, 'read'))}
${none(merge(6, 7, 8, 12, 15), gt(data, 10))}
${none(merge(6, 7, 8, 12, 15), gt(data, 20))}

true (if none of the users groups are allowed to read the 'current' object)
false
true

Returns the element with the given index from the given collection. This method is often used in conjunction with find() to return an element of the result list. See also find(), first() and last().

nth(collection, index)

${nth(find('User'), 2)}
${nth(merge('a', 'b', 'c'), 0)}
${nth(merge('a', 'b', 'c'), 2)}

f02e59a47dc9492da3e6cb7fb6b3ac25
a
c

Returns the size of the given collection.

size(collection)

${size(page.children)}
${size(merge('a', 'b', 'c'))}
${{ return $.size([1, 2, 3, 5, 8]); }}

1
3
5

IMPORTANT: The slice function has been removed with version 3.5 in favor of the advanced find access pattern.

This method returns elements from the given collection, list or array, starting at the given start argument, and ends at the given end argument.
If a queryFunction i used (i.e. find() or search) the start and end index are inserted into the cypher statement as LIMIT and SKIP parameters.

slice(queryFunction, start, end)

(1) ${slice(merge("a", "b", "c", "d"), 1, 2)}
(2) ${slice(find('User'), 0, 10)}
(3) ${slice(find('User'), 0, request.count)}

(4)
${{
	var retVal = Structr.slice(function() {
		var users = Structr.find('User');
		var files = Structr.find('File');

		return {
			f: files,
			u: users
		}
	}, 0, 2);
	
	Structr.print(retVal.f);
	Structr.print(retVal.u);
}}

(1) "b"
(2) The first 10 users
(3) The first request.count users
(4) Would print the first 2 files and the first 2 users.

Sorts the given collection according to the given property key and returns the result in a new collection. The optional parameter sortDescending is a boolean flag that indicates whether the sort order is ascending (default) or descending. This method is often used in conjunction with find().
The sort() and find() functions are often used in repeater elements in a function query, see Repeater Elements.
Parameters

sort(collection, propertyKey[, sortDescending = false])

${extract(sort(find('User'), 'name'), 'name')}
${extract(sort(find('User'), 'name', true), 'name')}

[admin, tester, user1, user2, user3]
[user3, user2, user1, tester, admin]

Combines the given nested collections into to a single, “flat” collection. This method is the reverse of extract() and can be used to flatten collections of related nodes that were created with nested extract() calls etc. It is often used in conjunction with the find() method like in the example below.

unwind(collections...)

${unwind(extract(find('Group'), 'members'))}

without unwind: [[b29e98329fb949b798162b88864aa038, 1224b74c018e4adf9cd6f5c07393f369, 6608098072bd44f68c0a9fdaa2571417]]
with unwind:    [b29e98329fb949b798162b88864aa038, 1224b74c018e4adf9cd6f5c07393f369, 6608098072bd44f68c0a9fdaa2571417]

Returns the list of property values for the given entity or object in the given property view. Or, when used with a single parameter that is a map / non-entity object type: returns all the values in the given object.

values(entity, propertyView)
values(object)

${values(page, 'public')}

Adds the given user as a member of the given group.

add_to_group(group, principal)

${add_to_group(first(find('Group', 'name', 'Admins')), me)}

Copies the security configuration of an entity to another entity. If the overwrite parameter is set to true, existing security relationships are overwritten. If it is not set (or omitted) the function works additively.

copy_permissions(sourceNode, targetNode[, overwrite = false])

Grants the given permissions on the given node to the given principal. This method creates or modifies the security relationship between the first two parameters. Valid values for the permission list are read, write, delete and accessControl. The permissions are passed in as a comma-separated list (see the examples below). The return value is the empty string. See also revoke() and is_allowed().

grant(principal, node, permissions)

${grant(me, node1, 'read')}
${grant(me, node2, 'read, write')}
${grant(me, node3, 'read, write, delete')}
${grant(me, node4, 'read, write, delete, accessControl')}

Returns a boolean value indicating the presence of the given permissions on the given node for the given principal. Valid values for the permission list are read, write, delete and accessControl. The permissions are passed in as a comma-separated list (see the examples below). See also grant() and revoke().

is_allowed(principal, node, permissions)

${is_allowed(me, group1, 'read')}
${is_allowed(me, group2, 'write')}
${is_allowed(me, group2, 'read, write')}
${is_allowed(me, group2, 'read, write, delete')}

Predicate function that returns if a given user is member of a given group.

New in v3.6: The optional parameter checkHierarchy allows to check for indirect group membership. If the given principal is member of another group which is member of the given group the result will be true.

is_in_group(group, principal [ , checkHierarchy = false ])

${is_in_group(first(find('Group', 'name', 'Admins')), me)}

Removes the given user as a member of the given group.

remove_from_group(group, principal)

${remove_from_group(first(find('Group', 'name', 'Admins')), me)}

Revokes the given permissions on the given node from the given principal. This method modifies the security relationship between the first two parameters. Valid values for the permission list are read, write, delete and accessControl. The permissions are passed in as a comma-separated list (see the examples below). The return value is the empty string. See also grant() and is_allowed().

revoke(principal, node, permissions)

${revoke(me, group1, 'read')}
${revoke(me, group2, 'read, write')}
${revoke(me, group2, 'read, write, delete')}
${revoke(me, group2, 'read, write, delete, accessControl')}

Calls the SchemaMethod with the given name and returns the result. This method is used to execute global schema methods (methods that are not associated with a type).

call(name [, key1, value1 [, ... ]] )
$.call(name [, map])

${call('methodName', 'param1', 'value1', 'param2', 'value2')}

${{
    $.call('methodName', {
        param1: 'value1',
        param2: 'value2'
    })
}}

Calls the SchemaMethod with the given name and returns the result. This method is used to execute global schema methods (methods that are not associated with a type).

call_privileged(name [, key1, value1 [, ... ]] )
$.call_privileged(name [, map])

${call_privileged('methodName', 'param1', 'value1', 'param2', 'value2')}

${{
    $.call_privileged('methodName', {
        param1: 'value1',
        param2: 'value2'
    })
}}

Returns the changelog for a specific entity. See Changelog for details on what the contents of a changelog are.

The resolve parameter controls if remote entities are resolved. Every changelog entry which has a target will be resolved as targetObj (if the remote entity still exists in the database).

Filtering (supported from version 2.2)
All filter options are chained using the boolean AND operator. Only changelog entries matching all of the specified filters will be returned.
For filter keys which can occurr more than once, the filter values are combined using the boolean OR operator (see examples 1 and 2)

(*) If a filter parameter is supplied, only changelog entries can be returned to which it is applicable. (e.g. combining key and relType can never yield a result as they are mutually exclusive)
(**) timeFrom/timeTo can be specified as a Long (time in ms since epoch), as a JavaScript Date object, or as a String with the format yyyy-MM-dd'T'HH:mm:ssZ
(***) The last supplied parameter takes precedence over the others
(****) The way we supply multiple occurrences of a keyword can differ from StructrScript to JavaScript

changelog(entity [, resolve=false [, filterKey1, filterValue2 [ , ... ] ] ] )
$.changelog(entity [, resolve=false [, map]])

1. StructrScript
	1. Return all changelog entries with verb=link
		- `changelog(node, false, 'verb', 'link')`
	2. Return all changelog entries with verb=(link OR unlink)
		- `changelog(node, false, 'verb', 'link', 'verb', 'unlink')`
	3. Return all changelog entries with (rel=OWNS) AND (verb=(link OR unlink))
		- `changelog(node, false, 'verb', 'link', 'verb', 'unlink', 'relType', 'OWNS')`
		- **Note**: filtering for the verbs link and unlink is redundant in this case as relType implies that only those verbs can be returned
	4. Return all changelog entries with (target=<NODEID>) AND (verb=(link OR unlink))
		- `changelog(node, false, 'verb', 'link', 'verb', 'unlink', 'target', '<NODEID>')`
		- **Note**: In this case the verb filter makes sense as the fitler key `target` also applies to the verbs create and delete


2. The same examples in JavaScript. For each entry both versions are identical. One uses the StructrScript way of supplying parameters, the other uses the JavaScript way.
	1. Return all changelog entries with verb=link
		- `Structr.changelog(node, false, 'verb', 'link')`
		- `Structr.changelog(node, false, {verb: 'link'});`
	2. Return all changelog entries with verb=(link OR unlink)
		- `Structr.changelog(node, false, 'verb', 'link', 'verb', 'unlink')`
		- `Structr.changelog(node, false, {verb: ['link', 'unlink']});`
	3. Return all changelog entries with (rel=OWNS) AND (verb=(link OR unlink))
		- `Structr.changelog(node, false, 'verb', 'link', 'verb', 'unlink', 'relType', 'OWNS')`
		- `Structr.changelog(node, false, {verb: ['link', 'unlink'], 'relType': 'OWNS'});`
	4. Return all changelog entries with (target=<NODEID>) AND (verb=(link OR unlink))
		- `Structr.changelog(node, false, 'verb', 'link', 'verb', 'unlink', 'target', '<NODEID>')`
		- `Structr.changelog(node, false, {verb: ['link', 'unlink'], 'target': '<NODEID>'});`

Creates a new node of the given type with the given value(s) for the given key(s). This method can be used with multiple key-value pairs. The return value is the newly created entity. See also delete().

create(type [, key1, value1 , ... ])
$(type [, map ]);

${create('User', 'name', 'tester3')}

ab6fcef53dd24793bfa67754f414c61e

Creates an object with the given properties or updates an existing object if it could be identified by a unique property. This function is a shortcut for a code sequence with a query that looks up an existing object and and a set() operation it if an object was found, or creates a new object with the given properties, if no object was found.

create_or_update(type, properties)

${create_or_update("User", "eMail", "tester@test.com", "name", "New Name")}

If no object with the given e-mail address exists, a new object is created, because "eMail" is unique.
Otherwise, the existing object is updated with the new name.

Creates a relationship of the given type between the two nodes. Please note that the inverse operation of this function is delete() since it can be used to delete both nodes and relationships. This method returns the created relationship.

create_relationship(from, to, type [, key1, value1 [, ... ]] )
$.create_relationship(from, to, type [, map ]);

${create_relationship(me, group, 'HAS')}

4793bfa4c61e67ab6fcef53dd2754f41

Deletes the given node(s) or relationship(s). This method takes multiple parameters (or a collection of objects) and returns an empty string. See also create().

delete(entity, ...)

(1) ${delete(first(find('Project')))}
(2) ${delete(find('Project'))}

(1) deletes the first project
(2) deletes all projects

Returns the value for the given property key from the given entity. This method will print an error message if the first parameter is null / not accessible. See get_or_null() for a more tolerant get method.

get(entity, propertyKey)

${get(page, 'name')}

my-page-name

Returns all incoming relationships between the given nodes, with an optional qualifying relationship type.

get_incoming_relationships(from, to [, relType ])

${get_incoming_relationships(page, me)}

[org.structr.web.entity.relation.PageLink@548b, org.structr.core.entity.relation.PrincipalOwnsNode@5820]

Returns the value for the given property key from the given entity, but doesn’t print an error message when the given entity is not accessible. See get() for the equivalent method that prints an error if the first argument is null.

get_or_null(entity, propertyKey)

${get_or_null(page, 'name')}

my-page-name

Returns all outgoing relationships between the given nodes, with an optional qualifying relationship type.

get_outgoing_relationships(from, to [, relType ])

${get_outgoing_relationships(me, page)}

[org.structr.web.entity.relation.PageLink@548b, org.structr.core.entity.relation.PrincipalOwnsNode@5820]

Returns the list of available relationship types form and/or to this node. Either potentially available (as defined in the schema) or actually available (existing relationships in the database).

get_relationship_types(node [, lookupType = 'existing' [, direction = 'both' ]])

${get_relationship_types(me, 'schema')}
${get_relationship_types(me, 'schema', 'incoming')}
${get_relationship_types(me, 'schema', 'outgoing')}
${get_relationship_types(me, 'existing')}
${get_relationship_types(me, 'existing', 'incoming')}
${get_relationship_types(me, 'existing', 'outgoing')}

[HOME_DIR, WORKING_DIR, OWNS, SECURITY, PICTURE_OF, FAVORITE, CONTAINS]
[OWNS, SECURITY, PICTURE_OF, CONTAINS]
[HOME_DIR, WORKING_DIR, OWNS, SECURITY, FAVORITE]
[OWNS, SECURITY, CONTAINS]    (user owns nodes, has permissions on nodes and is contained in a group)
[OWNS, SECURITY]              (user owns nodes and has permissions on nodes)
[CONTAINS]                    (user is contained in a group)

Returns all relationships between the given nodes, with an optional qualifying relationship type.

get_relationships(from, to [, relType ])

${get_relationships(me, page)}

[org.structr.web.entity.relation.PageLink@548b, org.structr.core.entity.relation.PrincipalOwnsNode@5820]

Returns a boolean value indicating whether at least one incoming relationship exists between the given nodes, with an optional qualifying relationship type. See also incoming(), outgoing(), has_relationship() and has_outgoing_relationship().

has_incoming_relationship(from, to [, relType ])

${has_incoming_relationship(me, page, 'OWNS')}

false

Returns a boolean value indicating whether at least one outgoing relationship exists between the given nodes, with an optional qualifying relationship type. See also incoming(), outgoing(), has_relationship() and has_incoming_relationship().

has_outgoing_relationship(from, to [, relType ])

${has_outgoing_relationship(me, page, 'OWNS')}

false

Returns a boolean value indicating whether at least one relationship exists between the given nodes, with an optional qualifying relationship type. See also incoming() and outgoing().

has_relationship(node1, node2 [, relType ])

${has_relationship(me, page, 'OWNS')}

false

Returns all incoming relationships, with an optional qualifying relationship type. This method can for example be used in the Function Query section of a Repeater Element to access the relationships of a node. See also outgoing() and has_relationship().

incoming(node [, relType ])

${incoming(page)}

[org.structr.web.entity.relation.PageLink@548b, org.structr.web.entity.relation.PageLink@5820]

Instantiates the given Neo4j node into a Structr node. This method can be used to convert raw Neo4j nodes obtained from a partial or mapped cypher() result into Structr nodes.

instantiate(neo4jNode)

${instantiate(rawNode)}

a567cfb1e66249a095097493f764b464

Returns a boolean value that indicates whether the given object is a Structr entity (i.e. a node or relationship).

is_entity(obj)

${is_entity(me)}

true

Copies the values for the given list of property keys from the source entity to the target entity.

merge_properties(source, target, propertyKeys...)

${merge_properties(this, copy, 'name', 'content', 'version'}

Returns all outgoing relationships, with an optional qualifying relationship type. This method can for example be used in the Function Query section of a Repeater Element to access the relationships of a node. See also incoming() and has_relationship().

outgoing(node [, relType ])

${outgoing(me, 'OWNS')}

[org.structr.core.entity.relationship.PrincipalOwnsNode@5977, org.structr.core.entity.relationship.PrincipalOwnsNode@596f, org.structr.core.entity.relationship.PrincipalOwnsNode@5921]

Sets the passed values for the given property keys on the specified entity, using the security context of the current user.
set() accepts several different parameter combinations, where the first parameter is always a graph object. The second parameter can either be a list of (key, value) pairs, a JSON-coded string (to accept return values of the geocode() function) or a map (e.g. a result from nested function calls or a simple map built in serverside JavaScript).

set(entity [, key1, value1, ... ])
set(entity, json)
set(entity, map)

// Key-Value examples
${set(user, 'name', 'new-user-name', 'eMail', 'new@email.com')}
${set(page, 'name', 'my-page-name')}

// JSON examples
${set(this, geocode(this.street, this.city, this.country))}
${set(me, "{name: 'new-user-name', age: 42, eMail: 'new@email.com'}")}

// JavaScript example
${{
    let me = $.me;
    $.set(me, {name: 'my-new-name', eMail: 'new@email.com'});
}}

Sets the value for the given property key on the given entity to the given value, using admin permissions.

set_privileged(entity [, key1, value1, ... ])
set_privileged(entity, json)
set_privileged(entity, map)

${set_privileged(page, 'accessCount', '2')}

Returns a CSV string representation of the given collection of objects.

to_csv(nodes, propertiesOrView[, delimiterChar = ';' [, quoteChar = '"' [, recordSeparator = "\n" [, includeHeader = true[, localizeHeader = false [, headerLocalizationDomain]]]])

${to_csv(find('User'), 'public')}
${to_csv(find('User'), merge('id', 'name'))}

"id";"type";"name";"isUser"
"70fd9f831cad4506a1076f956ffa2a0b";"User";"admin";"true"
"id";"name"
"70fd9f831cad4506a1076f956ffa2a0b";"admin"

Returns a XLSX string representation of the given collection of objects.

to_excel(nodes, propertiesOrView[, includeHeader = true[, localizeHeader = false [, headerLocalizationDomain[, maxCellLength = 32767 [, overflowMode = 'o']]]]])

1. Create a new file "new_document.xlsx" containing the list of users.
${set_content(create('File', 'name', 'new_document.xlsx'), to_excel(find('User'), 'public'), 'ISO-8859-1')}

2. Both of the following examples would results in a downloadable file named `user-export.xlsx` containing the list of users.
The scripts would need to be placed in a [dynamic file](438) with the charset `charset=ISO-8859-1` appended to the content-type.
${(
    set_response_header('Content-Disposition', 'attachment; filename="user-export.xlsx"'),
    to_excel(find('User'), 'public')
)}

${{
    // JavaScript Example
    $.setResponseHeader('Content-Disposition', 'attachment; filename="user-export.xlsx"');
    $.print(Structr.toExcel(Structr.find('User'), 'public'));
}}

3. The following example would result in a downloadable file named `users-truncated.xlsx` where all cells are truncated after 1000 characters. The parameters concerning the header row configure that a header is printed which is not localized.
The scripts would need to be placed in a [dynamic file](438) with the charset `charset=ISO-8859-1` appended to the content-type.
${{
    $.setResponseHeader('Content-Disposition', 'attachment; filename="users-truncated.xlsx"');
    $.print(Structr.toExcel(Structr.find('User'), 'excelView', true, false, '', 1000, 't'));
}}

Tries to convert given object or collection containing graph objects into a graph object. If an element in the source can not be converted to a graph object, it is ignored. Graph objects can be used in repeaters for example and thus it can be useful to create custom graph objects for iteration in such contexts. The optional view parameter can be used to select the view representation of the entity. If no view is given, the public view is used. The optional depth parameter defines at which depth the conversion stops. If no depth is given, the default value of 3 is used.

to_graph_object(source [, view = 'public' [, depth = 3]])

(1)
${{
	var coll = $.to_graph_object([
		{id:"o1",name:"objectA"},
		{id:"o2",name:"objectB"}
	]);
	$.print(coll.join(', '));	
}}

(2)
${to_graph_object(inheriting_types('Principal'))}

(1) {id=o1, name=objectA}, {id=o2, name=objectB}

(2) [{value=Principal},{value=Group},{value=LDAPGroup},{value=LDAPUser},{value=User}]

Returns a JSON string representation of the given object very similar to JSON.stringify() in JavaScript. The output of this method will be very similar to the output of the REST server except for the response headers and the result container. The optional view parameter can be used to select the view representation of the entity. If no view is given, the public view is used. The optional depth parameter defines at which depth the JSON serialization stops. If no depth is given, the default value of 3 is used.

to_json(source [, view = 'public' [, depth = 3]])

${to_json(me)}

{ "id": "6608098072bd44f68c0a9fdaa2571417", "type": "User", "isUser": true, "name": "tester1" }

Allows temporary access to read-only properties. This method will cause a single following call to set() on a read-only property to succeed. See also set_privileged().

unlock_readonly_properties_once(node)

Allows temporary access to system properties. This method will cause a single following call to set() on a system property to succeed. See also set_privileged().

unlock_system_properties_once(node)

Returns the changelog for the changes a specific user made.

user_changelog(user [, resolve=false [, filterKey1, filterValue2 [ , ... ] ] ] )
$.user_changelog(user [, resolve=false [, map]])

Returns the geocoding result for the given parameters. See Geocoding Configuration for more information. This method returns a nested object with latitude / longitude that can directly be used in the set() method.

geocode(street, city, country)

${set(this, geocode(this.street, this.city, this.country))}

Imports a GPX string and returns a complex object with its contents.

add(gpxString)

${ import_gpx( get_content( first(find('File', 'name', '20090815.gpx')) ) ) }

(Note: Indentation added for documentation purposes)
{
  tracks = [
    {
      segments = [
        {
          points = [
            {latitude=50.121096, longitude=8.641047, time=2009-08-15T08:37:23Z, altitude=168.3, horizontalDilution=3.2, verticalDilution=1.0, positionDilution=3.3},
            {latitude=50.12099, longitude=8.639938, time=2009-08-15T08:37:37Z, altitude=168.3, horizontalDilution=3.2, verticalDilution=1.0, positionDilution=3.3}
          ]
        }
      ]
    }
  ]
}

Converts the given latitude/longitude coordinates into an UTM string.

lat_lon_to_utm(latitude, longitude)

${lat_lon_to_utm(53.85499997165232, 8.081674915658844)}

"32U 439596 5967780"

Converts the given UTM string into latitude/longitude coordinates.

utm_to_lat_lon(utmString)

${utm_to_lat_lon("32 N 439596 5967780")}

{latitude=53.85499997165232, longitude=8.081674915658844}

Sends an HTTP DELETE request with an optional content type to the given url. This method can be used to make HTTP requests from within the Structr Server, triggered by a frontend control like a button etc.

The DELETE() method will return a response object with the following structure:

DELETE(url [, contentType = 'application/json' ])

${DELETE('http://localhost:8082/structr/rest/User/6aa10d68569d45beb384b42a1fc78c50')}

{body={code=401.0, message=Forbidden}, status=401, headers={Date=Tue, 22 Dec 2015 16:39:20 GMT, Content-Type=application/json; charset=utf-8, Content-Length=44, Server=Jetty(9.2.9.v20150224)}}

This method makes a server-side HTTP GET request to the given url and returns the literal HTTP response (without the headers - If you are interested in the response headers, use the HEAD() function).

The contentType only serves as way to handle certain formats differently:
- The value text/html parses the returned text as HTML using JSOUP and allows for an optional third parameter selector to select a subset of the HTML response, as documented in the JSOUP Cookbook.
- From version 3.5 onwards, GET() supports binary content by setting the contentType parameter to application/octet-stream. (This is helpful when creating files - see below example)
- Any other value for contentType simply returns the literal HTTP response

GET(url [, contentType [, username, password]])

GET(url, 'text/html', selector)
GET(url, 'application/octet-stream' [, username, password]])

(1) ${GET('http://localhost:8082/structr/rest/User')}

(2)
${
(
  add_header('X-User', 'admin'),
  add_header('X-Password', 'admin'),
  GET('http://localhost:8082/structr/rest/User')
)
}

(3) ${GET('http://www.google.com', 'text/html')}
(3a) ${GET('http://www.google.com', 'text/html; charset=UTF-8')}
(3b) ${GET('http://www.google.com', 'text/html; charset=ISO-8859-1')}

(4) ${GET('http://www.google.com', 'text/html', '#footer')}

(5) ${set_content(create('File', 'name', 'google_logo.png'), GET('https://www.google.com/images/branding/googlelogo/1x/googlelogo_light_color_272x92dp.png', 'application/octet-stream'))}

(1) An "Access denied" message with code 401 from that structr instance (depending on the configuration of that instance)

(2) The list of users from that structr instance (depending on the configuration of that instance)

(3) The front page of google.com
(3a) The front page of google.com (since the server sends a charset in the response, the given charset parameter is overridden)
(3b) The front page of google.com (since the server sends a charset in the response, the given charset parameter is overridden)

(4) The HTML element with the ID 'footer' from google.com

(5) A new file with the google logo is created in the local structr instance

Sends an HTTP HEAD request to the given url. This method can be used to make HTTP requests from within the Structr Server, triggered by a frontend control like a button etc. The optional username and password parameters can be used to authenticate the request.

The HEAD() method will return a response object with the following structure:

HEAD(url [, username, password ])

${HEAD('http://localhost:8082/structr/rest/User', 'tester', 'test')}

{status=401, headers={Date=Tue, 22 Dec 2015 16:53:30 GMT, Content-Type=application/json; charset=ISO-8859-1, Connection=close, Server=Jetty(9.2.9.v20150224)}}

Send an HTTP POST request with the given body to the given url. This method can be used to make HTTP requests from within the Structr Server, triggered by a frontend control like a button etc.

The POST() method will return a response object containing the reposonse headers, body and status code. The object has the following structure:

POST(url, body [, contentType = 'application/json' [, charset = 'utf-8' ] ] )

${POST('http://localhost:8082/structr/rest/User', '{name: "Tester"}')}

{body={code=401.0, message=Forbidden}, status=401, headers={Date=Tue, 22 Dec 2015 16:39:20 GMT, Content-Type=application/json; charset=utf-8, Content-Length=44, Server=Jetty(9.2.9.v20150224)}}

Send an HTTP PUT request with the given body to the given url. This method can be used to make HTTP requests from within the Structr Server, triggered by a frontend control like a button etc.

The PUT() method will return a response object with the following structure:

PUT(url, body [, contentType = 'application/json' [, charset = 'utf-8' ]] )

${PUT('http://localhost:8082/structr/rest/User/6aa10d68569d45beb384b42a1fc78c50', '{"name": "Tester"}')}

{body={code=401.0, message=Forbidden}, status=401, headers={Date=Tue, 22 Dec 2015 16:39:20 GMT, Content-Type=application/json; charset=utf-8, Content-Length=44, Server=Jetty(9.2.9.v20150224)}}

Temporarily adds the given (key, value) tuple to the local list of request headers. All headers in this list will be added to any subsequent GET(), HEAD(), POST(), PUT() or DELETE() call in the same request (meaning the request from the client to structr).

add_header(key, value)

(1) StructrScript
${
    (
        add_header('X-User', 'tester1'),
        add_header('X-Password', 'test'),
        GET('http://localhost:8082/structr/rest/User')
    )
}

(2) JavaScript
${{
    $.add_header('X-User', 'tester1');
    $.add_header('X-Password', 'test');
    let result = $.GET('http://localhost:8082/structr/rest/User');
}}

{ "code": 401, "message": "Wrong username or password, or user is blocked. Check caps lock. Note: Username is case sensitive!" }
(Please note that this example deliberately uses the wrong credentials to provoke the above error message.)

Removes all headers previously set with add_header() in the same request.

clear_headers()

Returns the value of the HTTP request header with the given name. This method can be used both in Entity Callback Functions and in the Page Rendering process to obtain the value of a given HTTP header, allowing the user to use HTTP headers from their web application clients to control features of the application.

get_request_header(name)

${get_request_header('User-Agent')}

Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:43.0) Gecko/20100101 Firefox/43.0

Sets the response code of the current rendering run. Very useful in conjunction with set_response_header() for redirects.

set_response_code(value)

${set_response_code(302)}

Sets the value of the HTTP response header with the given name to the given value. This method can be used to set and/or override HTTP response headers in the Structr server implementation to control certain aspects of browser / client behaviour.

set_response_header(name, value)
set_response_header(name, value [, override]) // New in v.3.6

${set_response_header('Content-Type', 'text/csv')}

Enables or disables certificate validation for outgoing requests. All subsequent GET(), HEAD(), POST(), PUT() or DELETE() calls in the same request (meaning the request from the client to structr) will use the setting configured here.

validate_certificates(true)
validate_certificates(false)

${{
    $.validate_certificates(false);
    let result = $.GET('https://www.domain-with-invalid-certificate.com/resource.json');
}}

Appends a string representation of the given values to a file underneath the Structr exchange/ directory. See Anatomy of a Structr application for more information.

append(filepath, data...)

${append('info.txt', 'Hello, ', 'world!')}
${append('subdir/info.txt', 'Hello, ', 'world!')}

Appends the given content to the given file.

append_content(file, content[, encoding = "UTF-8"])

append_content(first(find('File', 'name', 'test.txt')), '\nAdditional Content')

Copies the content of sourceFile to targetFile and updates the meta-data accordingly.

copy_file_contents(sourceFile, targetFile)

Creates and returns a ZIP archive with the given file (and folder) nodes and saves that archive under the name given as the first parameter.
The third parameter CustomFileType can be used if the schema defines a type inheriting from File and we want the archive to be of that type.

create_archive(archiveFileName, files[, CustomFileType])

${create_archive("logs", find("Folder", "name", "logs"))}
${{Structr.createArchive("logs", Structr.find("Folder", "name", "logs"))}}

Creates and returns a ZIP archive with the given name (first parameter), containing the given files/folders (second parameter).
By setting a password as the optional third parameters, the ZIP file will be encrypted.
If the optional fourth parameter is aes or AES, the ZIP file will be encrypted with the AES256 method.

create_zip(archiveFileName, files [, password [, encryptionMethod ] ])

${create_zip('test_encrypted', merge(find('Folder', 'name', 'a'), find('Folder', 'name', 'b')), 'mySecretPassword', 'aes')}

This function either behaves like a no-op or it behaves exactly like the log() function. This depends on the configuration setting log.debug.

debug(objects...)

Executes the script with the given name. In order to prevent execution of arbitrary code from the Structr rendering context, the script must be registered in structr.conf file using the following syntax.
key.for.my.script = my-script.sh
Upon successful execution, the exec() call returns the complete output of the script (not the return value).

exec(scriptConfigKey [, parameterArray [, logBehaviour ] ])

// deprecated from v6.0
exec(key [, parameters... ] )

// will not log to command line
${{ $.exec('key.for.my.script', ['param1', 'param2'], 0) }}

// will log to command line as '<path to script> "param1" "***"'
${{ $.exec('key.for.my.script', ['param1', { value: 'CLIENT_SECRET', mask: true }], 2) }}

// deprecated from v6.0+
${exec('key.for.my.script', 'param1', 'param2')}

Hello from my-script.sh!

This method is very similar to exec(), but instead of returning the (text) result of the execution, it will copy its input stream to the given output buffer without modifying the binary data. This is important to allow streaming of binary data from a script to the client.

exec_binary(output, scriptConfigKey [, parameterArray [, logBehaviour ] ])

// deprecated from v6.0
exec_binary(output, key [, parameters... ] )

${exec_binary(response, 'my.create.pdf')}
results in the streaming of the binary content of the `my.create.pdf` script to the client.

This method is used to execute a particular flow and returns the evaluation result of the Flow with the given effective name.

flow(effectiveName [, parameters... ])
flow(effectiveName [, parameterMap ])

$.flow('package1.flow1', {
    'parameter1' : 42,
    'parameter2' : 3.14
})

Retrieves the content of the given file from the Structr filesystem. This method can be used to access the binary content of a file stored in Structr

get_content(file[, encoding = "UTF-8"])

${get_content(first(find('File', 'name', 'test.txt')))}

Prints a string representation of the given objects to the Structr log file.

log(objects...)

${log('Hello, world')}

Returns a PDF string representation of the given page.
Parameters
- page: The page that should be rendered as a PDF
- wkhtmltopdfParameter: This string is passed to wkhtmltopdf and may contain all parameters that wkhtmltopdf accepts
- a useful parameter is --disable-smart-shrinking
- baseUrl: The baseUrl for the main page (the header and footer page need the baseUrl explicitly as they are currently provided as a string)
- defaults to the value of the keyword base_url
- runWithXServer: Forces the usage of xvfb
- xServerSettings: parameters for xvfb

pdf(page [, wkhtmltopdfParameter, baseUrl, runWithXServer, xServerSettings])

1. Dynamic file which automatically downloads
   (using 3 pages: 'pdf-export-main-page', 'pdf-export-header-page' and 'pdf-export-footer-page')

${{
    // download pdf file as "my-downloaded-file.pdf"
    $.setResponseHeader('Content-Disposition', 'attachment; filename="my-downloaded-file.pdf"');
    $.set_response_header('Cache-Control', 'no-cache');
    // These variables reference local pages in the structr installation
    let main   = 'pdf-export-main-page/';
    let header = '--header-html ' + Structr.get('base_url') + '/pdf-export-header-page/';
    let footer   = '--footer-html ' + Structr.get('base_url') + '/pdf-export-footer-page/';
    let wkhtmlArgs   = header + ' ' + footer + ' --disable-smart-shrinking';
    let pdf = Structr.pdf(main, wkhtmlArgs);
    $.print(pdf);
}}


2. Creates a new file for each run of the script:

${set_content(create('File', 'name', 'new_document.pdf'), pdf('pdf-export-page'), 'ISO-8859-1')}

Returns the contents of a file underneath the Structr exchange/ directory. See Anatomy of a Structr application for more information.

read(filepath)

${read('helloworld.txt')}
${read('subdir/helloworld.txt')}

Hello, world!

Overwrites the contents of the given file with the given content.

set_content(file, content[, encoding = "UTF-8"])

1. Simply overwrite file with static content
${set_content(first(find('File', 'name', 'test.txt')), 'New Content Of File test.txt')}

2. Create new file with Excel content
${set_content(create('File', 'name', 'new_document.xlsx'), to_excel(find('User'), 'public'), 'ISO-8859-1')}

3. Create a new file and retrieve the last 100 tweets from @structr
You first need to create a Twitter application and a corresponding bearer token (see https://developer.twitter.com/en/docs/basics/authentication/api-reference/token for more information)
${(
    add_header('Authorization', 'Bearer <YOUR PERSONAL BEARER TOKEN GOES HERE>'),
    set_content(create('File', 'name', 'structr-tweets.json'), 
    GET('https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=structr&count=100'))
)}

4. Download binary data (an image) and store it in a local file
${set_content(create('File', 'name', 'google_logo.png'), GET('https://www.google.com/images/branding/googlelogo/1x/googlelogo_light_color_272x92dp.png', 'application/octet-stream'))}

Writes a string representation of the given values to a file underneath the Structr exchange/ directory. See Anatomy of a Structr application for more information.

write(filepath, data...)

${write('info.txt', 'Hello, ', 'world!')}
${write('subdir/info.txt', 'Hello, ', 'world!')}

Tries to parse the contents of the given string into an XML document, returning the document on success. This method can be used in conjunction with read() and xpath() to read data from an XML file on disk.

xml(string)

${xml(read('test.xml'))}

[#document: null]

Sends an HTML e-mail with the given configuration. See Mail Configuration for more information. The e-mail methods are the main use-case for the template() method.

Available from 2.0.2: An optional list of files (instances of File) can be passed to the command. The files will be sent as e-mail attachments.

send_html_mail(fromAddress, fromName, toAddress, toName, subject, htmlContent, textContent [, attachments] )

${send_html_mail('info@structr.com', 'Structr', 'user@domain.com', 'Test User', 'Welcome to Structr', '<p>Hi <b>User</b>,</p><p>welcome to Structr!</p>', 'Hi User,\n\nwelcome to Structr!')}

Sends an e-mail with the given configuration. See Mail Configuration for more information. The e-mail methods are the main use-case for the template() method.

send_plaintext_mail(fromAddress, fromName, toAddress, toName, subject, content)

${send_plaintext_mail('info@structr.com', 'Structr', 'user@domain.com', 'Test User', 'Welcome to Structr', 'Hi User, welcome to Structr!')}

Begins an HTML e-mail with the basic given configuration. See Mail Configuration for more information. The e-mail methods are the main use-case for the template() method. The recipients are added via the mail_add_to(), mail_add_cc() and mail_add_bcc() functions. This is separated out to allow for emails with only CC and/or BCC addresses.
An optional list of files (instances of File) can be passed to the command. The files will be sent as e-mail attachments. For more granular control the mail_add_attachment() function can be used.
This is a convenience method where we can supply multiple parameters at once. Alternatively we can use mail_set_from(), mail_set_subject(), mail_set_html_content(), mail_set_text_content() and mail_add_attachment(). This is especially helpful if we are trying to send a series of mails with nearly identical content.

mail_begin(fromAddress [, fromName [, subject [, htmlContent [, textContent [, files]]]]] )

${mail_begin('info@structr.com', 'Structr', 'Welcome to Structr', 'Hi User, welcome to Structr!')}

Overwrites/Sets the from address (and optionally name) of the current mail.

mail_set_from(fromAddress [, fromName])

${mail_set_from('support@structr.com', 'Structr Support')}

Overwrites/Sets the subject of the current mail.

mail_set_subject(subject)

${mail_set_subject('Reply for you support ticket')}

Overwrites/Sets the HTML content of the current mail.

mail_set_html_content(htmlContent)

${mail_set_html_content('<b>HTML</b> content')}

Sets/Overwrites the text content of the current mail.

mail_set_text_content(textContent)

${mail_set_text_content('Plaintext content')}

Adds a To: recipient to the list of recipients. Can be called multiple times to add more recipients. The toName can be omitted.

mail_add_to(toAddress [, toName] )

${mail_add_to('info@structr.com', 'Structr')}

Clears the current list of To: recipients.

mail_clear_to()

${mail_clear_to()}

Adds a Cc: recipient to the list of recipients. Can be called multiple times to add more recipients. The ccName can be omitted.

mail_add_cc(ccAddress [, ccName] )

${mail_add_cc('info@structr.com', 'Structr')}

Clears the current list of Cc: recipients.

mail_clear_cc()

${mail_clear_cc()}

Adds a Bcc: recipient to the list of recipients. Can be called multiple times to add more recipients. The bccName can be omitted.

mail_add_bcc(bccAddress [, bccName] )

${mail_add_bcc('info@structr.com', 'Structr')}

Clears the current list of Bcc: recipients.

mail_clear_bcc()

${mail_clear_bcc()}

Sets the bounce address - the address to which undeliverable messages will be returned if undeliverable.

mail_set_bounce_address(bounceAddress)

${mail_set_bounce_address('bounce@structr.com')}

Removes the bounce address from the current mail.

mail_clear_bounce_address()

${mail_clear_bounce_address()}

Clears the current list of Reply-To: addresses.

mail_clear_reply_to()

${mail_clear_reply_to()}

Adds a Reply-To: address to the current mail. The replyToName can be omitted. Can be called multiple times.

mail_add_reply_to(replyToAddress[, replyToName])

${mail_add_reply_to('reply-to@structr.com')}

Adds a file (instances of File) as an attachment to the mail. The name parameter can be used to send the file with a different name than the filename in the Structr filesystem.

mail_add_attachment(fileNode [, name] )

${mail_add_attachment(first(find('File', 'name', 'static-file.txt')), 'renamed-static-file.txt')}

Clears the attachments from the current mail.

mail_clear_attachments()

${mail_clear_attachments()}

Adds a custom header to the mail.

mail_add_header(name, value)

${mail_add_header('X-Mailer', 'Structr')}

Removes a single custom header from the mail.

mail_remove_header(name)

${mail_remove_header('X-Mailer')}

Clears any configured custom headers for the current mail.

mail_clear_headers()

${mail_clear_headers()}

Indicates that the mail is a reply to the message with the given messageId. This function automatically sets the In-Reply-To header of the mail so that the receiving mail client can handle it correctly.
This function is especially interesting in conjunction with the mail_save_outgoing_message() function.

mail_set_in_reply_to(messageId)

${mail_set_in_reply_to('<1910177794.5.1555059600315.JavaMail.username@machine.local>')}

Indicates that the next mail is not a reply to a message. This function automatically clears the In-Reply-To header of the mail.
This function is only useful after sending a previous message with a configured In-Reply-To.

mail_clear_in_reply_to()

${mail_clear_in_reply_to()}

Configures the Advanced Mail Module that the next invocation of mail_send() should save the outgoing email as an EMailMessage node.
Configured attachments are copied and attached to the EMailMessage node. For attached dynamic files the evaluated result is saved as a static file.
After the mail_send() command is finished, the outgoing message can be accessed via mail_get_last_outgoing_message().

mail_save_outgoing_message(boolean)

${mail_save_outgoing_message(true)}

Returns the outgoing message as the saved EMailMessage node.

mail_get_last_outgoing_message()

${mail_get_last_outgoing_message()}

Sends the currently configured mail and returns the message-id of the created mail.
If not all pre-conditions are met or the sending of the mail fails, an empty string will be returned and an error message is logged.

Since v3.6 the error message can be retrieved via mail_get_error() and the presence of an error can be checked via mail_has_error(). Before attempting to send the mail, the last error (if any) is cleared automatically.

mail_send()

${mail_send()}

Decode “unstructured” headers, that is, headers that are defined as ‘*text’ as per RFC 822.
The string is decoded using the algorithm specified in RFC 2047, Section 6.1. If the charset-conversion fails for any sequence, it is returned as-is.
If the String is not an RFC 2047 style encoded header, it is also returned as-is

mail_decode_text(text)

${mail_decode_text('=?utf-8?Q?h=C3=A4llo?=')}

hällo

Encode a RFC 822 “text” token into mail-safe form as per RFC 2047.
The given Unicode string is examined for non US-ASCII characters. If the string contains only US-ASCII characters, it is returned as-is. If the string contains non US-ASCII characters, it is first character-encoded using the platform’s default charset, then transfer-encoded using either the B or Q encoding. The resulting bytes are then returned as a Unicode string containing only ASCII characters.
Note that this method should be used to encode only “unstructured” RFC 822 headers.

mail_encode_text(text)

${mail_encode_text('hällo')}

=?utf-8?Q?h=C3=A4llo?=

Allows selecting a different SMTP configuration (as configured in structr.conf) for the current outgoing mail. The 6 SMTP settings can be overridden individually by adding a prefixed configuration entry. If no entry is found the default (non-prefixed) value is used.

mail_select_config(name)

${mail_select_config('myDifferentConfig')}

**Example structr.conf**
[...]
smtp.host = <server>
smtp.port = <port>
smtp.user = <user>
smtp.password = <password>
smtp.tls.enabled = true
smtp.tls.required = true
myDifferentConfig.smtp.host = <server>
myDifferentConfig.smtp.port = <port>
myDifferentConfig.smtp.user = <user>
myDifferentConfig.smtp.password = <password>
myDifferentConfig.smtp.tls.enabled = true
myDifferentConfig.smtp.tls.required = true
[...]

New in v3.6: Allows setting completely manual/dynamic SMTP configuration for the current outgoing mail.

mail_set_manual_config(smtpHost = 'localhost', smtpPort = 25, smtpUser = null, smtpPassword = null, smtpUseTLS = true, smtpRequireTLS = true)

${mail_set_manual_config('smtp.example.com', 587, 'myUser', 'password', true, true)}

New in v3.6: Allows resetting a previously set manual/dynamic SMTP configuration for the current outgoing mail.

mail_reset_manual_config()

${mail_reset_manual_config()}

New in v.3.6: Allows to check for errors when sending a mail.

${mail_has_error()}

${{

  $.mail_begin('user@example.com', 'User', 'Test Mail', '<b>HTML</b> message', 'plain text message');
  $.mail_add_to('another-user@example.com');
  $.mail_send();

  $.log($.mail_has_error());
}}

true if an error occurred - false if not.

New in v.3.6: Allows to retrieve the last error message when sending a mail.

${mail_get_error()}

${{

  $.mail_begin('user@example.com', 'User', 'Test Mail', '<b>HTML</b> message', 'plain text message');
  $.mail_add_to('another-user@example.com');
  $.mail_send();

  if ($.mail_has_error()) {
    // react to error here
    $.log($.mail_get_error());
  }
}}

(example error)
Sending the email to the following server failed : smtp.example.com:587
535-5.7.8 Username and Password not accepted.

Aborts the current request if the given condition evaluates to false and returns the given error message with the status code.

assert(condition, statusCode, message)

assert(eq(me.name, 'admin'), 422, 'Only admin account is allowed to access this resource')

Creates a barcode image of the given type with the given data using the zxing library. The library supports several different barcode types.

barcode(type, data[, width = 200, height = 200 [, hintKey, hintValue, ...]])
$.barcode(type, data[, width = 200, height = 200 [, hintMap]])

(1) Usage in a dynamic file

- File content: ${barcode('QR_CODE', 'My testcode', 200, 200, "MARGIN", 0, "ERROR_CORRECTION", "Q")}
- File content-type: image/png;charset=ISO-8859-1

(2) Usage in a HTML IMG tag

- src attribute:  data:image/png;base64, ${base64encode(barcode('QR_CODE', 'My testcode', 200, 200, 'MARGIN', 0, 'ERROR_CORRECTION', 'Q'), 'basic', 'ISO-8859-1')}

Enables batching for the given expression, i.e. if the expression contains a long-running function (for example the deletion of all nodes of a given type, see examples below), that function will be instructed to commit its results in batches of batchSize.
Useful in situations where large numbers of nodes are created, modified or deleted in a StructrScript expression.

In JavaScript the batch() function takes a worker function as its first parameter and an optional error handler function as its second parameter. If the worker function returns true, it is run again. If it returns anything else it is not run again. If an exception occurs in the worker function, the error handler function (if present) is called. If the error handler returns true, the worker function is called again. If the error handler function returns anything else (or an exception occurs) the worker function is not run again.

batch(expression, batchSize)

// DEPRECATED in JavaScript!
$.batch(workerFunction [, errorHandlerFunction ] )

${batch(delete(find('Item')), 1000)}
${batch(each(find('Item'), set(data, "visibleToPublicUsers", true)), 1000)}


${{
    /* Iterate over all users in packets of 10 and do stuff */
    let pageSize = 10;
    let pageNo    = 1;

    $.batch(function() {
        let nodes = $.find('User', $.predicate.page(pageNo, pageSize));      // in structr versions lower than 4.0 replace "$.predicate.page" with "$.page"
		
        // compute-heavy stuff
		
        pageNo++;
	
        return (nodes.length > 0);
    }, function() {
        $.log('Error occurred in batch function. Stopping.');
        return false;
    });
}}

Triggers the sending of a sever-sent event all authenticated and/or anonymous users with an open connection.

broadcast_event(eventType, message [, authenticatedUsers = true [ , anonymousUsers = false ]] )

broadcast_event('myTopic', 'Topic message', true, false)

$.broadcastEvent('myJSONTopic', JSON.stringify({id: 'APP_MAINTENANCE_SOON', message: 'Application going down for maintenance soon!', date: new Date().getTime()}), true, false);

This method can be used to store a value (which is costly to obtain or should not be updated frequently) under the given key in a global cache. The method will execute the given valueExpression to obtain the value, and store it for the given time (in seconds). All subsequent calls to the cache() method will return the stored value (until the timeout expires) instead of evaluating the valueExpression.

cache(key, timeout, valueExpression)

${cache('externalResult', 3600, GET('http://api.myservice.com/get-external-result'))}

${{
    // (1) Simple example
    $.cache('myCacheKey', 3600, 'initialCacheValue');
    $.cache('myCacheKey', 3600, 'test test test');
    $.log($.cache('myCacheKey', 3600, 'test 2 test 2 test 2'));
    /* will log `initialCacheValue` to the server log. */

    (2) Lazily evaluated example
    $.cache('externalResult', 3600, () => {
        return $.GET('http://api.myservice.com/get-external-result');
    });
}}

Returns the configuration value associated with the given key from structr.conf. This method can be used to read arbitrary values from the configuration file and use it to configure frontend behaviour, default values etc. The optional second parameter is the default value to be returned if the configuration key is not present.

config(key[, default])

${config('files.path')}
${config('some.unconfigured.key', 'default value')}

./files
default value

Creates an JWT access_token for the given User entity that can be used for request authentication

create_access_token(user [, accessTokenTimeout])

${create_access_token(me [, 15])}

eyJhbGciOiJIUzUxMiJ9.eyJ[...]2Q1In0.K_o-mIjzJZlr3pWOjYBotD_JUeGZ1sS5necqKhfpfhy8yTbaKxRtpPMafBpQEvcH6dmKZ9kNhu5PGkvtKE_MFA

Creates an JWT access_token together with an refresh_token for the given User entity that can be used for request authentication and authorization.

create_access_and_refresh_token(user [, accessTokenTimeout, refreshTokenTimeout])

${create_access_and_refresh_token(me, 15, 60)}

{
   "access_token":"eyJhbGciOiJIUzUxMiJ9.eyJ[...]VkIn0.fbwKEQ4dELHuXXmPiNtn8XNWh6ShesdlTZsXf-CojTmxQOWUxkbHcroj7gVz02twox82ChTuyxkyHeIoiidU4g",
   "refresh_token":"eyJhbGciOiJIUzUxMiJ9.eyJ[...]lbiJ9.GANUkPH09pBimd5EkJmrEbsYQhDw6hXULZGSldHSZYqq1FNjM_g6wfxt1217TlGZcjKyXEL_lktcPzjOe_eU3A",
   "expiration_date":"1616692902820"
}

Returns a keyed-hash message authentication code generated out of the given payload, secret and hash algorithm.

hmac(value, secret [, hashAlgorithm ])

$.hmac(JSON.stringify({key1: "test"}), "aVeryGoodSecret")

5d1ab1de51a9e23d52dfb12a6b355420e84ca467b0071d2a58d9915e383e09d5

Removes the given function form the current transaction context and allows batching of a given expression, i.e. if the expression contains a long-running function (for example the deletion of all nodes of a given type, see examples below), that function will be instructed to commit its results in batches of batchSize.
Useful in situations where large numbers of nodes are created, modified or deleted.

This function is only available in JavaScript and takes a worker function as its first parameter and an optional error handler function as its second parameter. If the worker function returns true, it is run again. If it returns anything else it is not run again. If an exception occurs in the worker function, the error handler function (if present) is called. If the error handler returns true, the worker function is called again. If the error handler function returns anything else (or an exception occurs) the worker function is not run again.

New in v4.0: The errorHandler function now has a parameter where the error(/exception) is available. Depending on the error type, different methods are available on that object. Syntax errors will yield a PolyglotException (see https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/PolyglotException.html), other error types will yield different exception object. See example 4 for more information.

$.doInNewTransaction(workerFunction [, errorHandlerFunction] )

(1) Regular working example
${{
    /* Iterate over all users in packets of 10 and do stuff */
    let pageSize = 10;
    let pageNo    = 1;

    $.doInNewTransaction(function() {
        let nodes = $.find('User', $.predicate.page(pageNo, pageSize));      // in structr versions lower than 4.0 replace "$.predicate.page" with "$.page"
		
        // compute-heavy stuff
		
        pageNo++;
	
        return (nodes.length > 0);
    }, function() {
        $.log('Error occurred in batch function. Stopping.');
        return false;
    });
}}

(2) Example where the inner transaction tries to create a relationship to a node which has not yet been committed and thus the whole code fails
${{
    /* create a new group */
    let group = $.getOrCreate('Group', 'name', 'ExampleGroup');

    $.doInNewTransaction(() => {
        let page = $.create('Page', 'name', 'ExamplePage');

        /* this is where the error occurs - the Group node is not yet committed to the graph and when this context is closed a relationship between the group and the page is created - which can not work because only the page is committed to the graph */
        $.grant(group, page, 'read');
    });
}}

(3) Example to fix the problems of example (2)
${{
    /* create a new group */
    let groupId;

    $.doInNewTransaction(() => {
        let group = $.getOrCreate('Group', 'name', 'ExampleGroup');

        /* save the group id to be able to fetch it later */
        groupId = group.id;

        /* after this context, the group is committed to the graph and relationships to it can later be created */
    });

    $.doInNewTransaction(() => {
        let page = $.create('Page', 'name', 'ExamplePage' });

        /* fetch previously created group */
        let group = $.find('Group', groupId);

        /* this works now */
        $.grant(group, page, 'read');
    });
}}

(4) Example where an error occurs and is handled (v4.0+)
${{
    $.doInNewTransaction(() => {
        let myString = 'the following variable is undefined ' + M;
    }, (ex) => {
        // depending on the exception type different methods will be available
        $.log(ex.getClass().getSimpleName());
        $.log(ex.getMessage());
    });
}

Decrypts a base 64 encoded AES ciphertext and returns the decrypted result. This method either uses the internal global encryption key that is stored in structr.conf, or the optional second parameter.

decrypt(text [, secret ] )

${print(decrypt(get(this, 'encryptedString'))}
${print(decrypt(get(this, 'encryptedString'), 'secret key')}

Removes the cached value for the given key (if present).

delete_cache_value(key)

${delete_cache_value('externalResult')}

Temporarily disables the Websocket Broadcast notifications for the Structr Backend UI. This method can be used to prevent the broadcasting of large modification operations which greatly reduces the processing time for such large operations. If you experience very slow (i.e. more than 10 seconds) object creation, modification or deletion, try to disable notifications before executing the operation. See also enable_notifications().

disable_notifications()

This method is the inverse of disable_notifications(). It re-enabled the Websocket broadcast of creation, modification and deletion operations. See disable_notifications() for more information on that topic.

enable_notifications()

Encrypts the given string using AES and returns the ciphertext encoded in base 64. This method either uses the internal global encryption key that is stored in structr.conf, or the optional second parameter.

encrypt(text [, secret ] )

${set(this, 'encryptedString', encrypt('example string'))}
${set(this, 'encryptedString', encrypt('example string', 'secret key'))}

This method can be used to signal an error condition while scripting execution. It is mainly used in entity callback functions like onCreate() or onSave() to allow the user to implement custom validation logic.

If an error is raised the current transaction will be rolled back and no changes will be written to the database.

error(propertyKey, token, detail)
error(propertyKey, token)

${error('name', 'name_not_allowed')}
${error('name', 'name_not_allowed', 'The given name is not allowed.')}
results in an HTTP 422 Unprocessable Entity error.

Evaluates the given script in the context of given entity.

evaluate_script(entity, script)

${evaluate_script(me, "print(this.name)")}
results in the name of the current user being printed.

Retrieves the cached value for the given key.

Returns null if there is no stored value for the given key or if the stored value is expired.

get_cache_value(key)

${get_cache_value('externalResult')}

Gets all environment variables or the value of the specified environment variable. An environment variable is a system-dependent external named value.

If no variable is given, a map of all environment variables is returned.

getenv()
getenv(variable)

${getenv('JAVA_HOME')}
${{ return $.getenv().PATH; }}

Retrieves a value stored under the given key from the user session.

get_session_attribute(key)

${get_session_attribute('do_not_track')}

Checks if a cached value exists for the given key. Returns false if there is no stored value for the given key or if the stored value is expired.

This function is especially useful if the result of a JavaScript function should be cached (see Example 2).

has_cache_value(key)

(1) ${has_cache_value('externalResult')}

(2)
${{    
    let myComplexFunction = function() {
        // computation... for brevity just return a date string
        return new Date().toString();
    };

    let cacheKey = 'myKey';

    if (Structr.hasCacheValue(cacheKey)) {

        // retrieve cached value
        let cacheValue = Structr.getCacheValue(cacheKey);
        // ...
        // ...

    } else {

        // cache the result of a complex function
        let cacheResult = Structr.cache(cacheKey, 30, myComplexFunction());
        // ...
        // ...
    }    
}}

Allows checking if an error has been raised in the scripting context

has_error()

Returns a boolean value that indicates whether the locale of the current context is one of the given locale values.

is_locale(locales, ...)

${is_locale('de_DE', 'de_AT')}

true

Fetches data from a JDBC source. Since version 3.3.1, you can define the driver class by setting the full qualified class path in the driver parameter.
The default for the driver parameter is com.mysql.jdbc.Driver.

jdbc(url, query)
New with 3.3.1:
jdbc(url, query[, driver])

${jdbc("jdbc:mysql://localhost:3306",  "SELECT * from Test")}

New with 3.3.1:
You can now define the exact driver class:
${jdbc("jdbc:oracle:thin:user/password@myhost:1521:orcl", "SELECT * from Test", "oracle.jdbc.driver.OracleDriver")}

The following example shows how to use the `jdbc()` function to import data from an Oracle database:

{ // JavaScript Context
   
    let rows = $.jdbc('jdbc:oracle:thin:test/test@localhost:1521:orcl', 'SELECT * FROM test.emails');
   
    rows.forEach(function(row) {
       
        $.log('Fetched row from Oracle database: ', row);
       
        let fromPerson = $.getOrCreate('Person', 'name', row.from_address);
        let toPerson   = $.getOrCreate('Person', 'name', row.to_address);
       
        let message = $.getOrCreate('EMailMessage',
            'content',   row.email_body,
            'sender',    fromPerson,
            'recipient', toPerson,
            'sentDate',  $.parseDate(row.email_date, 'yyyy-MM-dd')
        );
       
        $.log('Found existing or created new EMailMessage node: ', message);
    });
}

Returns information about the job with the given job Id. If the job does not exist (anymore) the function returns false.

For script jobs the returned information is:

For file import the returned information is:

job_info(jobId)

${job_info(1)}

Creates an entity of type LogEvent with the current timestamp and the given values.
All four parameters (action, message, subject and object) can be arbitrary strings.

In JavaScript, the function can be called with a single map as parameter. The event paramters are taken from that map.

log_event(action, message [, subject [, object ]])
$.logEvent(map)

${log_event('VIEW', me.id)}

${{
    $.logEvent({
        action: "VIEW",
        message: Structr.me.id
    });
}}

Allows an admin user to execute a maintenance command from within a scripting context.

maintenance(commandName [, key1, value1 [, ... ]])
$.maintenance(commandName [, map ])

${maintenance('rebuildIndex')}

${{
    $.maintenance('rebuildIndex', { type: 'Article' });
}}

Opens a connection to a MongoDB source and returns a MongoCollection which can be used to further query the Mongo database. Available since version 4.0

mongodb(connectionString, database, collection)

NOTE: All examples assume a mongo instance has been locally started via docker with the following command: docker run -ti -p 27017:27017 mongo

(1) Open connection, insert object and retrieve objects with identical name
{
  // Open the connection to mongo and return the testCollection
  let collection = $.mongodb('mongodb://localhost', 'testDatabase', 'testCollection');

  // Insert a record
  collection.insertOne($.bson({
    name: 'Test4'
  }));

  // Query all records with a give property set
  return collection.find($.bson({ name: 'Test4' }));
}

(2) Open connection and find objects with regex name
{
  // Open the connection to mongo and return the testCollection
  let collection = $.mongodb('mongodb://localhost', 'testDatabase', 'testCollection');

  // Query all records with a give property set
  return collection.find($.bson({ name: { $regex: 'Test[0-9]' } }));
}

(3) Open connection, insert object with date and query all objects with dates greater than equal (gte) that date
{
  // Open the connection to mongo and return the testCollection
  let collection = $.mongodb('mongodb://localhost', 'testDatabase', 'testCollection');

   // Insert a record
  collection.insertOne($.bson({
    name: 'Test9',
    date: new Date(2018, 1, 1)
  }));
	
  return collection.find($.bson({ date: { $gte: new Date(2018, 1, 1) } }));
}

(1) objects with name 'Test4'
(2) objects with name 'Test' + a single digit
(3) objects with dates greater than equal (gte) that date

Interpretes R code. (See the Scripting Guide for more info on supported languages)

r(<R code>)

New in v3.6: Returns a new random UUID, a string with 32 characters [0-9a-f].

random_uuid()

${{
    var newId = $.randomUuid();
    return newId;
}}

dda27cc07ac34c75a121d6e1821c1851

Removes a value stored under the given key from the user session.

remove_session_attribute(key)

${remove_session_attribute('do_not_track')}

Retrieves the value previously stored under the given key in the current request context. This method can be used to obtain the results of a previous computation step etc. and is often used to provide some sort of “variables” in the scripting context. See store() for the inverse operation.
Additionally, the retrieve() function is used to retrieve the parameters supplied to the execution of a custom method.

retrieve(key)

${retrieve('users')}

[admin, user1, user2, user3]

Allows the user to insert a script snippet into the import queue for later execution. Useful in situations where a script should run after a long-running import job, or if the script should run in a separate transaction that is independent of the calling transaction.
The title parameter is optional and is displayed in the structr admin UI in the Importer section and in the notification messages when a script is started or finished.
The onFinish parameter is a script snippet which will be called when the process finishes (successfully or with an exception).
A parameter jobInfo is injected in the context of the onFinish function (see job_info() for more information on this object).
The schedule function returns the job id under which it is registered.

schedule(expression [, title [, onFinish ]])

${schedule('call("myCleanupScript")', 'Cleans unconnected nodes from the graph')}

**JavaScript Example**
${{
    $.schedule(function() {
        // execute global method
        Structr.call('myCleanupScript');
    }, 'Cleans unconnected nodes from the graph');
}}

${{
    $.schedule(function() {
        // execute global method
        Structr.call('myCleanupScript');
    }, 'Cleans unconnected nodes from the graph', function() {
        Structr.log('scheduled function finished!');
        Structr.log('Job Info: ', Structr.get('jobInfo'));
    });
}}

Triggers the sending of a sever-sent event to a given list of recipients. The message will only be sent if they have an open connection.

send_event(eventType, message, recipient(s))

send_event("myTopic", "Welcome Bob!", find('User', 'name', 'Bob'))

Returns the last n lines from the server log file

serverlog([lines = 50])

${serverlog(200)}

Sets the internal global encryption key that is used by the encrypt() and decrypt() functions. Please note that this method overwrites the encryption key that is stored in structr.conf. The overwritten key can be restored by using null as a parameter to this method, as shown in the example below

set_encryption_key(secret)

${set_encryption_key('secret key')}
${set_encryption_key(null)}

Sets the locale for the current scripting context. This setting directly influences the result of date parsing and formatting functions.

set_locale(locale)

${set_locale('de')}

This method can be used to store a value under the given key in the user session.

set_session_attribute(key, value)

${set_session_attribute('do_not_track', true)}

Causes the execution flow to wait / sleep for the given number of milliseconds.

sleep(milliseconds)

${sleep(1000)}

Stores the given value in the current request context under the given key. This method can be used to temporarily save the results of a computation step etc. and is often used to provide some sort of “variables” in the scripting context. See retrieve() for the inverse operation.

store(key, value)

${store('users', find('User'))}

New in v3.6: Returns a number of system parameters.

system_info()

system_info()

{now=1592312051572, uptime=877700, runtime=11.0.7+8-LTS, counts={nodes=9334, relationships=13878}, caches={node={size=9334, max=100000}, relationship={size=3806, max=500000}, localizations={size=0, max=10000}}, memory={runtime_info={free=361822224, max=8589934592, total=1289748480}, mgmt_bean_info={G1 Eden Space={i
nit=56623104, used=0, committed=740294656, max=-1}, G1 Old Gen={init=1017118720, used=0, committed=0, max=8589934592}, G1 Survivor Space={init=0, used=73400320, committed=73400320, max=-1}}}}

This method can be used to measure the performance of sections of code. The action parameter can be start to create a new timer or get to retrieve the elapsed time (in milliseconds) since the start of the timer.

timer(name, action)

${timer('benchmark', 'start')}
[...]
${log(timer('benchmark', 'get'), 'ms since timer started')}

Translates the given text via the a translation API.
Supported translation providers:

• google (Google Cloud Translation API, default)
• deepl (DeepL REST API)

translate(text, sourceLanguage, targetLanguage [, translationProvider] )

${translate("Structr is awesome", "en", "de")}

Structr ist großartig

Returns the sum of all the values.

add(values...)

${add(1, 2, 3, 4)}

10

Returns the given value, rounded up to the nearest integer. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments.

ceil(val)

${ceil(5.8)}

6.0

Returns the division result of parameter1 divided by parameter2.

div(parameter1, parameter2)

${div(5, 2)}

2.5

Returns the given value, rounded down to the nearest integer. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments.

floor(val)

${floor(5.8)}

5.0

Tries to convert the given object into an integer value.

int(object)

${int('23')}
${int(23.456)}

23

Tries to convert the given object into a long value.

long(object)

${long(now)}

1589407200000

Returns the greater of the given values. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments. See also min().

max(val1, val2)

${max(5, 8)}

8.0

Returns the smaller of the given values. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments. See also max().

min(val1, val2)

${min(5, 8)}

5.0

Returns the remainder of the quotient of val1 and val2. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments.

mod(val1, val2)

${mod(5, 2)}

1.0

Returns the product of all given parameters.

mult(val1, val2...)

${mult(5, 2, 3, "10")}

300.0

Returns the given numerical string as an actual number with double precision.

num(numericalString)

${num('23')}

23.0

Returns the quotient of val1 and val2. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments.

quot(val1, val2)

${quot(10, 2)}

5.0

Returns a random integer value between 0 (inclusive) and the bound parameter (exclusive).

rint(bound)

${rint(100)}

42

Returns the given value, rounded to the nearest integer. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments. If the optional parameter decimalPlaces is given, this method rounds to the given number of decimal places.

round(val [, decimalPlaces ])

(1) ${round(5.876543, 2)}
(2) ${round(5.49)}
(3) ${round(5.5)}

(1) 5.88
(2) 5
(3) 6

Returns the subtraction result of val1 minus val2. This method tries to convert its parameter objects into numerical values, i.e. you can use strings as arguments.

subt(val1, val2)

${subt(5, 2)}

3.0

Unarchives given file to an optional parent folder.

${unarchive(archiveFile [, parentFolder])}
${{$.unarchive(archiveFile [, parentFolder])}}

${unarchive(first(find('File', 'name', 'archive.zip')), first(find('Folder', 'name', 'parent')) )}
${{ $.unarchive($.first($.find('File', 'name', 'archive.zip')), $.first($.find('Folder', 'name', 'parent')) )}}

This method is one of the most important and frequently used built-in functions. It returns a collection of entities, which can be empty if none of the existing nodes or relationships matches the given search parameters.
find() accepts several different predicates (key, value pairs) and other query options like sort order or pagination controls. See the examples below for an overview of the possible parameter combinations for an advanced find() query. The simpler usage of the find() function is documented below in the article for find()

Predicates

The following predicates can be specified. Predicates can be combined and mixed to build complex queries. Some predicates and property keys need to be combined in a different way than others, please refer to the examples below for an overview.

Options
The following options can be specified:

find(type, predicates..., options...)

StructrScript
-------------

(1) ${find('User', sort('name'))}
returns all User entities in the database, sorted by name


(2) ${find('User', sort('name'), page(1, 10))}
returns the first 10 User entities in the database, sorted by name


(3) ${find('User', contains('name', 'e'))}
returns all user entities whose name property contains the letter 'e' (showcases the different ways to use the contains predicate)


(4) ${find('User', 'age', gte(18))}
returns all user entities whose age property is greater than or equal to 18

(5a) ${find('User', 'age', range(0, 18))}
returns all user entities whose age property is between 0 and 18 (inclusive!)

(5b) ${find('User', 'age', range(0, 18, false, false))}
returns all user entities whose age property is between 0 and 18 (exclusive!)


(6a) ${find('User', equals('name', 'Tester'), equals('age', range(0, 18)))}
(6b) ${find('User', and(equals('name', 'Tester'), equals('age', range(0, 18))))}
returns all user entities whose name is 'Tester' and whose age is between 0 and 18 (inclusive). Showcases the implicit (6a) and explicit (6b) logical AND conjunction of root clauses


(7) ${find('BakeryLocation', and(within_distance(48.858211, 2.294507, 1000)))}
Returns all bakeries (type BakeryLocation extends Location) within 1000 meters around the Eiffel Tower



JavaScript (Structr 4.0 and up)
-------------------------------

(8)
${{
    $.find('User', $.predicate.sort('name'), $.predicate.page(1, 10))
}}
returns the first 10 User entities in the database, sorted by name


(9a)
${{
    $.find('User', 'age', $.predicate.gte(21))
}}
returns all user entities whose age property is greater than or equal to 21.
This is the identical syntax to structrscipt, only in JavaScript. In JavaScript, there are more readable ways to express the identical query (see 9b, 9c)

(9b)
${{
    $.find('User', {
    	'age': $.predicate.gte(21)
    })
}}
returns all user entities whose age property is greater than or equal to 21.
In JavaScript, we can use a map as second parameter to have a more concise and programming-friendly way of query building


(9c)
${{
    $.find('User', $.predicate.equals('age', $.predicate.gte(21))
}}
returns all user entities whose age property is greater than or equal to 21.
Instead of a map, we can use a predicate-only approach. See the following


(10)
${{
    let projects = $.find(
    	'Project',
        {
            $and: {
                'name': 'structr',
                'age': $.predicate.range(30, 50)
            }
        },
        $.predicate.sort('name', true),
        $.predicate.page(1, 10)
    );

    return users;
}}
returns the first 10 projects (sorted descending by name) where 'name' equals 'structr' and the 'age' is between 30 and 50 (inclusive)


(11a)
${{
    // Showcasing the *limitation* of the MAP SYNTAX: OR on the same property is not possible. See 11b for a solution
    let users = $.find(
    	'User',
        {
            $or: {
                'name': 'jeff',
                'name': 'joe'
            }
        }
    );

    return users;
}}
Only the user "joe" will be returned because the map key "name" is used twice (which is impossible)

(11b)
${{
    // Showcasing the *advantage* of the PREDICATE SYNTAX: OR on the same property is possible. See (11c) for a more elegant version
    let users = $.find(
        'User',
        $.predicate.or(
             $.predicate.equals('name', 'jeff'),
             $.predicate.equals('name', 'joe')
        )
    );

    return users;
}}
All users named "joe" or "jeff" will be returned

(11c)
${{
    // More elegant example where predicates are created before of the query
    let nameConditions = [
        $.predicate.equals('name', 'jeff'),
        $.predicate.equals('name', 'joe')
    ];
    
    let users = $.find('User', $.predicate.or(nameConditions));

    return users;
}}
All users named "joe" or "jeff" will be returned. This showcases how to create condition predicates before adding them to the query

(11d)
${{
    // More advanced example where predicates are created before of the query
    let nameConditions = [
        $.predicate.equals('name', 'jeff'),
        $.predicate.equals('name', 'joe')
    ];

    let rootPredicate = $.predicate.and(
        $.predicate.equal('isAdmin', true),
        $.predicate.or(nameConditions)
    );

    let users = $.find('User', rootPredicate);

    return users;
}}
All users with the "isAdmin" flag set to true and named "joe" or "jeff" will be returned. This showcases how to create the complete predicate before the query





Deprecated: JavaScript (up until Structr 3.6.x)
-----------------------------------------------

The old syntax did not have the "predicate" object.

(12)
${{
    $.find('User', $.sort('name'), $.page(1, 10))
}}
returns the first 10 User entities in the database, sorted by name

(13)
${{
    let users = $.find('Project',
        {
            $and: {
                'name': 'structr',
                'age': $.range(30, 50)
            }
        },
        $.sort('name', true),
        $.page(1, 10)
    );

    return users;
}}
returns the first 10 projects (sorted descending by name) where 'name' equals 'structr' and the 'age' is between 30 and 50 (inclusive)

(14)
${{
    // Showcasing the *limitation* of the MAP SYNTAX: OR on the same property is not possible. See 13b for a solution
    let users = $.find('User',
        {
            $or: {
                'name': 'jeff',
                'name': 'joe'
            }
        }
    );

    return users;
}}
Only the user "joe" will be returned because the map key "name" is used twice (which is impossible)

Executes the given Cypher query and returns the results. Structr will automatically convert all query results into the corresponding Structr objects, i.e. Neo4j nodes will be instantiated to Structr node entities, Neo4j relationships will be instantiated to Structr relationship entities, and maps will converted into Structr maps that can be accessed using the dot notation (map.entry.subentry).

cypher(query [, key1, value1 [, ... ]] )
cypher(query [, map] )

${cypher('MATCH (n:User) RETURN n')}

[7379af469cd645aebe1a3f8d52b105bd, a05c044697d648aefe3ae4589af305bd, 505d0d469cd645aebe1a3f8d52b105bd]
**Example using Parameters**
${{
let query = "MATCH (user:User) WHERE user.name = $userName RETURN user";
let users = $.cypher(query, {userName: 'admin'});
}}

This method is one of the most important and frequently used built-in functions. It returns a collection of entities, which can be empty if none of the existing nodes or relationships matches the given search parameters.
find() accepts several different parameter combinations, whereas the first parameter is always the name of the type to retrieve from the database. The second parameter can either be a UUID (string), a map (e.g. a result from nested function calls) or a list of (key, value) pairs.

The given query parameters are combined with an AND predicate. For node attributes an exact match is searched for the given value. For remote attribute collections the given search values are combined with an OR predicate (see examples).

find(type [, key1, value1 [, ... ]] )
find(type [, map ])
find(type [, uuid ])

(1) ${find('User')}
(2) ${find('User', 'name', 'admin')}
(3) ${find('User', '7379af469cd645aebe1a3f8d52b105bd')}

(4) ${{
    let alice = $.find('User', 'name', 'alice')[0];
    let bob   = $.find('User', 'name', 'bob')[0];

    let userWithFriendAliceOrBob = $.find('User', {
        hasFriends: [ alice, bob ]
    });
}}

(1) [7379af469cd645aebe1a3f8d52b105bd, a05c044697d648aefe3ae4589af305bd, 505d0d469cd645aebe1a3f8d52b105bd]
(2) [7379af469cd645aebe1a3f8d52b105bd]

(3) This is a special case - a UUID was supplied, therefore only a single object is returned instead of a collection
(3) 7379af469cd645aebe1a3f8d52b105bd

(4) // returns every user who is friends with either alice or bob

Executes a find() operation with elevated privileges.
Usecases
find_privileged() can be used to query data from an anonymous context or when a users privileges need to be escalated.

find_privileged(type [, key1, value1 [, ... ]] )
find_privileged(type [, map ])
find_privileged(type [, uuid ])
find_privileged(type)

Returns a collection of entities of the given type from the database, takes optional key/value pairs

find_relationship(type [, key1, value1, [, ...] ])
find_relationship(type [, map ])

${find_relationship("PersonRELATED_TOPerson")}
${find_relationship("ProjectCONTAINSTask")}

get_or_create() finds and returns a single object with the given properties (key/value pairs or a map of properties) and creates that object if it does not exist yet.
The function accepts three different parameter combinations, where the first parameter is always the name of the type to retrieve from the database. The second parameter can either be a map (e.g. a result from nested function calls) or a list of (key, value) pairs.

get_or_create(type [, key1, value1, [, ...] ])
get_or_create(type [, map ])

${get_or_create('User', 'name', 'admin')}
${get_or_create('User', 'name', 'admin')}
${get_or_create('User', 'name', 'admin')}

7379af469cd645aebe1a3f8d52b105bd
7379af469cd645aebe1a3f8d52b105bd
7379af469cd645aebe1a3f8d52b105bd
The example shows that repeated calls to `get_or_create()` with the same parameters will always return the same object.

Returns a search predicate to specify value ranges, greater and less-than searches in find() and search() functions. The first two parameters represent the first and the last element of the desired query range. Both start and end of the range can be set to null to allow the use of range() for <, <=. > and >= queries.
There are two optional boolean parameters, includeStart and includeEnd that control whether the search range should include or exclude the endpoints of the interval.

range(start, end)
range(start, end, includeStart, includeEnd)

${find('Project', 'taskCount', range(0, 10))}
${find('Project', 'taskCount', range(0, 10, true, false))}
${find('Project', 'taskCount', range(0, 10, false, false))}
**Server-side JavaScript Examples**
Structr.find('Project').forEach(p => Structr.print(p.index + ", "));
=> 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
Structr.find('Project', { index: Structr.range(2, 5) }).forEach(p => Structr.print(p.index + ", "));
=> 2, 3, 4, 5,
Structr.find('Project', { index: Structr.range(2, 5, false) }).forEach(p => Structr.print(p.index + ", "));
=> 3, 4, 5,
Structr.find('Project', { index: Structr.range(2, 5, false, false) }).forEach(p => Structr.print(p.index + ", "));
=> 3, 4,

The search() method is very similar to find(), except that it is case-insensitive / inexact. It returns a collection of entities, which can be empty if none of the existing nodes or relationships matches the given search parameters.
search() accepts several different parameter combinations, whereas the first parameter is always the name of the type to retrieve from the database. The second parameter can either be a map (e.g. a result from nested function calls) or a list of (key, value) pairs. Calling search() with only a single parameter will return all the nodes of the given type (which might be dangerous if there are many of them in the database).

search(type [, key1, value1 [, ... ]] )
search(type [, map ])
search(type [, uuid ])
search(type)

For this example, we assume that there are three users in the database: [admin, tester1, tester2].
${search('User')}
${search('User', 'name', 'test')}

[7379af469cd645aebe1a3f8d52b105bd, a05c044697d648aefe3ae4589af305bd, 505d0d469cd645aebe1a3f8d52b105bd]
[a05c044697d648aefe3ae4589af305bd, 505d0d469cd645aebe1a3f8d52b105bd]

Returns the value of the given XPath expression from the given XML DOM. The optional third parameter defines the return type, possible values are: NUMBER, STRING, BOOLEAN, NODESET, NODE, default is STRING. This method can be used in conjunction with xml() and read() to read an XML file from the Structr exchange/ directory. Alternatively a file from the virtual filesystem can be read using the get_content() function. See Anatomy of a Structr application for more information.

xpath(xmlDocument, xpathExpression[, returnType])

xmlString is assumed to be
<xml>
    <projects>
        <project name='p1'>
            <budget>100</budget>
        </project>
        <project name='p2'>
            <budget>500</budget>
        </project>
    </projects>
</xml>

(1) ${xpath(xml(xmlString), "/xml/projects/project[1]/budget", "STRING")
(2) ${xpath(xml(xmlString), "/xml/projects/project[2]/budget", "STRING")
(3) ${xpath(xml(xmlString), "/xml/projects/project[2]/@name", "STRING")

(1) 100
(2) 500
(3) p2

Returns the counter value for the given level.

get_counter(level)

${get_counter(1)}

0

Increases the counter value for the given level, optionally resetting the value of all counters below the given level with the second parameters, which accepts a boolean value.

inc_counter(level, resetLowerLevels)
inc_counter(level)

${inc_counter(1, true)}

<no output>

Loads the element with the given name and renders its HTML representation into the output buffer. Nodes can be included via their name property. When used with an optional collection and data key argument, the included HTML element will be renderd as a Repeater Element.

Possible nodes MUST:
1. have a unique name
2. NOT be in the trash

Possible nodes CAN:
1. be somewhere in the pages tree
2. be in the Shared Components

Together with render(), include() is one of the most important methods when dealing with HTML web templates since it allows the user to populate static HTML pages with dynamic content from the underlying node structure.

include(name)
include(name, collection, dataKey)

${include('Main Menu')}
will render the contents of the [Shared Component](/article/Shared%20Components) with the name "Main Menu" into the output buffer.
${include('Item Template', find('Item'), 'item')}
will render the contents of the [Shared Component](/article/Shared%20Components) with the name "Item Template" repeatedly for every Item node in the database.

Loads a template’s child element with the given name and renders its HTML representation into the output buffer. Nodes can be included via their name property. When used with an optional collection and data key argument, the included HTML element will be renderd as a Repeater Element.

Together with render()and include(), include_child() is one of the most important methods when dealing with HTML web templates since it allows the user to populate static HTML pages with dynamic content from the underlying node structure. See Page Rendering for more information on this topic.

include_child(name)
include_child(name, collection, dataKey)

(1) ${include_child('Child Node')}
(2) ${include_child('Item Template', find('Item'), 'item')}

(1) will render the contents of the child node with the name "Child Node" into the output buffer.
(2) will render the contents of the child node with the name "Item Template" repeatedly for every Item node in the database.

Prints the string representation of all of the given objects into the page rendering buffer. This method is often used in conjunction with each() to create rendering output for a collection of entities etc. in scripting context.

print(objects...)

${print('Hello, world!')}

Hello, world!

Renders the HTML representation of the given node(s) into the output buffer. This method is exactly equivalent to the rendering process that Structr uses internally to create the HTML output of pages etc. It can be used to render dynamic content in pages with placeholders etc.
Together with include(), render() is one of the the most important method when dealing with HTML web templates, since it allows the user to fill static HTML pages with dynamic content from the underlying node structure. See Page Rendering for more information on this topic.

render(nodes)
render(node)

${render(children)}

Resets the counter for the given level.

reset_counter(level)

${reset_counter(1)}

<no output>

Allows overriding the current keyword with a given entity.

set_details_object(entity)

${set_details_object(first(find('User')))}

Returns the list of parent types of the given type including the type itself. Additionally a blacklist of type names can be provided as a list. If omitted, the list contains only “AbstractNode” by default.

ancestor_types(type[, blacklist])

${ancestor_types("MyType")}
${ancestor_types("MyType", merge())}  (merge() is used to create an empty list so the blacklist is reset)

[MyType]
[MyType, AbstractNode]

Returns a list of the possible values of an enum property.
If the rawList flag is set to “true”, a simple list will be returned. If it is omitted or set to false, a list of objects will be returned (so it can be used in a repeater element)

enum_info(typeName, enumName [, rawList = false])

An enum property `words` is defined on the type `Doge` with format = "such, choices, much, awesome"
(1) ${enum_info("Doge", "words")}
(2) ${enum_info("Doge", "words", true)}

(1) [{value: "such"}, {value: "choices"}, {value: "much"}, {value: "awesome"}]
(2) ["such", "choices", "much", "awesome"]

Returns the list of inheriting types of the given type including the type itself. Additionally a blacklist of type names can be provided as a list. If omitted, the blacklist is empty.

inheriting_types(type[, blacklist])

${inheriting_types("MyType")}
${inheriting_types("MyType", merge("UndesiredSubtype"))}

[MyType, Subtype1, Subtype2, UndesiredSubtype]
[MyType, Subtype1, Subtype2]

Returns a property info object for the property of the given type with the given name. A property info object has the following structure:

property_info(type, name)

${property_info('User', 'name').uiType}

String

If called with a view, all properties of that view are returned as a list. The items of the list are in the same format as property_info() returns. This is identical to the result one would get from /structr/rest/_schema/<type>/<view>.
If called without a view, the complete type information is returned as an object. This is identical to the result one would get from /structr/rest/_schema/<type>.

type_info(type[, view])

Abbreviates the given string at the last space character before the maximum length is reached.
The remaining characters are replaced with the ellipsis character (…) or the given abbr parameter.

abbr(string, maxLength [, abbr = '…' ] )

${abbr('A long string that is too long to be displayed entirely.', 20)}

A long string that…

Decodes the given base64 text using the supplied scheme. Valid values for scheme are basic (default), url and mime.
The following explanation of the encoding schemes is taken directly from https://docs.oracle.com/javase/8/docs/api/java/util/Base64.html

Basic
Uses “The Base64 Alphabet” as specified in Table 1 of RFC 4648 and RFC 2045 for encoding and decoding operation. The encoder does not add any line feed (line separator) character. The decoder rejects data that contains characters outside the base64 alphabet.

URL and Filename safe
Uses the “URL and Filename safe Base64 Alphabet” as specified in Table 2 of RFC 4648 for encoding and decoding. The encoder does not add any line feed (line separator) character. The decoder rejects data that contains characters outside the base64 alphabet.

MIME
Uses the “The Base64 Alphabet” as specified in Table 1 of RFC 2045 for encoding and decoding operation. The encoded output must be represented in lines of no more than 76 characters each and uses a carriage return ‘\r’ followed immediately by a linefeed ‘\n’ as the line separator. No line separator is added to the end of the encoded output. All line separators or other characters not found in the base64 alphabet table are ignored in decoding operation.

base64decode(text,[ scheme = basic [, charset]])

${base64decode("Q2hlY2sgb3V0IGh0dHA6Ly9zdHJ1Y3RyLmNvbQ==")}

Check out http://structr.com

Encodes the given string in base64 using the supplied scheme. Valid values for scheme are basic (default), url and mime.
The following explanation of the encoding schemes is taken directly from https://docs.oracle.com/javase/8/docs/api/java/util/Base64.html

Basic
Uses “The Base64 Alphabet” as specified in Table 1 of RFC 4648 and RFC 2045 for encoding and decoding operation. The encoder does not add any line feed (line separator) character. The decoder rejects data that contains characters outside the base64 alphabet.

URL and Filename safe
Uses the “URL and Filename safe Base64 Alphabet” as specified in Table 2 of RFC 4648 for encoding and decoding. The encoder does not add any line feed (line separator) character. The decoder rejects data that contains characters outside the base64 alphabet.

MIME
Uses the “The Base64 Alphabet” as specified in Table 1 of RFC 2045 for encoding and decoding operation. The encoded output must be represented in lines of no more than 76 characters each and uses a carriage return ‘\r’ followed immediately by a linefeed ‘\n’ as the line separator. No line separator is added to the end of the encoded output. All line separators or other characters not found in the base64 alphabet table are ignored in decoding operation.

base64encode(text,[ scheme = basic [, charset]])

${base64encode("Check out http://structr.com")}

Q2hlY2sgb3V0IGh0dHA6Ly9zdHJ1Y3RyLmNvbQ==

Capitalizes a String changing the first character to title case. No other characters are changed. If the first character has no explicit titlecase mapping and is not itself a titlecase char according to UnicodeData, then the uppercase mapping is returned as an equivalent titlecase mapping.

capitalize(string)

(1) ${capitalize("cat dog bird")}
(2) ${capitalize("cAT DOG BIRD")}
(3) ${capitalize("'cat dog bird'")}

(1) "Cat dog bird"
(2) "CAT DOG BIRD"
(3) "'cat dog bird'"

This method can be used to convert complex strings or collections of strings (e.g. user names, article titles, etc.) into simple strings that can be used in URLs etc.

clean(string)
clean(collection)

(1) ${clean('This   is Än   example')}
(2) ${clean(merge('This   is Än   example', 'This   is   Änother   example'))}

(1) this-is-an-example
(2) ['this-is-an-example', 'this-is-another-example']

Returns the first non-null value in the list of expressions passed to it. In case all arguments are null, null will be returned.

coalesce(node.name, node.title, node.id, ...)

(1) ${coalesce(null, null, 'cat', 'dog', 'bird')}
(2) ${coalesce(null, '', 'cat', 'dog', 'bird')}

(1) 'cat'
(2) ''

Concatenates the given list of objects into a single string without a separator between them.
The objects can be of any type: string, number, entity, collection. If a collection is encountered, all elements of that collection are concatenated.

concat(object...)

(1) ${concat('test', 1, me, ' a string')}
(2) ${concat('test ', merge('con', 'cat', 'enate'), ' ', me.name)}

(1) test1.0d8915af2c66942aeb46b960349fcadbc a string
(2) test concatenate admin

Returns a boolean value that indicates whether the given string contains the given word or the given collection contains the given element.

contains(string, word)
contains(collection, element)

${contains('This is a test string', 'test')}
${contains(find('Page'), page)}

true

Predicate function - returns true if the given string ends with the given suffix.

ends_with(string, suffix)

(1) ${ends_with('Hello World!', 'World!')}
(2) ${ends_with('Hello World!', 'Mundo!')}

(1) true
(2) false

Replaces special characters in text with their HTML entities, e.g. & with &.
Supports all known HTML 4.0 entities, including funky accents.

escape_html(string)

${escape_html('Test & Test"')}

Test & Test"

Escapes the given string for use in Javascript.

escape_javascript(string)

${escape_javascript('This is a "test"')}

This is a \"test\"

Escapes the given string for use in JSON.

escape_json(string)

${escape_json('This is a "test"')}

This is a \"test\"

Escapes the characters in a String using XML entities.

escape_xml(string)

${escape_xml('This is a "test" & another "test"')}

This is a "test" & another "test"

Encodes the given object for use in an URL, replacing invalid characters with their valid URL equivalent and joining the key/value pairs with an ampersand.

formurlencode(object)

(1) $.formurlencode({name:"admin", p1: 12, apiKey: "abc123", text:"Text with umläut"})
(2) $.formurlencode({name:"admin", p1: 12, apiKey: "abc123", text:"Text with umläut", sub: { subKey1: "subValue1", subKey2: 42 }})

(1) name=admin&p1=12&apiKey=abc123&text=Text+with+uml%C3%A4ut
(2) name=admin&p1=12&apiKey=abc123&text=Text+with+uml%C3%A4ut&sub[subKey1]=subValue1&sub[subKey2]=42

Parses the given source string and returns an object representation of the string.
If the parameter headerList is not supplied, it is assumed that the first line of the CSV is a header and those header values are used as property names.
If the parameter is supplied, the given values are used as property names and the first line is read as data.

from_csv(source[, delimiter = ';' [, quoteChar = '"' [, recordSeparator = '\n' [, headerList ] ]]])

(1) ${from_csv('COL1;COL2;COL3\nline1:one;line1:two;line1:three\nline2:one;line2:two;line2:three')}
(2) ${first(from_csv('COL1;COL2;COL3\nline1:one;line1:two;line1:three\nline2:one;line2:two;line2:three')).COL2}
(3) ${from_csv('COL1;COL2;COL3\nline1:one;line1:two;line1:three\nline2:one;line2:two;line2:three', ';', '"', '\n', merge('a', 'b', 'c') )}

(1) [{COL1=line1:one, COL2=line1:two, COL3=line1:three}, {COL1=line2:one, COL2=line2:two, COL3=line2:three}]
(2) line1:two
(3) [{a=COL1, b=COL2, c=COL3}, {a=line1:one, b=line1:two, c=line1:three}, {a=line2:one, b=line2:two, c=line2:three}]

Parses the given source string and returns a Structr object representation of the string. This method is the inverse of to_json().

from_json(source)

(1) ${from_json('{name: Test, value: 123}')}
(2) ${from_json('{name: Test, value: 123}').name}

(1) {name=Test, value=123.0}
(2) Test

Parses the given XML and returns a JSON representation of the XML which can be further processed using from_json() or JSON.parse().

from_xml(source)

${from_xml('<entry>0</entry>')}

{"entry": 0}

Parses the given CSV string and returns a list of column headers

get_csv_headers(source[, delimiter = ';' [, quoteChar = '"' [, recordSeparator = '\n' ]]])

${get_csv_headers('COL1;COL2;COL3\none;two;three')}

["COL1", "COL2", "COL3"]

Returns the hash (as a hexadecimal string) of a given string, using the given algorithm (if available via the underlying JVM).

Currently, the SUN provider makes the following hashes/digests available: MD2, MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256, SHA3-224, SHA3-256, SHA3-384, SHA3-512

If an algorithm does not exist, an error message with all available algorithms will be logged and a null value will be returned.

hash(algorithm, value)

hash('SHA-512', 'Hello World!')

861844d6704e8573fec34d967e20bcfef3d424cf48be04e6dc08f2bd58c729743371015ead891cc3cf1c9d34b49264b510751b1ff9e537937bc46b5d6ff4ecc8

Returns the position of the first occurrence of the given word in the given string, or -1 if the string doesn’t contain the word.

index_of(string, word)

${index_of('This is a test', 'test')}

10

Joins the given collection of strings into a single string, separated by the given separator. This method is often used in conjunction with find() and extract() to create comma-separated lists of entity names etc. The merge() function can be used to create a list of strings like in the following example.

join(collection, separator)

(1) ${join(merge('one', 'two', 'three'), ', ')}
(2) ${join(extract(find('User'), 'name'), ', ')}

(1) one, two, three
(2) admin, tester1, tester2, tester3

Returns the length of the given string.

length(string)

${length('This is a test')}

14

The localize() function can be used to localize strings and therefor create localized user interfaces. It uses the current locale (see keyword locale) to search for nodes of type Localization in the database. This lookup works in 4 stages. If a Localization object is found (in the order of evaluation), the process is stopped. If no localization is found, the key itself is returned.

1. find localization with exact match on key, domain and full locale
2. find localization with exact match on key, NO domain and full locale
3. find localization with exact match on key, domain and language only
4. find localization with exact match on key, domain and language only
5. Restart steps 1-4 with the fallback locale - if defined and active via structr.conf:
   • application.localization.usefallbacklocale = enable/disable use of the fallback locale
   • application.localization.fallbacklocale = the fallback locale

If after step 4 no localization is found, the input parameters are logged if the configuration entry application.localization.logmissing in structr.conf is enabled.

localize(key [, domain])
localize(keys [, domain])

<input type="text" placeholder="${localize('username')}...">

// if the current locale is en_US
<input type="text" placeholder="Username...">

// if the current locale is de_DE
<input type="text" placeholder="Benutzername...">

Returns the lowercase value of the given string.

lower(string)

${lower('STRUCTR')}

structr

Returns the MD5 hash value (32 characters alphanumeric (hex)) of the given string. The method takes exactly one argument.

md5(string)

<div id="user-${md5(me.name)}"></div>

<div id="user-c3bfefa0c01486e95cc345472626e9cb)}"></div>

Formats the given number in the given language according to the given pattern. This method uses the Java NumberFormat class which supports the ISO two-letter language codes, e.g. “en”, “de” etc. The following four pattern chars are supported:

number_format(number, languageCode, pattern)

${number_format(1.234, 'en', '###0.0000')}
${number_format(1234567, 'de', '0,000,000.0000')}

1.2340
1.234.567,0000

Parses the given string into a numerical value. With the second (optional) parameter you can pass a locale string to take a country-/language specific number formatting into account.

parse_number(string[, locale])

(1) ${parse_number('123,456,789.123', 'en')}
(2) ${parse_number('123.456.789,123', 'de')}

(1) 123456789.123
(2) 123456789.123

Returns a random alphanumerical string of the given length. This method can for example be used to create default passwords etc.

random(length)

${random(8)}

gz5sl4z

Replaces all template expressions in the given template string with values from the given entity. This method can be used to evaluate template expressions in database objects, for example to create customized e-mails etc.

replace(template, entity)

${replace('Welcome, ${this.name}!', me)}

Welcome, admin!

Uses the given separator to split the given string into a collection of strings. This is the opposite of join().

The default separator is a regular expression which splits the string at ANY of the following characters: ,;(whitespace)
The optional second parameter is used as literal separator, it is NOT used as a regex. To use a regular expression to split a string, see split_regex().

split(string [, separator])

${split('one,two,three,four')}
${split('one;two;three;four')}
${split('one two three four')}
${split('one::two::three::four', ':')}
${split('one.two.three.four', '.')}
${split('one,two;three four')}

[one, two, three, four]

Uses the given separator to split the given string into a collection of strings. This is the opposite of join().
The default separator is a regular expression which splits the string at any of the following characters: ,;(whitespace)
The optional second parameter is used as regex. To use a literal string as separator, see split().

split_regex(string, separator)

${split_regex('one,two,three,four')}
${split_regex('one;two;three;four')}
${split_regex('one two three four')}
${split_regex('one::two::three::four', ':+')}
${split_regex('one.two.three.four', '\\.')}
${split_regex('one:two&three%four', ':|&|%')}

[one, two, three, four]

Predicate function - returns true if the given string starts with the given prefix.

starts_with(string, prefix)

(1) ${starts_with('Hello World!', 'Hello')}
(2) ${starts_with('Hello World!', 'Hola')}

(1) true
(2) false

Replaces each substring of the subject that matches the given regular expression with the given replacement.

str_replace(subject, search, replacement)

${str_replace("Hello Wrlod!", "Wrlod", "World")}

Hello World!

Removes all HTML tags from the given source string and returns only the content.

strip_html(source)

${strip_html('<h3><p>Clean me!</p></h3>')}

Clean me!

Returns a portion with the given length of the given string, starting from the given start index. If no length parameter is given or the length would exceed the string length (calculated from the start index), the rest of the string is returned.

substring(string, start [, length ])

(1) ${substring('This is my test', 2)}
(2) ${substring('This is my test', 8, 2)}
(3) ${substring('This is my test', 8, 100)}

(1) is is my test
(2) my
(3) my test

Loads a node of type MailTemplate with the given name and locale values and uses the given source entity to resolve template expressions in the content field of the loaded node, returning the resulting text.

template(name, locale, source)

// passing the Structr me object, representing the current user
${template('MAIL_SUBJECT', 'de', me)}

// passing an arbitrary JavaScript object
${{
    return $.template('MAIL_SUBJECT', 'de', $.toGraphObject({name: "Mr. Foo"}))
}}

Assuming the MailTemplate is configured as:
Welcome, ${this.name}!

Welcome, admin!

Titleizes the given string. The given string is split at the separatorChars and each ‘word’ is titleized.

titleize(string[, separatorChars = " "])

(1) ${titleize('structr has a lot of built-in functions')}
(2) ${titleize('structr has a lot of built-in functions', '- ')}

(1) Structr Has A Lot Of Built-in Functions
(2) Structr Has A Lot Of Built In Functions

Removes any leading or trailing whitespace from the given object. If the object is a string, a trimmed version will be returned. If it is a collection, a collection of trimmed strings will be returned.

trim(object)

${trim('         A text with lots of whitespace                                                   ')}
${trim(merge('     A text with lots of whitespace                  ', '     Another text with lots of whitespace               '))}

A text with lots of whitespace
[A text with lots of whitespace, Another text with lots of whitespace]

Reverses the effect of escape_html().

unescape_html(string)

${unescape_html('Test & Test"')}

Test & Test"

Returns the uppercase value of the given string.

upper(string)

${upper('structr')}

STRUCTR

Encodes the given string for use in an URL, replacing invalid characters with their valid URL equivalent.

urlencode(string)

${urlencode('This is a test')}

This+is+a+test

Adds the given parameters to the given date and returns the resulting date.

date_add(date, year[, month[, day[, hour[, minute[, second]]]]])

(1) ${date_add(to_date(1585504800000), 1)}
(2) ${date_add(to_date(1585504800000), 0, -1)}

(1) Mon Mar 29 20:00:00 CEST 2021
(2) Sat Feb 29 20:00:00 CET 2020

Formats the given date object according to the given pattern, using the current locale (language/country settings). This method uses the Java SimpleDateFormat class which provides the following pattern chars:

Each character can be repeated multiple times to control the output format.

date_format(date, pattern)

(1) ${date_format(to_date(1585504800000), 'yyyy-MM-dd')}
(2) ${date_format(to_date(1585504800000), 'EEEE')}
(3) ${(set_locale('de'), date_format(to_date(1585504800000), 'EEEE'))}

(1) 2020-03-29
(2) Sunday
(3) Sonntag

Parses the given string according to the given pattern and returns a date object. This method is the inverse of date_format().

parse_date(string, pattern)

${parse_date('2015-12-12', 'yyyy-MM-dd')}

Sat Dec 12 00:00:00 CET 2015

Converts the given number into a date object.
The number is interpreted as UNIX timestamp (milliseconds from Jan. 1, 1970).

to_date(number)

${to_date(1585504800000)}

Sun Mar 29 20:00:00 CEST 2020

Removes a stored value from the application level store.

application_store_delete(key)

application_store_delete("do_no_track")

Retrieves a stored value from the application level store.

application_store_get(key)

application_store_get("do_no_track")

true

Lists all keys stored in the application level store.

application_store_get_keys()

application_store_get_keys()

['do_not_track', 'key1', 'key2', 'key3']

Checks if a key is present in the application level store.

application_store_has(key)

application_store_has('do_not_track')

true

Stores a value in the application level store.

application_store_put(key, value)

application_store_put("do_no_track", true)

Removes a stored value from the request level store.

request_store_delete(key)

request_store_delete('do_not_track')

Retrieves a stored value from the request level store.

request_store_get(key)

request_store_get('do_not_track')

true

Lists all keys stored in the request level store.

request_store_get_keys()

request_store_get_keys()

['do_not_track', 'key1', 'key2', 'key3']

Checks if a key is present in the request level store.

request_store_has(key)

request_store_has('do_not_track')

true

Stores a value in the request level store.

request_store_put(key, value)

request_store_put("do_no_track", true)