Listeners

Listeners define how an event of a particular type from a particular component is processed in the event-processing cycle when it occurs.

When the component produces an event of the expected type, the listener catches the event and sends it to the event-processing cycle. The event is processed as defined by the properties of the listener.

Listeners defines the following:

• Basic properties determine what events they catch and how they are handled:

  • Listener type: the type of event the listener handles

    A listener catches only events with the same type as the listener type. You can use the Generic Listener if you want it to handle any event on the component.

  • Refresh components: comma-separated list of component IDs that are refreshed, that is, their content is recounted and the components are re-rendered.

  • Validators: validation expression

    The event is handled only if the validation expressions are true.

  • Data validation: validation expressions that validate against Constraints

    When using data constraints, the expression should include a validate() call that will trigger the constraint validation.

  • Execute if other validations failed: select to ignore failed validation on other than ValueChangeEvents (refer to chapter on the settings)
  • Execute even if invalid components: enforces execution of the listener logic even if the form contains incorrect data, such as, "aaa" instead of an integer, to allow operations as refresh or reset on click.

  • Handle expression: expression that is executed

    The expression represents the action the listener performs to handle the event.

  • Event identifier: identifier of the received event

    You can use the identifier in the Handle expression to acquire the event fields with event details, such as the component that produced the event, uploaded files, etc.; refer to Filtering Events on Listeners.

• Advanced properties define the context of the execution and actions as well as handling pre-condition:

  • Process components: comma-separated list of component IDs; only events produced by the components are included in the event-processing cycle

    The property allows you to ignore queued event from the specified components of the form, typically, if you have a form with multiple tabs and you want to ignore events with their validation on another tab, or to prevent validation on all components when resetting the content of one component.

  • Execution context: execution context of the listener

    All expressions defined in the listener properties, such as, its precondition, validation, etc. are evaluated in this context level.

    • default: the context level of the component with the listener
    • top level: the screen context of the form
    • component: ID of the component which represents the target execution context

      Important: The execution context setting does not influence how View Models are merged: this is set by the merge type property on the View Model.

  • Execute only if visible components: comma-separated list of component IDs; the event handling takes place only if all specified components are displayed in the form.
  • Clear/merge view model components: IDs of view models (their contexts are cleared or merged to the target execution level).

  • View model init: expression executed right after the merge or clear of view model components

    The expression serves as a hook after the merge-clear phase.

  • Precondition: pre-condition for event handling

    If the pre-condition evaluates to false the event is not handled.

• Actions properties define what actions are performed on the to-do or document after the event is processed:

  • Submit: defines if the document or to-do is submitted as part of the event handling;

    If enabled, the relevant data in the components is persisted and the to-do becomes finished or the document closes.

  • Persist: if enabled, the relevant data in the processed components is persisted as part of the event handling; unlike on submit action, if the form is used by a to-do, the to-do does not become finished; if part of a document, the document remains open; persist is performed after the merge to the screen level before the transaction is committed.

    You can define a persist action, which is performed immediately after the persist.

  • Save action: defines if the to-do or document is saved;

    The save action saves the current state of the to-do or document for later editing, which includes saving the provided data; it is identical to clicking the Save button on a to-do or document in the LSPS Application User Interface; the save action does not persist the data; therefore make sure to define the Persist property if required. If a newer version of the saved to-do or document is available, the application displays a notification.

    Note: A saved document is persisted in the system database as the SavedDocument record. If saved repeatedly, the same record is overwritten; hence only the last saved document version is available. On submit, the persisted document is removed. For more information on the record type and related functions, refer to the Standard Library documentation.

  • Navigation: defines the location where to navigate after the event is processed; you can navigate to a to-do or document, URL, custom application page (refer to the descriptions of data types defined in the human.navigation.datatypes resource in the Standard Library)

    Navigation takes place after persisting, which allows you to use the persisted data in the navigation expression.

    Important: If the form is used in documents, the form navigation is overridden with the document navigation.

  • Fire application event: ApplicationEvent the listener produces
• Expression tab allow you to define the entire listener as an expression: when you select the Listener is defined by expression option, the properties defined on the other tabs are reflected in the generated expression