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 byitems.x
, wherex
is the item’s label defined in itslabel
attribute (i.e.> label=x ...
)lang
- thelang
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 theiframe
’sheight
attributewidth
: set theiframe
’swidth
attributefull
: enter fullscreen modenormal
: exit fullscreen mode