Scripting
Learn How to Use Scripting to Implement More Validation and Security Solutions
Introduction
This documentation is based on the FoodCrunch use case. Please open the link below alongside this page to understand the examples.
Why Scripting?
Some business rules around security and validation are hard to solve with a generic feature that works for everybody and is easy to use. The workflow system has limitations as well and you cannot write permissions that depend on the data of the content.
In general, scripting can be used to handle gaps in the Squidex feature set.
Scripting for Content
You can create scripts that run whenever a content item is created, updated, deleted, queried or when the status changes (e.g. from Draft to Published).
Scripts can be defined in the schema editor:
Go to your App (1).
Go to the Schema (2) settings.
Select the schema (3) you want to write a script for, i.e
startups
in this example.Select the Scripts (4) tab
Select the tab (5), depending on when you want the script to run, to work with the editor.
In the editor, you can define scripts for the following actions:
Query script is executed whenever a content item is queried with the API, but not when queried by the Management UI.
Prepare Query is called once for all content items of the current query. It can be used to precompute or prefetch data.
Create script is executed before a content item is created.
Change script is executed before the status of a content item is changed. When you use scheduling to change the status of a content item in the future, the script is called just before the status is changed and not when you schedule it. This can also stop your scheduling, when the script fails or it rejects the change.
Delete script is executed before a content item is deleted.
Update script is executed before a content item is updated.
Content creation and updates happen in the following order:
The content item is loaded. If it does not exist, the API responds with 404 (NotFound).
The data from the request is validated. The API responds with 400 (BadRequest) for invalid data.
The script is executed.
The data from the request is enriched with configured default values.
The constraints, such as unique fields are checked.
This means that you have the guarantee in your scripts, that the data is always valid and that you cannot violate constraints such as unique fields when you auto-generate or change content data.
Scripts are executed for the REST endpoint as well as for the GraphQL endpoint.
Scripting for Assets
Asset scripts can be defined in the settings:
Go to your App (1).
Go to the Settings (2).
Select the Asset Scripts (3) menu item.
Select the script type (4) you want to edit.
In the editor you can define scripts for the following actions:
Annotate script is executed before the metadata of an asset is changed.
Create script is executed before an asset is created.
Moved script is executed before an asset is moved to another folder.
Delete script is executed before an asset is deleted.
Update script is executed before an asset is replaced with a new file.
Execution and Variables
The scripts are executed in a Sandbox. You do not have access to the file system and only to allowed functions. Only the ES5 JavaScript syntax is implemented so far, which means you cannot use Lambda expressions, Promises or classes.
Variables
All variables are accessible over the ctx
(Context) variable. The following fields can be used for all scripts:
The user object has the following structure:
Content Script Variables
The following fields can be used for content scripts:
Asset Script Variables
The following fields can be used for Asset scripts:
Methods
Control Methods
These methods are used to make changes to the content item or to reject changes.
Helper Methods
Squidex provides a set of general helper functions for scripting and rule formatting.
In addition to that, there are also methods that are only available for scripting.
Use Cases
Debugging: Write the Context to a Field
If you want to understand your data structure and the context object, you can just write it to a string field.
Do Not Return Sensitive Information When Queried by a Client
Do Not Allow the Client to Set Fields
Ensure that Two Fields Have the Same Value
Ensure that Only a Specific User can Publish Content
Compute Field From Other Values
Store in a separate field if another field has a valid value:
Calculate the slug for a content title automatically:
Calculate the number of words in a Markdown field:
Calculate the number of characters in a HTML field:
Enrich Your Content with Data from External Services
You can use the getJSON
function to enrich the content with data from external services. This example is a little bit more complicated that the other examples above, but let's jump into the code first:
When you make an asynchronous call to another service or content, the script engine cannot stop the script automatically. Therefore, it is very important to finish the script with a call to replace()
, even if you do not make a change to the content data.
Restrictions
There are some existing restrictions:
You cannot include external libraries.
You cannot make calls to external services, except
getJSON
.Scripts will timeout after 200ms of CPU execution.
Scripts will timeout after 5 seconds of total execution, e.g. waiting for external services with
getJSON
.
Last updated