Working with payload types

When you wire widgets together, you create the communication line that allows data to pass from one widget to another. This data is defined by the event name, the payload (the actual content), and the payload type. The event name provides descriptive information about the event. For example, the event name News breaks can describe an event that fires when users click a link that displays a set of news articles. In this case, the news articles themselves are the payload of the event name News breaks.

So how does the payload type fit into this event-payload model?

The payload type defines the format of data that is passed between widgets when an event occurs. The sending and receiving widgets must both be able to interpret and process a common payload type in order to be wired together successfully. Essentially, the payload type serves as an "interpreter" that determines whether or not two widgets speak the same language. Similar to two humans conversing with one another, two widgets must share a common method of communication if they are to understand each other. If the widgets do not share a common payload type, they cannot be wired together.

For example, let's say that you are creating a mashup for your human resources department. One widget (Widget A) in your mashup is designed to handle employee information. In order to uniquely identify employees, you have designed Widget A to receive an employee's e-mail address when an event occurs on the page. The event name can be something similar to processEmployeeInfo, and the payload type is email. This way, only the widgets that expose email as their payload type can be wired to Widget A.

In order to address the issue of two widgets needing a common payload type, Lotus Mashups has defined a list of common types. Lotus Mashups payload types are defined and associated with events in the widget definition file that is located inside each widget's WAR package. Each definition file contains a string similar to the following:

<iw:eventDescription id="RowClick
" payloadType=“text“/
 

Most of the payload types supported by Lotus Mashups are simple types, for example text, person, phone, and address. You can combine two simple payload types to provide a more complete payload type. For example, you can combine the currency payload type with the countrycode payload type so that the currency value can be associated with that country's monetary system. Combined data types are created in this format: payloadtype1.payloadtype2. For more details about combining payload types, see the Special payload types section below.  

For more complicated data, such as data in XML format, Lotus Mashups supports complex payload types, for example xml, atom, and json. Lotus Mashups also supports special payload types that you can use for custom or unknown payload types. See the following sections for more details.

This article is designed to help you understand the types of payloads that Lotus Mashups supports, including both simple and complex payload types. We also explain which payload types are compatible with each other and how you can implement a public API to create and customize your own payload type when you cannot use of the types provided with Lotus Mashups.

Simple payload types

Simple payload types define common, non-complex data that is typically not used as a container to hold other data. See the following table for a list of simple payload types that are supported in Lotus Mashups:

Payload type	Description
text	A string that contains plain text content, for example Hello World.
url	A string that points to a Web resource, for example http://www.ibm.com. See the discussion about combined data types in the Special payload types section below for more information about how to combine the url payload type.
html	A string that is a fragment of HTML markup, for example <h2   This is a title</h2   .
image	A DOM node or DOM node ID that represents an image on the client side. Can also be combined as url.image to represent an image on the Web.
number	A number, for a example an integer, float, or double. To see an example of a number payload type, see the wiring interface of the Action Timer widget.
countrycode	A string that represents an A3 ISO 3166 country code, for example USA or CHN.
languagecode	A string that represents an ISO 639-2 language code, for example en, es, and fr.
currency	A number that indicates a monetary value, for example 100 or 200. Typically, the currency data type is combined with a country code so that the value can be associated with that country's monetary system, for example currency.USA or currency.CHN.
boolean	A true or false value.
email	A string that represents an e-mail address, such as henry@acme.com.
person	A string that represents a person, such as John Smith or Salvador Gonzales.
postalcode	A string that represents a postal code, for example 27612.
phone	A string that represents a phone number, such as 1-888-555-5555.
address	A string that represents an address, for example 100 Main Street, Boston, Massachusetts, 25443.
date	A string that represents a date in one of the following formats: YYYY-MM-DD YYYYMMDD YYYYMM YYYY where YYYY is the year, MM is the month, and DD is the day. To see an example of a date payload type, see the wiring interface of the Action Timer widget.
time	A string that represents the time in one of the following formats: hh:mm:ss.mmmm hh:mm:ss hh:mm hh where hh is the hour, mm is the minute, ss is the second, and mmmm is the millisecond. To see an example of a time payload type, see the wiring interface of the Action Timer widget.
timestamp	A string that combines the date and time payload types into one of the following formats: YYYY-MM-DD hh:mm:ss.mmmm YYYYMMDD hhmmss YYYYMMDDThhmmss To see an example of a timestamp payload type, see the wiring interface of the Action Timer widget.

Complex payload types

A complex payload type is usually a composite of two other payload types. For example, consider the data in a typical mailing address:

Street number, street name

City, state, postal code

Country

Each of the six pieces of data in the mailing address can be defined individually using the simple payload types provided with Lotus Mashups. However, in order to combine all the data into a single payload that can be interpreted and passed to and from widgets in your mashup, you must define a complex payload type such as mailingaddress that specifies all the pieces of data it supports. You can even combine the mailingaddress data type with additional simple payload types to create a second complex payload type, for example:

Last name, first name

Home phone, work phone

Mailing address

See the following table for a list of complex payload types that are supported in Lotus Mashups:

Payload type	Description
table	A piece of text in comma-separated value (CSV) format that appears in rows. Note the following behaviors: The items in the first row make up the column header. The data types of each column are denoted with a bracket, for example firstName<text   , age<number   , home<address   . If no data type is specified for a column, the text data type is used as the default. If a column uses a comma as part of its data, you must add double quotes (") to the value for that column, for example “109 Hickorywood Blvd., Cary, NC 27590”. If a column uses double quotes as part of its data, for example John "the leader" Doe, you must insert one set of double quotes before the first occurrence and two sets of double quotes after the second occurrence, for example John ""the leader""" Doe.
atom	A piece of text in Atom format, for example an XML file.
xml	A piece of text in XML format, for example: <data type=“table”   Id<number   ,title<text   ,age<number   ,height<number   ,heightUnit<text   101,engineer,49,2.1, meter 209,manager,34,4.3, feet 201,director,45, 5.9, feet </data   Note the following behaviors: The XML must comply with the W3C XML specification, located at http://www.w3.org/TR/REC-xml/. The XML element may have a payload type that indicates its data type, for example <first_name type=“text”   john</first_name   or <home type=“address”   888 Mountview Parkway, SomeTown, CA 99019. If the XML element does not have a payload type attribute, the data type defaults to text. If the XML element does have a data type attribute, but the value of the attribute is not recognized, then the type defaults to text.
json	A piece of text in JavaScript Object Notation (JSON) format.

Creating customized payload types

As a widget developer, you can implement the following public data model application programming interface (API) and create your own customized payload types:

com.ibm.mashups.data.model

When you use a customized payload type, you must update the following string in the widget definition file so that the payload type is set to modeldata, for example:

<iw:eventDescription id="RowClick
" payloadType=“modeldata“/
 

The com.ibm.mashups.data.model API provides the following methods:

getValue

getValueType

getValues

getAttributes

hasAttribute

isItem

fetch

serialize

This API also supports the method fetch callback function:

onBegin (size, request)

onItem (item, request)

onComplete (items, request)

onError (errorData, request)

For more information about how to implement this API, see the IBM Lotus Mashups API Reference.

Note: As you create new payload types, be sure that you do not use any payload type names that are reserved for Lotus Mashups. If you specify a payload type name that is already supported by Lotus Mashups, your mashup will produce errors at runtime.

Special payload types

In addition to the simple and complex payload types described above, Lotus Mashups also offers the following three specialized payload types. See the table for more information.

Payload type	Description
modeldata	A payload type designed to interpret customized data types that you create using the com.ibm.mashups.data.model public API.
any	A common payload type that can support any type of data. The any data type is useful in cases when you are not sure what format of data the event will produce. It is also useful in cases where the event payload may change, for example when sending event data to the Event Explorer widget from other widgets that may support various data types.
combined	A payload type that combines two or more payload types into one. For example, if your event payload is a URL that always points to an image, you can combine the url and image data types into the following combined data type: url.image. In a different scenario, you can also combine the url payload type with a simple payload type and either the countrycode or languagecode payload types to further define the data, for example: url.simplepayloadtype.countrycode url.simplepayloadtype.languagecode

Understanding compatible payload types

Certain payload types can communicate with other payload types. For example, when sending a URL from one widget to another widget, and that URL payload is defined with the url simple payload type, any receiving widget that accepts the text payload type can process the URL. Learning which payload types are especially important when attempting to create automatic wiring by dropping widgets onto other widgets. If the payload types are the same or are compatible, then the wiring will take place successfully. However, if the payload types either do not match or are not compatible, the wiring will not be created and your mashup will not function properly, even though you may have not gotten any type of error indicating a problem.

See the following table to learn which simple data types are compatible:

Receiving payload type	Sending payload type
The text data type can receive the following data types:	url html number   countrycode languagecode currency boolean date, time, timestamp email postalcode phone address   person feed json
The date and time data types can receive the following data type:	timestamp

Simple payload types can also receive a combined payload type but only when it can ignore the suffix, allowing it to create a match. For example, the url payload type can receive a url.text payload type. The combined payload type can never receive other payload types. Finally, complex payload types can only receive matching payload types.