Events

Events serve as a mechanism for initiating specific actions, often employed to trigger particular behaviors. They collaborate with various actions to establish dynamic interactions within an application.

For instance, when a user interacts with a webpage by clicking a button, you have the flexibility to determine the response, whether it involves invoking a function or opening another webpage. Furthermore, events can be activated in response to updates in a datasource.

Within Qodly Studio, events play a pivotal role in executing code on the Qodly web server, without requiring any supplementary JavaScript.

Types of Events

Events can be set to trigger either when end-users perform specific actions or when datasources are updated.

User events

You can configure events to activate in response to specific actions performed by end-users, such as clicking buttons, moving the mouse cursor, and more.

Typical user events include On Click, On DblClick, On MouseEnter, On Keyup, and others. The available events may vary depending on the selected component, and detailed documentation can be found in the Triggers and Events section on each component's page.

Datasource events

Besides events triggered by end-user actions, events can also be automated to respond when datasources undergo changes. The primary event for datasources is the On Change event.

When the On Change event is linked to a datasource, it will trigger in the following scenarios:

Trigger	Description
Datasource	The reference pointed to by the datasource changes in the web browser (not on the server) The entity is touched
Entity datasource	The contents of the entity attribute change
Entity selection datasource	The reference pointed by the datasource changes in the web browser (not on the server) An entity is added to the entity selection
Scalar datasource	The contents of the scalar datasource change

Managing events

The Contextual panel facilitates the association of class functions, navigation actions, and standard actions with distinct events within your application.

Adding an Event

To bind class functions, navigation actions or standard actions with events, follow these steps:

1. Select a Component or Datasource: Begin by choosing the component or datasource to which you want to attach an event. This selection can be made using the canvas, the outline, or, in the case of datasources, either the shared datasources area or the local datasources area.

2. Expand the Contextual Panel: Once your selection is made, expand the Contextual panel . It will provide you with a list of compatible events specifically tailored to your chosen component or datasource.

3. Bind the Desired Action to the Event: Next, select the type of action you wish to bind to the event. You have three options:

   • Standard Action: Configure automatic actions on datasources, such as create, save, drop, or order by, without the need for coding.
   • Navigation Action: Set up actions related to navigation within the application, such as opening another page or redirecting to an external URL.
   • Class Function: Use a custom function to handle the event.

4. Action Bound to Event: In the list of available events, you will notice a purple bullet displayed on the left side of events that have already been configured (if any).

5. Configure Event Properties: Complete the remaining steps specific to each action type, as detailed in the respective sections within the Configuring Events section.

tip

You can define different actions for the same event.

Removing an Event

To remove a defined action, simply click on the trash icon located within the event box. This action will result in the removal of the event that is bound to an action.

Toggling Event Execution

To manage whether an event should execute during rendering, you can toggle its execution status using the toggle icon . This allows you to enable or disable the event as needed to meet your specific requirements.

This feature is valuable for scenarios like debugging or temporarily pausing specific event executions without removing them from your application entirely.

Chaining actions

In event coordination, actions are linked together sequentially. Pay attention to the alignment of each action with its predecessor, contributing to the overall flow and effectiveness of the process.

Preview Section

In the preview section, various capabilities are available when actions are bound to a specific event, depending on the type of action. It's worth mentioning that standard actions have no effect in this context.

• Preview Function Code: Selecting a function bound to a particular event allows you to preview its content within the preview section.

  

• Edit Function Code: To directly open and edit a function associated with a specific event, simply select the function and click on the function edit icon .

  

• Open Linked Webform: When dealing with a navigation action bound to a specific event, selecting it allows you to access and open the webform associated with that event, using the same icon .

  

Binding Actions to Events

The Contextual panel facilitates the association of class functions, navigation actions, and standard actions with distinct events within your application.

Standard Actions

Standard actions apply to datasources, and their availability depends on the type of datasource. Datasources can be categorized into three types: Entity, Entity Selection, and Scalar. To bind standard actions with events, follow these steps:

1. Select and Assign: Add an event, and then assign a standard action to your chosen component or datasource by clicking Add a Standard Action.

   

2. Define Action: In the designated Action area, provide the name of the datasource, thus unveiling its inherent capabilities. The available actions vary, contingent on the type of datasource:

   • For Scalar datasources: offer the ability either copy its content into another datasrouce of the same type or clear its content.
     

     Datasource type	Action	Icon	Description
     Scalar	Copy		Copy the content of the datasource to a target datasource
     	Clear		Erase the content within the datasource

   • For Entity selections: offer the ability to arrange and choose attributes for sorting. You can query, refresh, load all entities of a particular data class, and create new empty selections.
     

     Datasource type	Action	Icon	Description
     Entity selection	Order By		Specify one or more attributes to sort and select direction
     	Query		The query is provided as a string and supports the same syntax as an ORDA query, except for formula (eval) and the settings object. Placeholders can be used with datasources or data as-is
     	Reload		Reload the entire entity selection from the server
     	All		Load all entities of the same dataclass
     	Clear		Remove any content and create a new, empty selection of the same dataclass
     	Copy		Copy the entity selection to a target entity selection datasource

   • For Entities from Entity Selections Datasources: you can create new ones, save them, reload them and drop them. You have the ability to navigate through the entity selection, traversing to the first, previous, next, or last entity.
     

     Datasource type	Action	Icon	Description
     Entity	Create a new entity		Generate a new entity from the corresponding dataclass
     	Save the entity		Save the entity on the server
     	Reload		Reload entity values from the server
     	Drop		Delete the entity on the server
     	Copy		Copy the entity to a target entity datasource
     	Clear		Put null in the datasource. If the datasource is the selected element of a component (Matrix, Select box, Datatable), clearing the datasource also unselects the selected element
     	First		Navigate to the first entity within the entity selection
     	Previous		Move to the previous entity within the entity selection
     	Next		Advance to the next entity within the entity selection
     	Last		Navigate to the last entity within the entity selection

   • While Independently Created Standalone Entities: permits only direct actions like create, remove, or reload, as navigation actions are not applicable in this context.
     

     Datasource type	Action	Icon	Description
     Entity	Create a new entity		Generate a new entity from the corresponding dataclass
     	Save the entity		Save the entity on the server
     	Reload		Reload entity values from the server
     	Drop		Delete the entity on the server
     	Copy		Copy the entity to a target entity datasource
     	Clear		Put null in the datasource. If the datasource is the selected element of a component (Matrix, Select box, Datatable), clearing the datasource also unselects the selected element

info

Entities originating from an entity selection datasource enable iterative navigation within the selection, while Independently Created Standalone Entities are generated independently and lack any selection affiliation.

3. Provide Feedback: Enable the Provide Feedback checkbox to customize the handling of unexpected error messages, determining what will be displayed to end users. For more detailed information, refer to the Provide Feedback section. Here, you have the ability to:

   • Provide simple UI feedback on a Save, Reload, or Drop standard action on an entity.
   
   
   • Provide simple UI feedback on a Reload, Order by, or Query standard action on an EntitySelection.

   

Navigation - Webforms

Navigation actions allow you to navigate to a target webform. To bind navigation actions with events, follow these steps:

1. Select and Assign: Add an event, and then assign a navigation action to your chosen component or datasource by clicking Add a Navigation Action.

   

2. Explore Target Webforms: Navigate through the available selection of target webforms, each representing a distinct destination for navigation actions.

3. Define Transition Method: Define the approach through which the target webform will be presented based on the following options:

   • New Tab: Induce the opening of a new browser tab.
   • Current Tab: Replace the ongoing browser tab with the chosen webform.
   • Webform Loader: Access the intended webform through a dedicated Webform loader.
   • Webform Loader (Self): Reveals content within the existing Webform loader
   .

   

tip

The feature for providing feedback is not applicable in the context of navigation events. This implies that users will not have the option to provide feedback regarding their navigation experience.

Navigation - External Links

In addition to navigating to webforms, Qodly Studio offers a convenient way to direct users to external links. The process follows the same steps as outlined for associating navigation actions with events for webforms, with a slight variation in the "Select Target" step:

1. Select Target: Paste the desired external link URL into the "Select Target" field.


2. Choose External Link: Within the "Select Target" field's dropdown list, select External Link.

3. Define Transition Method: Similar to configuring webform navigation, you can specify how the external link will be presented. However, for external links, you have two options:


• New Tab: Induce the opening of a new browser tab.


• Current Tab: Replace the ongoing browser tab with the chosen external link.

Navigation - Shared Folder

Accessing content stored in the Shared folder follows a process similar to navigating to external links. You have the option to display items from this folder, like images, in either a new tab or the current tab by specifying the image path (e.g., /$shared/visuals/banner.png) in the "Select Target" field. Ensure that the path begins with /$shared.

tip

When the path points to a file, it doesn't open it in a new tab but instead initiates a download.

Class Functions

Data model class functions can be linked to events, utilizing parameters from datasources or static values, with the option to assign the result to a datasource as needed. To bind class functions with events, follow these steps:

1. Select and Assign: Add an event, and then assign a class function to your chosen component or datasource by clicking Add a Function Event.

   

2. Select a Function: Browse the available functions and select an appropriate class function. You can link the following class functions to events:

   • Exposed datastore class functions distinguishable by the keyword Datastore.

   
   • Exposed dataclass class functions distinguishable by the keyword Dataclass Name.

   
   • Exposed entity class functions and entity selection class functions, distinguished by the Namespace Of Datasource keyword, encompass shared functions when these entities serve as shared datasources.

   

tip

You can choose to display the function prototype in either table (default) or line format. To switch between these displays, simply click the expand icon located in the upper right corner of the area.

3. Pass Parameters: After selecting a class function, Qodly Studio automatically parses it, extracting its declared prototype. This allows you to visualize and configure its parameter(s) and return value. You can enhance the functionality of class functions by configuring parameters in two ways using the toggle to define how the function parameter(s) should be filled:

   • Hardcoded values: Provide various types of values directly to the class function as parameters by selecting the type through the value icon . Whether it's a string, number, boolean, or any other supported data type, simply choose the desired type from the dropdown list ensuring compatibility with the expected parameter type for precise and accurate results.

     
   The following types are supported as hard-coded values:

   Type	Description	Example
   String	Any string value	Hello World
   Object	JSON syntax	{"age": 12, "name": "Smith"}
   Array	Collection of values	[10, 20, 30]
   Number	Any numeric value	42
   Date	A short-format date	20/12/2024
   Boolean	True or False	False

   
   
   • Datasources: Pass local or shared datasources as parameters to the class function. The scope of the datasource is indicated by a name tag. If the tag reads webform, it signifies a local datasource visible only within the current webform. On the other hand, if there is a tag with a specific name shared, it implies that you have passed a shared datasource belonging to a namespace.
     Make sure the datasource value is of the same type as expected for the parameter by the function, otherwise an error will be returned.

     

4. Select a Datasource for the returned result: In the return parameter section, choose a datasource to store the function's returned result.
   

   • If your class function defines a specific name for the result, that name will be displayed in the label within the return parameter section. For example, if you have a function like exposed function toggleComponent() -> isComponentVisible: boolean, the result label would be isComponentVisible.
   
   
   • However, if your class function does not specify a result name, the default label $0 will be used in the return parameter section.

   
   
   
   
   
   

tip

When you make modifications to the function prototype in the code editor, such as adding or removing parameters or changing their types, and you want these changes to be applied to the Action configuration area, you can easily do so by clicking the Refresh button. Qodly will then re-parse the function prototype to reflect the updated information while preserving the already assigned data sources as parameters.

5. Add Parameter: If your function accepts a variable number of parameters, you can use this button to declare and bind one or more appropriate parameter(s). They will be passed to the function in the defined order when called for the event.

   

6. Provide Feedback: Enable the Provide Feedback checkbox to display backend feedback on the user interface. For more detailed information, refer to the Provide Feedback section.

   

tip

A single class function can be utilized across multiple events, allowing you to assign multiple events to a single function and observe a coordinated sequence of actions taking place.

Providing feedback

To provide feedback within the user interface, enable the Provide Feedback checkbox. This feature allows the backend to communicate with the user by displaying relevant messages regarding the outcomes of different functions or standard actions.

info

Importantly, this customized feedback aligns with the application's business rules and does not disrupt the application's navigation flow.

Toast Notifications

When the Provide Feedback checkbox is enabled, it introduces a hidden internal feedback element into the web page, known as a toast notification. This element automatically showcases messages generated by the application code in response to events, using dedicated webForm functions or by specifying them for On Success or On Failure in the WebForm editor interface, for the case of standard actions.

info

If this feature is not enabled, feedback sent from the backend will not be displayed within the user interface.

Control of Feedback Display

The Provide Feedback checkbox offers manual control over the display of feedback messages when executing a specific function. This manual control is designed to determine when to provide and display feedback, ensuring that messages precisely align with the specific needs of the user and the context.

For example, in the context of a technical document, regular users may require feedback messages to stay informed about the status of their requests, such as waiting for admin approval. However, administrators using a different interface to make modifications to the same technical document, which invokes the same function, might not need to receive the same message due to their administrative roles.

Three Tiers of Feedback

Three tiers of feedback are accessible and will be displayed as colored toasts:

• Informative Messages: Dispatches informative messages when invoked, either directly through the setMessage() function or by specifying them in the On Success field within the event section associated with a standard action.

• Cautionary Messages: Sends out cautionary messages, and these messages are exclusively triggered using the setWarning() function.

• Error Messages: Issues error messages when invoked, either directly through the setError() function or by specifying them in the On Failure field within the event section associated with a standard action.

info

Displaying multiple toasts through a single function is not supported.

Upon calling a function, it initiates an HTTP request, updating the UI simultaneously with the latest changes. This aligns with the principle that one HTTP request results in one response, leading to a single UI update.

Consequently, only the final update from the function will be visible in the UI, showcasing only the last toast.

The time these toast notifications remain visible is typically managed by Qodly Studio's internal logic.

info

They will automatically disappear after a preset 5-second period. Users can also manually dismiss them by clicking on the x icon.

Example of datasource events

In this scenario:

  • The Employee Datatable component displays a list of employees, utilizing an entity selection (bound to the employees catalog datasource).

  • The "General statistics/Detailed statistics" Radio component is linked to the choice webform datasource.

  • Buttons are bound to standard actions that perform queries on the employee datasource (e.g., "salary < 23000").

  • An on Change event is assigned to both the employees and choice datasources. These events call the same function from the EmployeeSelection class, named statistics.

  • For simplicity, the statistics scalar datasource (object) is visualized as a Text component

When a button is clicked or a radio button is selected, the employees datasource updates, prompting the on Change event. This function receives the value of the choice datasource as a parameter and produces general or detailed statistics as an object based on the parameter value.

Here's what you obtain after the button is clicked: