Bookmark+-
❀1-0
Arthur Liao
5 years ago (updated)

The RICH Player Development Guide

Basic Requirements

Each RICH player should at least include the RICH messaging library and invoke RICH.init. Please keep the code slim and mobile-friendly.

1. Include the RICH Library

The RICH player is executed within a sandboxed iframe of a RICH client webpage. It communicates with the parent window using window.postMessage method defined in the RICH messaging library. Please include these lines in your main HTML file:

<script>
window.RICH=window.RICH||{version:"1",origin:"*",_c:0,init:function(cb){RICH.
send({command:"init"},cb)},send:function(m,cb){var id=m._id=++RICH._c; m._ver
=RICH.version;if(cb){var ln=function(m){var o=m.data;if(o&&o._id===id){r();cb
(o.data)}};var r=function(){window.removeEventListener("message",ln)};window.
addEventListener("message",ln);setTimeout(r,3e4)}window.parent.postMessage(m,
RICH.origin)}};
</script>

Alternatively, you can just include this line:

<script src="//storage.googleapis.com/twincl-rich/1/player.min.js"></script>

2. Invoke RICH.init

Upon window.onload event, the player should invoke RICH.init with a callback function to receive a RICH snippet object to render:

RICH.init(function (result) {
  // Initialize and render
});

The result object contains the parsed RICH snippet to render. It has the following fields:

  • item - the first item in the snippet, which has these fields:
    • data - the item data defined in the data block (the text below the attribute line > ...)
    • other fields - the item attributes defined in the attribute line
  • items - all items in the snippet (an array); it can also be referenced by items.x, where x is the item’s label defined in its label attribute (i.e. > label=x ...)
  • lang - the lang attribute of the parent window’s html; use this for i18n support

Note that when specifying item attributes in the attribute line of the snippet, users may prepend an asterisk * to the attribute name to specify a global attribute. Global attributes apply to all items, e.g. > *global-attr=value1 local-attr="value 2" ....

Development and Registration

1. Use test player

There is a special test RICH player to help player writers test the player code during development. Refer to the test player usage page for more details. You may write a test post in your personal /notes area where people won’t see it.

To further speed up the development cycle, you can mockup RICH.init function to run the player code without connecting to Twincl site. For example:

RICH.init = function (cb) { cb({item: {data: '...', ...}}); };

2. Host files on the Internet

When the player development is done, put the player files somewhere on the Internet. For static files with low traffic, GitHub or Dropbox may suffice. If the traffic becomes high and causes some problem, we may host the player files for you.

The tic-tac-toe player is an example of hosting on GitHub: https://github.com/arthurtw/tic-tac-toe.

3. Register the player

Go to /rich/player to write a registration/usage post for the player. Refer to the template post and existing players as examples. We will add the player to the system as soon as possible.

RICH Messaging API

RICH.init(callback)

Send an init command to the parent window.

RICH.send(message, callback)

Send a message to the parent window. The message object must contain a command field to indicate the command type. The optional callback function will be called upon receiving response from the parent window. Its parameter is the received result object.

Messaging commands

"init"

The initialization command. The response contains the parsed RICH snippet object.

"ping"

The dummy ping command. The response contains no result object.

"screen"

The screen size command. The fields are:

  • command: "screen"
  • height: set the iframe’s height attribute
  • width: set the iframe’s width attribute
  • full: enter fullscreen mode
  • normal: exit fullscreen mode
Bookmark+-
0 comment Comment