Cola API

Cola is the set of all API available for use in creating bubbles for the Cola Messaging Platform.

Example:

var { Bubble, Conversation } = require('cola-api');

This module provides the following exported classes:

Additionally, it exposes the following classes:

Finally, this document includes infomation regarding bubble manifest files. Although there is no direct access provided as part of the runtime, it is considered part of the platform.

Bubble

Bubble is the class which provides the base services for creating Cola bubbles.


Properties

Bubble.BUBBLE_INITIAL_PAYLOAD

This is a string value which represents the property name to be used for determining the intial payload for the bubble. This property name with its value will be sent to the bubble’s instance.

During compose, this value will be undefined. In other modes, it will be the JSON value from the data stream which had been previously set using the callback to the bubble.bubbleSetupDidComplete() method.

Example:

var myBubble = Bubble.createBubbleClass({
render: function() {
var payload = this.props[Bubble.BUBBLE_INITIAL_PAYLOAD] || {};
var txt = payload.text;
return ({txt});
}
});

Bubble.BUBBLE_MODE

This is a string value which represents the property name to be used for determining the state of the bubble. This property name with its value will be sent to the bubble’s instance.

Example:

var myBubble = Bubble.createBubbleClass({
render: function() {
var txt;
switch (this.props[Bubble.BUBBLE_MODE]) {
case Bubble.BUBBLE_SETUP_MODE:
txt = "Setup Mode";
break;
case Bubble.BUBBLE_OUTGOING_MODE:
txt = "Outgoing Inline Mode";
break;
case Bubble.BUBBLE_FULL_OUTGOING_MODE:
txt = "Outgoing Maximized Mode";
break;
case Bubble.BUBBLE_INCOMING_MODE:
txt = "Incoming Inline Mode";
break;
case Bubble.BUBBLE_FULL_INCOMING_MODE:
txt = "Incoming Maximized Mode";
break;
}

return ({txt});
}
});

Bubble.BUBBLE_INCOMING_MODE

The property value for BUBBLE_MODE when an incoming bubble is being displayed inline.

Bubble.BUBBLE_FULL_INCOMING_MODE

The property value for BUBBLE_MODE when an incoming bubble is being displayed at a maximized size.

Bubble.BUBBLE_OUTGOING_MODE

The property value for BUBBLE_MODE when an outgoing bubble is being displayed inline.

Bubble.BUBBLE_FULL_OUTGOING_MODE

The property value for BUBBLE_MODE when an outgoing bubble is being displayed at a maximized size.

Bubble.BUBBLE_SETUP_MODE

The property value for BUBBLE_MODE when an outgoing bubble is being displayed for setup.

Bubble.Colors

This property value is an associative array containing the color values suitable for creation of a Style Sheet for particular situations. Be sure to use the proper key for the bubble’s mode.

Key Description
PrimaryColor Primary interface and tint color used throughout Cola Messenger
OutgoingBackground Background color used for outgoing, inline bubbles
OutgoingText Color of text displayed in outgoing, inline bubbles
IncomingBackground Background color used for incoming, inline bubbles
IncomingText Color of text displayed in incoming, inline bubbles

Methods

bubble.bubbleSetupDidComplete()

The bubbleSetupDidComplete() method should be declared on the bubble specification provided to Bubble.createBubbleClass(). This method will be called when the user attempts to send the bubble.

When this method is called, it is provided a callback function which should be called to complete the send. It’s during this call when the inital payload data should be constructed and can be sent to Cola in order to place it in the data stream.

The payload data should be kept to a maximum of 1K for the best performance and behavior. Larger data should reside elsewhere and be loaded asynchronously as needed for the user.

Cola reserves two key names in the payload data: initialLayout and cola.io. initialLayout is reserved for the inline bubble sizing (see Initial Bubble Layout for more information). cola.io is reserved for future expansion.

If this method is not provided, only a reference to the bubble is placed in the data stream with no data payload. This could be a desired effect for bubbles which require no saved state for instantiation.

Parameters:

callback
This function must be called to complete the send. It takes one optional argument which must be a JSON Object suitable for serialization.

Example:

var myBubble = Bubble.createBubbleClass({

bubbleSetupDidComplete: function(callback) {
callback({text:this.state.text});
},

render: function() {
var payload = this.props[Bubble.BUBBLE_INITIAL_PAYLOAD] || {};
var txt = payload.text || "Not set";
return ({txt});
}
});

Bubble.createBubbleClass()

The createBubbleClass() method creates a registered Cola bubble from the provided specification and returns a registered Cola bubble.

Parameters:

specification

A bubble class specification to be used as the base component for the bubble. This specification should follow the React.createClass guidelines.

Example:

var myBubble = Bubble.createBubbleClass({
render: function() {
return (This is my bubble.);
}
});

Bubble.sendMinorNotificationText()

Posts a minor notification with the specified text to the conversation stream.

Parameters:

text

This string should contain a succinct reason for the notification. It will be displayed inline for all recipients in the conversation.

This text is not required to contain the participant name or bubble title. These attributes are added to the notification automatically.

Example:

MyBubble.onPressedButton = funtion() {
this.CommitMyVote(this.state.vote);
Button.sendMinorNotificationText('voted');
}

Bubble.sendMajorNotificationText()

Posts a major notification with the specified text to the conversation stream.

Parameters:

text

This string should contain a succinct reason for the notification. It will be displayed inline for all recipients in the conversation.

This text is not required to contain the participant name or bubble title. These attributes are added to the notification automatically.

Bubble.setPreferredSize()

The Bubble.setPreferredSize() method is used to tell the intended size of the bubble while displayed in any of the inline modes. Cola will not allow the bubble to be displayed larger than its computed maximum size or smaller than its computed minimum size.

This method should only be called once during the course of render for an inline bubble. After being displayed at one size, a bubble should refrain from changing the size of the bubble for the user. This can cause an odd “bouncing” effect for the user and may make it difficult to read and interact with this and other bubbles.

A bubble may choose to use a special payload key, initialPayload, instead of this method though. The two forms of sizing should not be used together. See Initial Bubble Layout for more information.

Parameters:

width
This value is an integer value indicating the preferred width of the bubble.

height
This value is an integer value indicating the preferred height of the bubble.

Bubble.setSendEnabled()

This method enables or disables the send button while the bubble is in BUBBLE_SETUP_MODE.

Parameters:

enabled

This boolean value indicates whether the send button should be enabled or disabled.


Initial Bubble Layout

If bubble layout is invariant or known at compose time, specify initialLayout in the payload to avoid unnecessary bubble resizing. The initialLayout object supports three properties: width, height, and ratio.

Because maximum bubble size is a function of screen width, different screen sizes will allow different max bubble sizes. Bubble layouts should use flexbox to be reactive; avoid hard-coding your bubble layout to a specific width or height.

If your bubble requires a fixed height but can resize horizontally, specify only the height property in initialLayout. This will ensure your bubble has a fixed height regardless of screen size.

{ initialLayout: { height: 200 } }

If your bubble requires a fixed width but can resize vertically, specify only the width property in initialLayout. This will ensure your bubble has a fixed width regardless of screen size and a default height that varies w/ screen size.

{ initialLayout: { width: 220 } }

If your bubble requires a fixed aspect ratio (ex. photo or other media), specify only the ratio property in initialLayout, where ratio = width/height. This will ensure your bubble is as large as allowed regardless of screen size, while maintaining the desired aspect ratio.

{ initialLayout: { ratio: 1.778 } }

If your bubble requires a fixed size regardless of screen size, specify both width and height in initialLayout. This will force your bubble to have the same size regardless of screen size.

{ initialLayout: { width: 220, height: 180 } }

Note: if both width and height are specified and either exceeds the computed maximum bubble dimensions (on a given screen), both width and height will be capped to the maximum bubble size while maintaining the aspect ratio implied by these values (width/height = ratio). If only width or height is specified and exceeds the maximum value (on a given screen), value will be capped at maximum bubble value.

Conversation

Conversation represents a discussion among a number of participants.


Properties

Conversation.me

If the current user is part of the conversation, this Participant will represent them. If they are not part of the conversation, the value is undefined. Use Conversation.addParticipantsListener() to watch for changes to this property.
This property may not be populated immediately on instantiation. The default value is undefined.

Conversation.participants

This array contains the known participants of the conversation. This list does not include the Conversation.me participant. Use Conversation.addParticipantsListener() to watch for participants being added or removed.

This property may not be populated immediately on instantiation. The default value is an empty array ([]).


Methods

Conversation.addParticipantsListener()

This method adds a function which will be executed whenever the list of participants changes or if the Conversation.me property changes. It returns a subscription for that event.

More than one listener is supported. A handler should be removed using Conversation.removeParticipantsListener() when updates are no longer needed.

Parameters:

handler

A function which is called whenever Conversation.participants or Conversation.me changes.

Example:

var myBubble = Bubble.createBubbleClass({

participantsChanged: function() {
// Manage participant changes
},

componentDidMount: function() {
this.participantListener = Conversation.addParticipantsListener(this.participantsChanged);
},

componentWillUnmount: function() {
Conversation.removeParticipantsListener(this.participantListener);
},

render: function() {
return (This is my bubble.);
}
});
var MyBubble = Bubble.

Conversation.getParticipant()

This method will return a Participant instance given a participant identifier. If the conversation participants are not yet known or the identifier is not found in the list of participants, undefined will be returned.

Parameters:

identifier

An opaque string reference used to indicate the participant to be retrieved.

Example:

var savedParticipantId = this.state.savedParticipantId;
var participant = Conversation.getParticipant(savedParticipantId);
if (participant) {
// Use participant to get further information.
}

Conversation.removeParticipantsListener()

This method removes the respective listener to a subscription which was returned by a previous call to Conversation.addParticipantsListener().

If Conversation.addParticipantsListener() had previously been called, this method should be called. Without calling this method, the handler may be called at an unexpected time, or the subscription could be leaked memory later.

Parameters:

subscription

The subscription is the result of a previous call to Conversation.addParticipantsListener().

Participant

Participant is a class which represents an individual who is part of a conversation.
Currently, there is no factory or constructor exposed for this class. Instances are only available via the Conversation class API.


Properties

participant.identifier

The identifier is an opaque string reference representing a unique identifier for this participant. If the identifier is not currently available for the participant (for example, Conversation.me during compose), this property value will be undefined.

participant.shortName

A string containing the participant’s short name.

participant.longName

A string containing the participant’s long name.

PrivacyAccess

The PrivacyAccess is responsible for controlling and monitoring changes in access to certain privacy related services. This is used to determine access to such services as the user’s location.


Properties

PrivacyAccess.PRIVACY_SETTING_UNKNOWN

This string value indicates the user has not been asked to provide access to the requested service. The user can be prompted, or the bubble should attempt a call to PrivacyAccess.requestAccessToService() to try to get access.

PrivacyAccess.PRIVACY_SETTING_PRIVACY_SETTING_AUTHORIZED

This string value indicates the user has provided access to the requested service.

PrivacyAccess.PRIVACY_SETTING_DENIED

This string value indicates the user has denied access to the requested service. It is okay to inform the user and ask for access using PrivacyAccess.requestAccessToService() again.

PrivacyAccess.PRIVACY_SETTING_RESTRICTED

This string value indicates the user has restricted access to the requested service. It is okay to inform the user about the lack of access, but the user should not be prompted to alter the access. They have no ability to change it (for example, this is a managed service which they do not control).


Methods

PrivacyAccess.getServiceSetting()

The PrivacyAccess.getServiceSetting() method is used to get the currently known access value for a service. If the value is queried too early and prior to it being known, PrivacyAccess.PRIVACY_SETTING_UNKNOWN will be returned.

PrivacyAccess.requestAccessToService()

PrivacyAccess.requestAccessToService() should be used to prompt the user for access to a service. This is the only mechanism to get the value of the access setting changed.

This method starts an asynchronous process which may involve the user. It will return immediately, but the provided callback will be executed after the access determination or alteration has been made.

Parameters:

service

This string value indicates the name of the service being requested. This same service must have been declared in the bubble manifest as well.

The current supported list of services is

Name Description
location This is used to indicate access to the user’s location.

callback

The callback function will be called upon completion of the request. This function will be provided two arguments, service and setting. The service will be the same service which was requested. The setting is the value of the access after the change, if one was made. It’s possible for the user to not have changed the value, although the callback will still be made.

PrivacyAccess.addPrivacyAccessListener()

This method adds a function which will be executed whenever the access of any of the services changes. It returns a subscription.

More than one listener is supported. A handler should be removed using PrivacyAccess.removePrivacyAccessListener() when updates are no longer needed.

Parameters:

handler

A function which is called whenever privacy access for services change.

PrivacyAccess.removePrivacyAccessListener()

This method removes the respective listener to a subscription which was returned by a previous call to PrivacyAccess.addPrivacyAccessListener().

If PrivacyAccess.addPrivacyAccessListener() had previously been called, this method should be called. Without calling this method, the handler may be called at an unexpected time, or the subscription could be leaked memory later.

Parameters:

subscription

The subscription is the result of a previous call to PrivacyAccess.addPrivacyAccessListener().

Manifest

The manifest.json file contains all the metadata associated with the bubble as well as the required declarations for the runtime of the bubble. It must exist at the top level of the bubble’s file hierarchy.

There are a number of valid keys and values which may be set.

Key Description
format The version of the manifest format being used. The currently valid version is 1.
identifier This is a string whose value is the unique identifier for the bubble. This value should have the developer identifier as it’s prefix. E.g. io.cola.HowsYourWeather for the io.cola. developer profile.
version This is a version number for the bubble. Version numbers are monotonically increasing and must be integers.
name This string value is displayed in the bubble menu, in the inline bubble header, in the bubble bar, and in notifications.
style This is a string value which declares the layout style of the bubble. Valid values are default, edge-to-edge, and full. A missing or unknown value will be handled the same as default.
icons Object with 3 key-value pairs. The keys are each of 22px, 44px, and 66px. The respective values are bubble relative paths to the PNG files for the icons of those sizes (square).
access Ojbect with key-value pairs. The currently valid keys are privacy and services. Each value is an object which makes further declarations.

Style

The style value currently allows for the display of bubbles in three different layouts:

Value Description
default This is the standard layout used for bubbles. It is used for bubbles such as “Track My Flight” and “Quick Poll” These bubbles have a bubble header as well as horizontal and vertical spacing around the bubble.
edge-to-edge The layout of this bubble allows the masking of the content, so it’s clipped arounds its edges. It is used for bubbles like “I’m On My Way” and “How’s Your Weather?” These bubbles have a bubble header, but the content is clipped at the edges.
full The layout of this bubble is similar to edge-to-edge with no bubble header. This is used for bubbles like “Giphy” and “YouTube.”

See “Types of Bubbles” in User Experience Guidelines for more information and guidance on using these bubble styles.


Icons

The icons object declaration is used to define the suite of icons used in the bubble menu, in bubble headers, and in the bubble bar. There are 3 sizes which should be supplied: 22 px, 44 px, and 66 px. They are declared using the similarly named 22px, 44px, and 66px keys, respectively. These values should be strings which are file paths relative to the bubble package.

Based upon drawing context, the runtime will choose the appropriate image for display. The images will be displayed using a tinting technique, so they should be masks and not full color images.


Access

The access object is used to declare certain requirements for the runtime. If certain privacy access and services are not declared, those items will not be available for the bubble when it executes.

The declaration of these items does not cause prompts for the user automatically. User interaction is still the responsibility of the bubble developer.

Currently, there are only two forms for declarations: privacy and services.

Privacy

The privacy object is used to declare which user data the bubble might need to access. All undeclared items will return an access value of PrivacyAccess.PRIVACY_SETTING_DENIED when queried via PrivacyAccess.

Currently, there is only one valid privacy key, location. Each declaration value is an object. At this time, there are no key-values required for these declarations.

Services

The services object is used to declare the use of other external services controled by the runtime. At this time, there are no currently available services.


Example:

{
"format": 1,
"identifier": "io.cola.YouTube",
"version": 1,
"name": "YouTube",
"style": "full",
"icons" : {
"22px" : "resources/icon_22px.png",
"44px" : "resources/icon_44px.png",
"66px" : "resources/icon_66px.png"
}
}