<Require feature="osml">

<Require feature="opensocial-templates">

@person {string|Object} The person object or DataContext key referring to a person object. (required)

Welcome, <os:Name person="${Viewer}"/>

@group {string|Object} An array of person objects or DataContext key referring to 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 data context variable that is set with the selected id(s). (optional)
@onselect {string|function} Client side script function to invoke when a person is selected. (optional)

<form action="/top_friends.php" method="POST">
  Select your top 8 friends:
  <os:PeopleSelector group="${ViewerFriends}" multiple="true" max="8" inputName="top8"/>
</form>

@person {string|Object} The person object or DataContext key referring to
a person object. (required)

My top friends:<br/>
<os:Badge repeat="${TopFriends}" person="${Cur}"/>

@href {string} The URL from which to retrieve HTML content (required)

${Viewer.Name}'s pet information
<os:Get href="http://developer.superpetstore.com/petHtml?petId=${viewer.appData.petId}"/>

Non-Tags

There are a number of potential tags that can be better supported using templating, for reasons outlined below.

Non-tag: Inserting Text Content

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 http://code.google.com/apis/opensocial/docs/0.8/reference/#opensocial.Person.Field for a list)
• Can be used in attributes, such as <input type="submit" value="Share with ${Name}">

Non-tag: Flow Control

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

Non-tag: Pronoun

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.

Interaction with Proxied Content

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.

Flow control and repeated elements

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">
  <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

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">
  <os:PersonRequest userId="@owner" key="Owner"/>
</Content>

Example PHP:

<?php
// Some code that pulls POST param into $Owner
echo "High score for <os:Name person=\"${Owner}\"> is ".getHighScore($Owner['id']);
?>
 
or 
 
<?php
echo "High score for <script type=\"text/os-template\"><os:Name person=\"${Owner}\"></script> is ".getHighScore($Owner[['id']);
?>