Message Handler Example
Step 1 - Prepare Perspective Workspace
- Open the Designer.
- Switch over to the Perspective Workspace by clicking on Perspective in the Project Browser.
- Right-click on the Views folder and select New View.
- Give the new View a name and click the Create View button. The name of the view will not matter for this example.
- Place a Button and a Label component on the View.
Step 2 - Create A Message Handler
Message Handlers are effectively user-created scripting events. A user can define a Message Handler that listens for a particular message. The idea being that some other component will broadcast a message, and if the type of the message matches what the Message Handler is listening for, the Message Handler will execute a script.
Message Handlers are useful because they don't care about which component broadcast the message: if something sends a message with the correct type, then the Message Handler will execute. Additionally, message can be sent across separate views, pages, or throughout the entire session.
In our example, we want the Label's text property to change when something else in the view happens (in our case, our button is pressed), so it would make sense to configure a Message Handler (listener) on the Label. This way, if we relocate the Label component in the view, the script will still work.
- Right-click on the Label, and select Configure Scripts.
- The Script Configuration window appears. Make sure the title bar on the window states that it's the Label component.
- On the left side of the Script Configuration window, you will see a tree. Double-click on the Add handler... item.
- A new handler named "type-name-here" will appear. Under Message Type type
my-handler. Note that we're using all lowercase characters: message handlers are case-sensitive. The Message Type is effectively the name of the message handler. When sending a message, we will specify this message handler's type, which will cause it to respond by executing the script.
In our example, let's change the text on the Label to "Hello!". Under the script area, type the following script:
- This example is fairly limited to this one view. Thus, let's limit the scope so that it will only respond to messages from the same view the Label is on. Under the Listen Scopes, uncheck Page, and check View.
- The window should look like the following:
- Click the OK button. We just created a Message Handler. In the next step, we'll create a script that will call the Message Handler.
Step 3 - Send A Message
In this step, we place a script on the Button that will call our Message Handler.
- Right-click on the Button, and select Configure Events... The Event Configuration window appears.
- We want our script to trigger when the button is pressed. On the left side of the window, in the Mouse Events folder, select onClick.
- The Organize Actions list will appear. Press the Add icon. A popup list will appear.
- Select the Script action.
Add the following code:
The window should look like the following. Note the tab indentation on lines 4 and 5:
Click OK to apply the script.
The example is now running. From the Designer, enable Preview mode, and then click on the Button component. The text on the label should update.
In this simple example, the major issue you may run into is the Message Type. Recall from #4 in Step 1 of the example, that Message Type is case-sensitive, so make sure the script on the Button is correctly referencing the message type, and try again.
Passing Parameters Example
Let's make the previous example more complicated and pass some values with the message. The example above can be modified to determine the timestamp. When passing parameters in a script, the most direct approach is to include any parameters along with the message. Message Handlers have a built-in argument called a payload, which is used to transfer values to the handler. The payload is simply a Python Dictionary, so please see the Dictionaries page for more information.
Alternatively, we could create a session property to hold the value, and have the label reference the session property. However this would require that we either create a new property to hold the value or overwrite the value of another property. Thus, our next example will demonstrate how to utilize the payload.
Avoid Storing Values in Tags
Since Tag values are shared by all Perspective sessions, you may not want to write the parameters in Tags. Doing so would result in each session instance potentially trying to overwrite the same value.
Step 1 - Update the Button Script Action
- Right-click on the Button component and select Configure events...
Replace the code with the following:
Make sure the code is properly indented. It should look like the following:
On line 8, we're creating a dictionary, creating a key called "time", and storing the current time with the "time" key. When our handler receives the payload, it can retrieve the value we passed by referencing the "time" key.
- Once finished, click the OK button.
Step 2 - Update the Message Handler
Now that we're including a payload with the message, we need to modify our handler so that it will extract the time from the payload.
- Right-click on the Label component, and select Configure scripts...
Replace the original code with the following:
- Click OK.
- To test it, enable Preview mode, and click the Button component. You will see the current time populate in the Label.