API Reference

Lifecycle Methods

afterCreate

Called after a new object of this type is created.

The afterCreate() lifecycle method is called after a new object of this type is created. This method runs after the creating transaction is committed, so you can be sure that the validation was successful and the object is stored in the database.

This method would be the right place to send a welcome email, for example, as you can be sure that the user exists.

Notes

This lifecycle method can be defined on any node type.
See also: onCreate().

afterDelete

Called after an object of this type was deleted.

The afterDelete() lifecycle method is called after an object of this type is deleted. This method runs after the deleting transaction is committed, so you can be sure that the object was deleted from the database.

Notes

This lifecycle method can be defined on any node type.
See also: onDelete().

afterSave

Called after an existing object of this type is modified.

The afterSave() lifecycle method is called after an existing object of this type is modified. This method runs after the modifying transaction is committed, so you can be sure that the validation was successful and the object is stored in the database.

Notes

This lifecycle method can be defined on any node type.
See also: onSave().

onAcmeChallenge

Called when… ??

onCreate

Called when a new object of this type is created.

The onCreate() lifecycle method is called when a new object of this type is created. This method runs at the end of a transaction, but before property constraints etc. are evaluated.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

If you want to execute code after successful validation, implement the afterCreate() callback method.

Notes

This lifecycle method can be defined on any node type.
See also: onNodeCreation(), afterCreate(), error() and assert().

Examples

Example 1 (JavaScript)

{
	if ($.this.name === 'foo') {

		// don't allow creation of nodes named "foo"
		$.error('name', 'create_not_allowed', 'Can\'t be created because name is "foo"');

	} else {

		$.log('Node with name ' + $.this.name + ' has just been created.');
	}
}

onDelete

Called when an object of this type is deleted.

The onDelete() lifecycle method is called when an existing object of this type is deleted. This method runs at the end of a transaction, but before property constraints etc. are evaluated.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

If you want to execute code after successful validation, implement the afterDelete() callback method.

You can access the local properties of the deleted entity through the this keyword.

Notes

This lifecycle method can be defined on any node type.
See also: afterDelete(), error() and assert().

Examples

Example 1 (JavaScript)

{
	if ($.this.name === 'foo') {

		// don't allow deletion of nodes named "foo"
		$.error('name', 'delete_not_allowed', 'Can\'t be deleted because name is "foo"');

	} else {

		$.log('Node with name ' + $.this.name + ' has been deleted.');
	}
}

onDownload

Called after the download of a File is complete.

The onDownload() lifecycle method is called after a File is downloaded.

Notes

This method must be defined on the type File or its descendants.
See also: onDelete().

onNodeCreation

Called at the moment when a new object of this type is created.

The onNodeCreation() lifecycle method is called at the moment when a new object of this type is created. In contrast to onCreate(), this method runs at the same time that the object is created.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

If you want to execute code at the end of the transaction, implement the onCreate() callback method.
If you want to execute code after successful validation, implement the afterCreate() callback method.

Notes

This lifecycle method can be defined on any node type.
See also: onCreate(), afterCreate(), error() and assert().

onOAuthLogin

Called when a user authenticates with oAuth.

The onOAuthLogin() lifecycle method is called when users create login via oAuth.

To receive this callback, you must create a user-defined function called onStructrLogin, instance methods or static methods will not be called.

This method will be called with the following arguments:

Name	Description
provider	The name of the oAuth provider that handled the login
userinfo	The map of user information sent by the oAuth server

Note: You cannot prevent a user from logging in with this method. If you throw an error in this method, or the method contains a syntax error, the error will be logged but the login will not fail.

Notes

This lifecycle method must be defined on the type User or its descendants.
See also: onStructrLogin(), onStructrLogout().

onSave

Called when an existing object of this type is modified.

The onSave() lifecycle method is called when an existing object of this type is modified. This method runs at the end of a transaction, but before property constraints etc. are evaluated.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

This lifecycle method will be called with the following arguments:

Name	Description
modifications	A map of modifications that reflect the changes made to this object

The modifications map contains the following entries:

Name	Description
before	key-value mappings that were removed
after	key-value mappings that were added or changed
added	key-value mappings that were added
removed	key-value mappings that were removed

Notes

This lifecycle method can be defined on any node type.
If you want to execute code after successful validation, implement the afterSave() callback method.
See also: afterSave(), error() and assert().

Examples

Example 1 (JavaScript)

{
	if ($.this.name === 'foo') {

		// don't allow deletion of nodes named "foo"
		$.error('name', 'save_not_allowed', 'Name can\'t be changed to "foo"');

	} else {

		$.log('Node with name ' + $.this.name + ' has been modified.');
	}
 }

onStructrLogin

Called when a user starts a new session.

The onStructrLogin() lifecycle method is called when users create new sessions by authenticating themselves with any of the login mechanisms.

To receive this callback, you must create a user-defined function called onStructrLogin, instance methods or static methods will not be called.

Note: You cannot prevent a user from logging in with this method. If you throw an error in this method, or the method contains a syntax error, the error will be logged but the login will not fail.

Notes

See also: onStructrLogout().

onStructrLogout

Called when a user finishes a new session by logging out.

The onStructrLogout() lifecycle method is called when users finish a session by logging themselves out, OR when the session times out.

To receive this callback, you must create a user-defined function called onStructrLogout, instance methods or static methods will not be called.

Note: You cannot prevent a user from logging out with this method. If you throw an error in this method, or the method contains a syntax error, the error will be logged but the logout will not fail.

Notes

See also: onStructrLogin().

Previous: Functions
Next: System Types

Lifecycle Methods

afterCreate

Called after a new object of this type is created.

This method would be the right place to send a welcome email, for example, as you can be sure that the user exists.

Notes

This lifecycle method can be defined on any node type.
See also: onCreate().

afterDelete

Called after an object of this type was deleted.

Notes

This lifecycle method can be defined on any node type.
See also: onDelete().

afterSave

Called after an existing object of this type is modified.

Notes

This lifecycle method can be defined on any node type.
See also: onSave().

onAcmeChallenge

Called when… ??

onCreate

Called when a new object of this type is created.

The onCreate() lifecycle method is called when a new object of this type is created. This method runs at the end of a transaction, but before property constraints etc. are evaluated.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

If you want to execute code after successful validation, implement the afterCreate() callback method.

Notes

This lifecycle method can be defined on any node type.
See also: onNodeCreation(), afterCreate(), error() and assert().

Examples

Example 1 (JavaScript)

{
	if ($.this.name === 'foo') {

		// don't allow creation of nodes named "foo"
		$.error('name', 'create_not_allowed', 'Can\'t be created because name is "foo"');

	} else {

		$.log('Node with name ' + $.this.name + ' has just been created.');
	}
}

onDelete

Called when an object of this type is deleted.

The onDelete() lifecycle method is called when an existing object of this type is deleted. This method runs at the end of a transaction, but before property constraints etc. are evaluated.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

If you want to execute code after successful validation, implement the afterDelete() callback method.

You can access the local properties of the deleted entity through the this keyword.

Notes

This lifecycle method can be defined on any node type.
See also: afterDelete(), error() and assert().

Examples

Example 1 (JavaScript)

{
	if ($.this.name === 'foo') {

		// don't allow deletion of nodes named "foo"
		$.error('name', 'delete_not_allowed', 'Can\'t be deleted because name is "foo"');

	} else {

		$.log('Node with name ' + $.this.name + ' has been deleted.');
	}
}

onDownload

Called after the download of a File is complete.

The onDownload() lifecycle method is called after a File is downloaded.

Notes

This method must be defined on the type File or its descendants.
See also: onDelete().

onNodeCreation

Called at the moment when a new object of this type is created.

The onNodeCreation() lifecycle method is called at the moment when a new object of this type is created. In contrast to onCreate(), this method runs at the same time that the object is created.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

If you want to execute code at the end of the transaction, implement the onCreate() callback method.
If you want to execute code after successful validation, implement the afterCreate() callback method.

Notes

This lifecycle method can be defined on any node type.
See also: onCreate(), afterCreate(), error() and assert().

onOAuthLogin

Called when a user authenticates with oAuth.

The onOAuthLogin() lifecycle method is called when users create login via oAuth.

To receive this callback, you must create a user-defined function called onStructrLogin, instance methods or static methods will not be called.

This method will be called with the following arguments:

Name	Description
provider	The name of the oAuth provider that handled the login
userinfo	The map of user information sent by the oAuth server

Note: You cannot prevent a user from logging in with this method. If you throw an error in this method, or the method contains a syntax error, the error will be logged but the login will not fail.

Notes

This lifecycle method must be defined on the type User or its descendants.
See also: onStructrLogin(), onStructrLogout().

onSave

Called when an existing object of this type is modified.

The onSave() lifecycle method is called when an existing object of this type is modified. This method runs at the end of a transaction, but before property constraints etc. are evaluated.

If you throw an error in this method, the enclosing transaction will be rolled back and nothing will be written to the database.

This lifecycle method will be called with the following arguments:

Name	Description
modifications	A map of modifications that reflect the changes made to this object

The modifications map contains the following entries:

Name	Description
before	key-value mappings that were removed
after	key-value mappings that were added or changed
added	key-value mappings that were added
removed	key-value mappings that were removed

Notes

This lifecycle method can be defined on any node type.
If you want to execute code after successful validation, implement the afterSave() callback method.
See also: afterSave(), error() and assert().

Examples

Example 1 (JavaScript)

{
	if ($.this.name === 'foo') {

		// don't allow deletion of nodes named "foo"
		$.error('name', 'save_not_allowed', 'Name can\'t be changed to "foo"');

	} else {

		$.log('Node with name ' + $.this.name + ' has been modified.');
	}
 }

onStructrLogin

Called when a user starts a new session.

The onStructrLogin() lifecycle method is called when users create new sessions by authenticating themselves with any of the login mechanisms.

To receive this callback, you must create a user-defined function called onStructrLogin, instance methods or static methods will not be called.

Note: You cannot prevent a user from logging in with this method. If you throw an error in this method, or the method contains a syntax error, the error will be logged but the login will not fail.

Notes

See also: onStructrLogout().

onStructrLogout

Called when a user finishes a new session by logging out.

The onStructrLogout() lifecycle method is called when users finish a session by logging themselves out, OR when the session times out.

To receive this callback, you must create a user-defined function called onStructrLogout, instance methods or static methods will not be called.

Notes

See also: onStructrLogin().