You have been redirected from an outdated version of the article. Below is the content available on this topic. To view the old article click here.

Callback Methods

Callback methods on Custom Types

Custom Types can implement four pre-defined Callback Methods that are executed when an object of that type is subject to external changes.

A callback method can be implemented in StructrScript or, for more complex implementations, in ServerSide JavaScript. To implement a pre-defined callback method, the name of the method must match the name of the event below. Callback methods can prevent the modification of an object by calling the error() method, which will fail the transaction and cause a 422 Unprocessable Entity error to be sent to the user.

In the callback methods on custom types, the current object can be accessed via the this keyword. (see onDelete for an exception to this rule)

onCreate

Called when a new instance of this Custom Type is created in the database.

Example

The following onCreate script sets the timestamp property of a newly created entity to the current time and date and triggers Geocoding. This example illustrates the syntax of the template expression used in callbacks.

(
    set(this, 'timestamp', now),
    set(this, geocode(this.street, this.city, this.country))
)

The next example illustrates the use of the error() method to prevent the creation of invalid entities in the database.

(
    if(empty(this.name),
        error('User', 'name', 'must_not_be_empty'),
        null
    )
)

JavaScript equivalent:

{
    var self = Structr.get('this');
    
    if (Structr.empty(self.name)) {
        Structr.error('User', 'name', 'must_not_be_empty');
    }
}
onSave

Called when an instance of this Custom Type is modified (this does not include creation). Just like onCreate above, onSave can prevent the modification of an object with the error() method. The actual changes made to a node can be accessed via the modifications collection in an onSave method.

onDelete

Called when an instance of this Custom Type is deleted. The error() function can be used on onDelete as well.

Note: In the onDelete callback, using the this keyword will produce an error as the object has already been deleted.
Note: Raising an error() will trigger a rollback of the transaction.

onDownload

Called when a File is downloaded.

Note

You can of course declare more than one method of each type, suffixing the individual methods with a number (e.g. onCreate01, onCreate02, …). This allows you to specify a series of functions that will be executed when a new entity is created.

Global callback methods

Currently there are two predefined global callback methods onStructrLogin and onStructrLogout. They are called when a user logs in and out respectively and are executed in a superuser context.
For these two methods Structr will provide the current user in a variable called user.
Any global schema method called via call() will stay in the user context of the current user. Methods called via call_privileged() will run in a superuser context.

Search results for "Callback Methods"

Relationship Details Dialog

The Cascading Delete settings allow configuration of what happens when either end of the relationship is deleted. The possible values are explained in-depth in the help popup in the dialog.
Automatic Creation of Related Nodes configures if it is allowed to include nested nodes in a REST POST request for this relationship. A node with the given property set is automatically created and linked to the node. If the nested node contains an id attribute (or another property marked as unique) a node is searched for that property and linked if found.

Permission Resolution allows configuration of rights propagation in the graph. If NONE is selected, no rights propagation is applied for this relationship. If SOURCE_TO_TARGET is selected the rights are propagated along the relationship direction to the next node. For TARGET_TO_SOURCE the rights propagation is works against the relationship direction. For ALWAYS the direction of the relationship does not matter and rights propagation is always applied.
Specific rights (Read, Write, Delete, AccessControl) can be added, kept or removed according to the propagation configuration. If a user has read rights to the previous node and Read is configured to Keep, the user also has read rights for the next node. (Specific User/Group rights are applied before using permission propagation - i.e. if a user has specific rights configured for a node, permission resolution is not evaluated as user rights are more specific).
Along the way of permission propagation, properties can be hidden in order to hide sensitive information from users who get rights from permission propagation. The property names can be separated by comma , or space character.

There are 3 tabs where the functionality of the type can be configured:

  • Local Attributes
    A Custom Type can be extended with dynamic properties to provide the data model for the intended use-case. This list contains all local properties (meaning they are defined on this type directly).
  • Views
    The properties of a type can be combined into named Views, which are accessible under an individual REST URL. Access to these URLs can be configured independently for each HTTP method using Resource Access Grants, which makes them an ideal tool to create specialised endpoints for different client applications (e.g. mobile clients etc.).
  • Methods
    There are different kinds of methods - callback methods and entity methods. Callback methods are automatically executed by the framework upon certain lifecycle events and have a strict naming convention. Entity methods are called by the user/programmer.
    Entity methods are not automatically run by the framework and must be called manually. This either means making a POST request to /structr/rest/(Type)/(<a data-id="7c9c8218bced42bab66868373e64d885" class="mention">UUID</a>)/(methodName) or in serverside JavaScript as node.methodName();

Type Details Dialog

There are 5 tabs where the functionality of the type can be configured:

  • Local Attributes
    A Custom Type can be extended with dynamic properties to provide the data model for the intended use-case. This list contains all local properties (meaning they are defined on this type directly).

  • Views
    The properties of a type can be combined into named Views, which are accessible under an individual REST URL. Access to these URLs can be configured independently for each HTTP method using Resource Access Grants, which makes them an ideal tool to create specialised endpoints for different client applications (e.g. mobile clients etc.).

  • Methods
    There are different kinds of methods - callback methods and entity methods. Callback methods are automatically executed by the framework upon certain lifecycle events and have a strict naming convention. Entity methods are called by the user/programmer.
    Entity methods are not automatically run by the framework and must be called manually. This either means making a POST request to /structr/rest/<Type>/<UUID>/<methodName> or in serverside JavaScript as <node>.<methodName>();

  • Remote Attributes
    Custom types can be linked to other types, including base types. Structr will automatically create Remote Attributes on either side of the link, which can then be used to create, update or remove the relationships between instances of the two types. In this tab the configuration of the remote attributes can be viewed and edited. The names configured here are used throughout the application to refer to the other side of the relationship(s).

  • Inherited Attributes
    The content of this tab is of informative character. All inherited attributes are shown with an information from where it was inherited.