Events

Action is a procedure written in CJ Blocks that invokes whenever a trigger event occurs.

Trigger events can be predefined or custom. Predefined events happen whenever a particular moment in the page life cycle is reached (for example, Load action ) or when a particular field changes its state. Custom trigger events happen when users presses on the button.

Actions can be executed in the user’s browser (“client-side” actions) or on a web server (“server-side” actions). When building, client-side actions are translated to JavaScript code and server-side actions to Java code. Therefore developers can mix CJ Blocks code with code written in JavaScript or Java depending on whether the action is run on the client or server.

Within the App Builder, there are different actions that can be performed, and they are shared into two categories - Type and Fields action

Types action

All of these actions can be found on the Data types details page. To view the actions, navigate to the Code Blocks section and click Actions. If you want to add actions, hover your mouse pointer over Actions, then click the plus sign beside it.

Load: The load action is triggered when the web page is loading. It also a server-side action. It is used to calculate additional data on the server. This data is not stored in the database and is only generated for a specific session. Transient field values are not stored in the database and can be filled on the load action. For example, creating a transient Fullname field to be filled with values that are calculated from the Surname and name. Without this the transient Fullname field, additional and unnecessary data will be stored in the database.



Loaded: The loaded action is a Client-side action that is triggered when the web page is already loaded. So, it works just like the Load action and calculates some additional data on the client-side. With the use of native code, it is possible to modify the web page. For example, you want to create a webpage view with three tabs and you want the second tab and its contents to be displayed when the page is loaded. For this, you need to add an identifier to the webpage view element (i.e. the specified tab). Then on the loaded action, you should add a native code block with the specified code element to display the specified tab.


Validate: The validate action accesses the validity of your data. It is triggered after the user clicks the save button and before the save action. It is a server-side action. For example, you are building an app to store medical lab results. Knowing that some of the lab values cannot be negative, you need to make sure that all the values are validated before they can be stored in the database. If there is a negative value where it is not supposed to be, then it will display an error. For example, red blood cells (RBCs) cannot have a negative value.


Save: This is a server-side action. It is triggered after the save button is clicked and validation has been passed. This gives the users the opportunity to process the information on the server after the save button is clicked. For example, we want to know when the last modification of an instance occurred. For this, we need to write a code to get the timestamp every time the user saves an instance.


Delete: This is a server-side action that is triggered just before an Item is deleted. It could be used to remove some references, recalculate some statistics, etc. For example, you have created an invoice containing individual orders and their prices and the total amount. If one of the orders is paid, then it should be removed or deleted from the invoice. Once it is deleted, the total amount to be paid is recalculated.


Tree change: The tree change action is triggered when the tree-like structure is changed by
the user. In the example below, we have restricted the logs folder only to items with the name “Log”. So, if the name of the item is not “Log” it can’t be added to the Logs folder.


After import: This action is triggered when the user imports data instances from an external
source. It enables the user to add info or make changes to the data before saving in the database. For example, the After import action can be used when you need to register the exact time a data instance was imported.

Build: This is an action that is unique only for the Report data type. It is triggered when report data is converted into readable and understandable data.

Get data leaves: This action is also specific for the Report data type. It is triggered before the report is generated. Here, it is possible to specify the data that will be used to build the report.

Fill functions: This is a server-side action that is triggered when an instance is created based on another type. For example, from an instance of data type car, we can create an instance of data type product that has information such as name, version, price, etc.

Post: This action can be found only when working with the Document data type. It is triggered when a document is posted and used to work with journals. Journals is a type kind for storing accounting records created for posted Documents.

Custom: It enables the user to assign actions to buttons that have been manually added to the app. Custom actions are triggered when the user clicks the button. When creating a custom action, you will need to choose if it is client-side or server-side.
Here, there are three types of actions that can be set:

  • Before server action - This is the first client-side action to be executed when the user clicks the button. For example, you may need to create a button that will open the specified tab.

  • Server action - This is the server-side action to be executed. It is executed after 'before server action'. For example, creating a button to check for the temperature. It calculates information about the temperature on the server and returns the results. 

  • After server action -The client-side action to be executed after server-side action. For example, you need to create a button to save and go to your homepage.

Note that if one action fails, the subsequent actions will not be performed.

Field actions
 
Basic field actions


These actions can be accessed by clicking the three vertical dots on the left side of the field created found in the Fields section.

  • On validate field event: The validate action can be used to check your data for errors in a specific field. It is triggered before the save action. It is the same as the Validate action explained above with the difference being that it checks only for a specified field.

  • On field change event on server: This action is triggered on the server-side when the user changes data in the field and loses focus. For example, in a currency converter app, inputting the value of a currency will automatically calculate its value in another currency.

  • On field changed event on client: This action is triggered on the client-side when the user changes data in the field and occurs after the On field change event. This event is the same as the latter only that it occurs on the client-side. 

  • On field filtered event: This action is triggered when a list of instances is displayed. For example, you have built a web app for buying cars. It is possible to add a filter to the car field which helps the users to see only the cars within the price range they have set.


Collection field actions

These are actions that can be carried out on collection fields. There are two actions that are specific to these fields:

  • On collection inserted event: It is triggered when an item(s) is added to the collection. For example, adding an invoice to a collection of invoices. Once the invoice is added to the collection, the total value of all the invoices is recalculated.

  • On collection deleted event: This action is triggered when an item(s) is removed from the collection. For example, deleting an invoice from a collection of invoices. Same as with the above example, the total value of all the invoices are calculated once the invoice is deleted.

  • OnRow Click: This is a server-side action and it is triggered when the user clicks on a table row.
    For example, this action can be used when the user is working with several invoices on a form. The developer can set the OnRow Click action on a row so that when it is clicked, the name of the active invoice is displayed.

  • OnRow Clicked: This is a client-side action that is triggered when the user clicks on a table row. For example, clicking on a row redirects the user to the homepage.

Note: The actions in the subfield of the embedded data type are the same as those in the basic fields.  Also, actions can be added to items in the Shared fields section. These actions are the same as those in the basic fields.



Table actions
This action can be accessed under the Views section in the data types details page. Click on Table to expand it, then click on the three vertical dots on the left side of the table item. These actions work on virtual and index tables.

  • On rowLoad event: This is a server-side event that is triggered only for a virtual and index tables when it loads data. For example, you have created a cryptocurrency trading app. A user has Bitcoins and Eutherum and displays their values in USD. Every time the data is displayed, the exact values for the cryptocurrencies are calculated on the server.

  • On rowLoaded event: It is a client-side action that is triggered only for a virtual and index table when it loads data. The same example above can be applied here. The only difference is that the action takes place on the client-side.

Custom permission action
This action is found on the Permissions page where the permissions of the app can be edited. The custom permission action allows users to set functions that will grant permission to perform some actions. This action is triggered before a specified action is performed. For example, we created a custom permission action to check if the user has permission to view transaction history. In this case, we granted only users with an account balance more than zero permission to view the history.

API function
In the app builder, it is possible to create custom API functions that will be triggered when another app makes a request to your created URL. Sometimes, your app may have a feature that is needed by a third-party app. For the third-party app to be able to access this feature, it needs to send a request through an API. For example, your app has the ability to convert Epoch to human-readable data. If a third-party app wants access to this information, it will have to send a request through an API.

Add to scheduler
This action can be found in the Code Blocks section. To use it, expand Custom actions, click on the three vertical dots next to any server-side action, then select Add to scheduler. It is used when the user wants to repeat an action multiple times.