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 be able both 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, you might be 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 email 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, Mashup Center has defined a list of common types. Mashup Center 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="url.table"
Most of the payload types supported by Mashup Center are simple types, for example text
, 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
For more complicated data, such as data in XML format, Mashup Center supports complex payload types, for example xml
, and json
. Mashup Center also supports special payload types that you can use for custom or unknown payload types. See the following sections for more details.
The following sections are designed to help you understand the types of payloads that Mashup Center 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 Mashup Center.
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 Mashup Center:
Table 1. Simple payload types
|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. See ISO 3166 Codes (Countries) for more information.|
|languagecode||A string that represents an ISO 639-2 language code, for example en, es, and fr. See Codes for the Representation of Names of Languages for more information.|
|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 firstname.lastname@example.org. |
|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:
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:
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:
To see an example of a timestamp payload type, see the wiring interface of the Action Timer widget.
- YYYY-MM-DD hh:mm:ss.mmmm
- YYYYMMDD hhmmss
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
Each of the six pieces of data in the mailing address can be defined individually using the simple payload types provided with Mashup Center. 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 Mashup Center:
Table 2. Complex payload types
|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:|
201,director,45, 5.9, feet
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> or <home
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.
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:
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:
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® Mashup Center API Reference
As you create new payload types, do not use any payload type names that are reserved for Mashup Center. If you specify a payload type name that is already supported by Mashup Center, your mashup will produce errors at runtime.
Special payload types
In addition to the simple and complex payload types described above, Mashup Center also offers the following three specialized payload types. See the table for more information.
Table 3. Special payload types
|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:
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 compatible is 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:
Table 4. Compatible payload types
|Receiving payload type||Sending payload type|
|The text data type can receive the following data types: ||
- date, time, timestamp
|The date and time data types can receive the following data type: ||timestamp|