LSPS Documentation
When the user performs an action on a form component, such as, changing a value, clicking a button, moving a widget, etc. the component produces an event of a type: the type depends on the action. The produced event holds data about the actions.
If the component has a listener that is listening for an event of the given type, it catches the event. These caught events are add to the event queue. Most events, called immediate events, trigger the request-response cycle and hence are processed immediately along with all the events in the event queue. If the event is not immediate, it waits in the queue until an intermediate event enters the queue and triggers the request-response cycle.
Some event types are immediate by default; other event types are non-immediate and can be set as immediate explicitly if required.
All queued events are processed simultaneously: the way the events are handled and the actions they cause are defined by the listeners that caught them; for example, a listener can request refreshing of form components, data validation, etc.
Events have their properties stored in their fields: for example, the ChartClickEvent contains fields with details on where exactly on the chart the click occurred so the listener can define different actions depending on the location where the user clicked.
Form components produce events of different types depending on the action that created the event. Here is a brief summary:
ApplicationEvent produced by any event as part of the event processing
Application events can be fired by an event of any type and is broadcast to all form components.
All input components
The time when the change-value event is processed depends on the setting of immediate mode.
The InitEvent is fired when a component is displayed, be it for the first time or after it was saved or when it became visible.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component that produced the event |
| isFirstLoad | Boolean | true for a component displayed for the first time (the property is true also when a hidden component is displayed for the first time) |
| isFirstLoadAfterSave | Boolean | true for a component displayed for the first time or for the first time after save |
The ValueChangeEvent is fired by input components and that when the user changes a value in an input component and changes the focus or on when they select an option.
Note: When ValueChangeEvent takes effect depends on whether its input component is immediate, which is defined by the Immediate property of the component.
If the component has the Immediate property set to
true, the event is processed as follows:
- If on a Text Box or Text Area, the event is produced and handled when the component loses focus, that is, after you edit the value and click another component or press Enter.
- If on Lists, Check and Combo Boxes, the event is produced and handled when an item is selected.
If the property is set to
false, then the event is produced at the same time but remains unhandled, that is, the request-response cycle is not triggered: Instead it is added to an event queue. The queued events are processed on the next run of the request-response cycle, that is, when a ValueChangeEvent with activated immediate mode or an event of another type is handled. This typically happens when the user confirms the value changes by clicking a button (a listener for the ActionEvent must exist).
When a ValueChangeEvent occurs, the new value undergoes conversion validation before the events are actually processed. On conversion validation, the server checks, if the new value has the correct form. If this validation fails, the component is marked as invalid and the ValueChangeEvent, any ApplicationEvents and ActionEvents are not processed any further.
Note that when you change a value in an input component, the value change is applied on the bound entity, such as, a variable, even if no listener for the value change event exists. To prevent this behavior, use nested contexts.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component that produced the event |
| oldValue | Object | Object with the value before change |
| newValue | Object | Object with the value after change |
The AsynchronousValueChangeEvent is fired and processed immediately when the user changes a value in a Text Box or Text Area component.
The event is fired asynchronously: a new one can be fired even if the old one is still being processed.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component that produced the event |
| text | String | String with the input |
The ActionEvent is fired when an action or image component is clicked, when a file upload is started, and when ENTER is pressed on the TextBox component.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component that produced the event |
The FileDownloadEvent is fired when the File Download component is clicked.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component that produced the event |
The FileUploadEvent is fired when file uploading finishes. Note that on upload start, an ActionEvent is fired.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component that produced the event |
| uploadedFiles | Set<Files> | Set of uploaded files |
| errorMessage | String | Error message returned if the upload fails |
The ChartClickEvent is fired when a data point of a chart element is clicked.
The event contains the data series, key, and values of the clicked chart location. This allows you to implement, for example, data drill-down.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component that produced the event |
| series | String | Label of data series that was clicked |
| key | Object | Key value for the data point |
| value | Decimal | First value defining the data point |
| value2 | Decimal | Second value defining the data point |
| payload | Object | Payload of the data point |
The WidgetChangeEvent is fired when a widget is added, removed, resized, moved, or hidden.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | widget component that produced the event |
| widgetId | String | ID of the widget that produced the event set in the Widget ID parameter |
| configuration | WidgetConfiguration | Widget configuration with details about the widget visualization properties |
The CalendarCreateEvent is fired by a calendar component when the user clicks and drags over a period in a calendar. The event holds the selection data as its payload and the data can be used to create a new calendar entry.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | Calendar | Calendar component that produced the event |
| from | Date | Start date of the selected period |
| to | Date | End date of the selected period |
| allDay | Boolean | If the entry is a whole-day event (if selected across days, the entry is an allDay entry; if the selected area is across hours, the allDay property is false and the exact hours are included) |
The CalendarEditEvent is fired by a calendar component when a calendar entry is clicked. Note that the event has as its payload the business object of the calendar entry that was clicked.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | Calendar | Calendar component that produced the event |
| data | Object | Business object of the calendar entry that was clicked |
The CalendarRescheduleEvent is fired by the calendar component when a calendar entry is dragged-and-dropped to a different date. Note that the event has as its payload the business object of the rescheduled calendar entry.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | Calendar | Calendar component that produced the event |
| from | Date | Start date of the new period |
| to | Date | End date of the new period |
| data | Object | Business object of the calendar entry that was rescheduled |
The GeolocationEvent is fired by the Geolocator component after the component has acquired the geographical position of the user or when the request for location times out.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | Geolocator | Geolocator component that produced the event |
| position | Geoposition | Data on position including latitude and longitude, speed, altitude, etc. |
| failure | GeolocatorError | Type of error if locating failed |
The MapClickedEvent is fired by the Map Display component when the user clicks into the map.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | MapDisplay | Map Display component that produced the event |
| point | GeographicCoordinate | point that was clicked |
The MarkerClickedEvent is fired by the Map Display component when the user clicks a marker.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | MapDisplay | Map Display component that produced the event |
| makerData | Object | underlying marker business object (the respective object of the set defined in the Markers property of the Map Display component) |
The MarkerDraggedEvent is fired by the Map Display component when the user drag-and-drops a marker.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | MapDisplay | Map Display component that produced the event |
| makerData | Object | underlying marker business object (the respective object of the set defined in the Markers property of the Map Display component) |
| newLocation | GeographicCoordinate | new marker position after dropped |
The MenuEvent is fired when the user clicks an item in the context menu.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Component with the context menu |
| id | Object | id of the clicked MenuItem object |
The TreeEvent is fired when the user expands or collapses a tree item, be it in a tree or a tree table component.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | UIComponent | Parent Tree or TreeTable of the treeItem |
| treeItem | TreeItem | TreeItem object that produced the event |
The TablePageSizeChangeEvent is fired when the user changes the size of a paged table.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | Table | Parent Table |
| pageSize | Integer | page size after the change |
The PopupCloseRequestEvent is fired when the user clicks the close button in the caption of a popup component.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| source | Popup | Popup that requested close |
The ApplicationEvent can be produced by any listener: it is the only event, the user can define out-of-the-box: When a listener catches its event, it can fire an ApplicationEvent as part of its logic. The event can be caught by any ApplicationEvent listener in the form, and that including listeners on any hidden components and reused forms.
Table with event properties
| Property | Data Type | Description |
|---|---|---|
| eventName | String | Custom name of the ApplicationEvent |
| payload | Object | Custom event data |
For example, let's assume a form for placing orders. It contains multiple nested reusable forms: one contains customer details, another ordered items, and the last one invoicing details. All three reusable forms need to be validated before the order can be placed. The Place Order button located in the parent form, will fire an ApplicationEvent that will be handled by ApplicationEventListeners on the reusable forms. The listeners will trigger validation and any other actions needed as part of the event handling.
To distinguish application events, use the event fields.
For example, let us assume an application form with personal details, application details has Reject and Accept buttons, and a Reusable form with additional data on reject. If the user rejects the application, the provided data must be validated and the reject form must appear and they must provide the relevant rejection data. If they accept the application, no comment is required. However, all other components must be still validated.
The underlying form will define the two buttons with listeners that throw the OnSubmit ApplicationEvent. However, the Reject button will throw an ApplicationEvent with the REJECT value as its payload field, while the Accept button throws an ApplicationEvent with the ACCEPT value as its payload field. The input component for the comment must therefore define an ApplicationListener that will check that the ApplicationEvent payload is ACCEPT or if the payload is REJECT, it will check that the comment component is not empty.