OpenSocial Markup Language Tags Specification v0.9

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

OpenSocial Markup Language tags defines a set of tags that every OpenSocial compliant container makes available to an OpenSocial application.

To use OSML tags, you need to add the "osml" feature to your gadget spec:

<Require feature="osml"> OSML tags are a strict subset of OpenSocial Templating, you can also use tags if you use the "opensocial-templates" feature:

<Require feature="opensocial-templates"> The reason for separate require features is that templates may not be supported on all views for all containers, due to processing and/or latency costs. OSML tags must be supported in all views.

An OSML tag is invoked much like an OpenSocial template. It needs to be surrounded by a <script> tag with @type="text/os-template":

Welcome, <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Name person="${Viewer}"/></script>!

An implementing Container MUST support at least the tags listed in this section. A Container MAY support additional tags - an effort will be made to make such support as consistent as possible across different Containers, and tags that are deemed useful may be adopted into this specification in the future.

Inline tag to show a person's name. If a profile URL is available it will be linked to. The tag may display additional container bling (i.e. more information on hover), but must do so without breaking up text flow. Attributes: @person {Object} The person object. (required)

Example <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup">Welcome, <os:Name person="${Viewer}"/></script>

Tag to show a UI that chooses from a list of people, and set a form field with the associated value. Attributes: @group {Object} An array of person objects. @inputName {string} Name of the form input element that will contain selected id(s). Containers can provide a default here. (optional) @multiple {boolean} Allow multiple selections? (optional) @max {number} Maximum number of people that can be selected. (optional) @var{string} Name of the top level DataContext variable that is set with the selected person object (or array of objects). (optional) @onselect {string|function} Client side script function to invoke when a selection is made. The function will get the selected person object (or array of objects) as a parameter. (optional)

Example <form action="/top_friends.php" method="POST"> Select your top 8 friends: <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PeopleSelector group="${ViewerFriends}" multiple="true" max="8" inputName="top8"/> </script> </form>

Block level tag to show information about a person in the style of the container, usually with an image. Attributes: @person {string|Object} The person object or DataContext key referring to a person object. (required)

Example My best friend is:<br/> <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Badge person="${TopFriend}"/></script>

There are a number of potential tags that can be better supported using templating, for reasons outlined below. Note that most of these capabilities will require using the "opensocial-templates" feature.

For generating text content, expressions are used instead of tags. Example: ${Viewer.name} or ${Owner.jobs[0].Title} instead of <os:Name> (note that <os:Name> is for showing a linked name, not for inserting text only). Reasoning: Extends to all OpenSocial fields (see OpenSocial, opensocial.Person.Field for a list). Can be used in attributes, such as <input type="submit" value="Share with ${Name}">.

For conditional content, a conditional statement in OpenSocial templating is used along with an expression. Example: <div if="${!viewer.hasApp}"><a href="...">Click here to install!</a></div> or <div if="${jobs[0].Title}">${name}'s job is ${jobs[0].Title}"</div> instead of <os:HasApp> etc. Reasoning: Extends well to a large number of conditional constructs (no need for one tag per condition). Equivalently simple to use.

For pronouns, conditional HTML blocks based on gender are used. Example: <span if="${person.gender == 'MALE'}">He said "boo"</span> <span if="${person.gender == 'FEMALE'}">She said "boo"</span> instead of <span><os:Pronoun> said "boo"</span> Reasoning: You need full sentences to localize properly.

Inlining of remote HTML markup is possible via a combination of Data Pipelining's <os:HttpRequest> tag and OpenSocial Templates variable inlining via the ${data} syntax. Thus a dedicated <os:Get> tag is not needed. Example: <os:HttpRequest key="Data" href="http://example.com/data.html" format="text"> Then use <os:Html code="${Data}"/> in your template. Reasoning: Re-using existing capabilities avoids doing the same thing in two different ways.

The combination of tags, templates, and proxied content leads to a number of combinations for developer to use. Here are a few common use cases and how developers might handle them. This is for informational purposes only - it doesn't extend the proposal, but hopefully clarifies a few use cases.

OpenSocial data will be posted on the developer server and flow control will be handled on the developers own server, in PHP, JSP, ASP, or the language of the developer's choice.

Example Gadget XML <Content href="http://developer.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PeopleRequest userId="@viewer" groupId="@friends" fields="name,birthday" key="ViewerFriends"> </Content>

Example PHP <?php // Some code that pulls POST param into $ViewerFriends here foreach ($ViewerFriends as $friend) { if ($friend['birthday']) { echo "<div>".$friend['name']."'s birthday is".$friend['birthday']"</div>"; } } ?>

Tags can be inserted into the output and will be processed by the container or JavaScript on the client side.

Example Gadget XML <Content href="http://developer.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PersonRequest userId="@owner" key="Owner"/> </Content>

Example PHP <?php // Let the Container know that the Owner object is needed for post-processing ?> <script type="text/os-data" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PersonRequest userId="@owner" key="Owner"/> </script> <?php // Some code that pulls POST param into $Owner echo "High score for <script type=\"text/os-template\" xmlns:os=\"http://ns.opensocial.org/2008/markup\">" . "<os:Name person=\"${Owner}\"></script> is " . getHighScore($Owner['id']); ?>

PHP Output <script type="text/os-data" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PersonRequest userId="@owner" key="Owner"/> </script> High score for <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Name person="${Owner}"></script> is 100

Final Container output after OSML is processed High score for John Doe is 100