| OpenSocial | OpenSocial and Gadgets Specification Group |
| <opensocial-markup-language-tags-specification-v0_9> | April 15, 2009 |
OpenSocial Markup Language Tags Specification v0.9
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 [RFC2119]. Domain name examples use RFC2606 [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:
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:
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:
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:
Reasoning:
For conditional content, a conditional statement in OpenSocial templating is used along with an expression.
Example:
instead of
Reasoning:
For pronouns, conditional HTML blocks based on gender are used.
Example:
Reasoning:
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:
Reasoning:
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
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels" , RFC 2119, March 1997. |
| [RFC2606] | Eastlake, D. and A. Panitz, "Reserved Top Level DNS Names" , RFC 2606, June 1999. |
| [OS] | social, o., "OpenSocial Specification v0.9" , January 2009, <Opensocial-Specification.html>. |