RIA Messaging Basics

Everything in Appcelerator is accomplished via messaging. In this section, we will describe the basics of how messaging works in an Appcelerator RIA.

The Web Expression Language and Messaging

RIA Messaging is made easy by Appcelerator’s Web Expression Language. The Web Expression Language turns standard HTML elements into dynamic RIA components. You can enable the Web Expression by simply adding an on attribute to any HTML element. All expressions following the same basic syntax:

on="[condition] then [action]"

The Web Expression Language allows HTML elements and Appcelerator widgets to both send and receive messages.

Message Format

Appcelerator messages have a name and a payload. The name is simply a string that you define (we typically use dotted notation). Client-generated message names are prefixed with either l: or r:. The l: stands for Local and the r: stands for Remote. Local messages remain on the client-side and are only sent to UI elements. Remote messages are sent to both UI elements and to server-side Appcelerator services. Here is an example message name:

r:save.user.request

This message will be sent to all UI element and service listeners because it has the r: prefix for remote.

Subscribe and Publish Made Easy

Specifying a Message as a condition is how an element subscribes to message. Specifying a Message as an action is how an element publishes a messages. Here’s an example of how to subscribe to a message.

<img src="images/indicator.gif" on="r:login.request then show">

In this example, the image tag is listening for a remote message named login.request. When this message is received, the image will be displayed. Now, let’s look at an example of how to publish a message.

<input type="button" value="submit" on="click then r:login.request"/>

In this example, the button will generate the remote message named login.request when the button is clicked. That’s all there is to it.

Message Data Payload

Messages also have a data payload. All data payloads are JSON-based, but we have greatly simplified the syntax for adding or reading payload data. The example below show how you can generate a message with a data payload:

<input type="button" on="click then r:save.user.request[newuser=true,key=$user_id]"/> 

In the above example, a message will be sent when the button is clicked. The message will have two items in the data payload newuser=true and key=$user_id. Notice that the latter uses the $. Appcelerator allows you to prefix the element ID of an HTML element with a $ to get its value, so in this example, we send the actual value of an element with an element ID = “user_id” along with the message’s data payload.

You can also easily evaluate the data payload in a message in order to determine if a particular condition is met. Here’s an example:

<div on="r:save.user.request[newuser=true] then effect[Fade] else hide"></div>

In the above example, the DIV will perform a “Fade” effect ONLY when it receives the message r:save.user.request with the value newuser=true in its data payload, otherwise it will hide itself.