2018-10-10
1.0.1
OutSystems R&D
All
All
Libraries
[Overview]
Web Block template that allows you to trigger Web Block Events from JavaScript
[Detail]
The UI logic of Web Blocks runs server-side, so events can only be triggered after an interaction that causes a server request, like the user clicking a Button or Link that is bound to an Action.
Some extensibility scenarios may require events to be triggered directly from JavaScript without the need of a UI element, like reacting to browser events such as when resizing a window or scrolling along the screen.
This Forge component provides a block that allows you to trigger its event by calling a JavaScript method, encapsulating all the details needed to perform the server call that will trigger the event server-side.
This block is a template and is meant to be duplicated instead of reused. This is a better option because it allows you to configure the number of parameters of the event and its types. It’s much better when all parameters are clearly defined with the correct data types, preventing hard to find errors that usually occur when parsing serialized arguments from a string, which is typically the general solution to send multiple types of data using a fixed interface.
Using the block
Copy the block from the Forge component and paste it in your module.
Drag the copy of the block to the screen where you want to trigger an event and give a name to the block.
Now go to the Handler property for the EventFromJS event of the block on the screen and select the option to create a new Screen Action.
In that action, implement the logic you wish to run when the event is triggered.
Now that we have the handler set, we need a way to trigger the event. Add an Expression widget at the end of the screen and set its Escape Content property to No.
Edit the value of the expression and add the JavaScript code that will end up triggering the event. To do the trigger add the following code:
TriggerEvents('" + [your block name].Id + "', [your text value]);
Publish, open the screen in the browser and see the magic happening.
Customizing the block
Adding a parameter
Open your copy of the block.
Create a local variable on the block with the desired name and type of the new parameter.
Create an input parameter on the EventFromJS event with the same type as the local variable.
Duplicate the in1 input widget and place the copy next to the existing input. The new input will be automatically renamed to in2.
Change the variable of the new input to the newly created variable.
Change the data-p extended property value of the new input to 2. Each input must have a unique sequential number on a 1-based integer sequence. This is how we fill the values of the variables with the arguments sent in the TriggerEvents JavaScript function, by mapping the argument index with the value of the data-p extended property on the inputs.
In the TriggerEventButton widget map the newly created input parameter of the event in the Destination to the newly created local variable.
You’re done. Now, when calling the TriggerEvents function you will be able to pass an extra argument for this new parameter.
TriggerEvents(blockIdentifier, existingParameter, newParameter);
Deleting the parameter
Open your copy of the block.
Delete the local variable.
Delete the input parameter from the EventFromJS event.
Delete the input widget of the block, which should be marked as having an error because the variable it was bound to no longer exists.
You’re done. Now, when calling the TriggerEvents function you no longer need to pass the second argument:
TriggerEvents(blockIdentifier);
In-depth look: How does data flow from the JavaScript function to the event handler
The TriggerEvents function assigns an index to each parameter, by order of declaration. In the example call of TriggerEvents(MyBlockInstance.Id, "My Name", 42); the parameters will be associated with the following indexes:
"My Name": 1
42: 2
The function then searches for the inputs that have a data-p extended attribute with those indexes and sets their values with the ones passed as arguments.
data-p = 1 -> input.Value = "My Name"
data-p = 2 -> input.Value = 42
The function then triggers a click on the TriggerEventButton widget, which will cause the value on the input widgets to be transferred to the variables they’re mapped to. The button will then trigger the event set in its destination sending the value of each local variable to the Event Parameter they are bound to. On the screen or block using the EventExtensibilityBlock, the handler action which was mapped to the block event will be executed and will receive in its input parameters the values sent in the input parameters of the event.