OpenSocial Templates - Draft Proposal

[Evan Gilbert]

Hi all - I'm restarting the thread on adding template support to OpenSocial. Templates will be discussed in detail at the OpenSocial summit this upcoming Wednesday - please attend and join in the discussions if you have an interest in the subject.

Draft proposal is up at http://groups.google.com/group/opensocial-and-gadgets-spec/web/opensocial-templates. Once we get agreement on the basics we will follow up with a more formal spec document.

Some notes on the proposal:

You can embed template content directly into gadget <Content> sections or HTML documents using a <script> tag.
• OpenSocial tags are prefixed (by convention) with "os:". However the templating system supports multiple markup libraries - containers, library developers and gadget authors can all define their own tags.
  
Templates can be processed using just a JavaScript include. The language also supports server-side processing for performance or security.
Expressions in templates can reference data returned from OpenSocial API calls as well as data provided by the gadget author.

Next step: everyone gives feedback. I've already incorporated some great feedback from initial discussions with Chris & Marco at MySpace and Mike at hi5 - looking forward to hearing from the rest of you.

Cheers,
Evan

Target schedule (note: I pushed back the original schedule by 3 weeks to allow the 0.8 spec discussions to die down):

- May 12th. Draft proposal submitted to spec group for feedback
- May 14th. Template discussion at OpenSocial summit

- May 12th - June 2nd. Discussion on the spec mailing list. Goal is to resolve all issues by the 2nd.
- June 9th. Final spec + sample implementation

[Reinoud Elhorst]

I can't make it to the OS summit tomorrow. I like the proposal in general, some quick remarks:

• I can't seem to find and i18n support, how would this work?
• In http://groups.google.com/group/opensocial-and-gadgets-spec/web/outline-of-proposal the content-type text/os-template is being used, on other places text/template
• Is it possible to include a (java)script block in a template, without the javascript </script> tag closing the template-script block. If so, does this mean that all HTML within the template should be XML-compatible.
• The suggested method of using variables means that some object members cannot be accessed. example: myvar = {}; myvar["foo.bar"] = hello. Not the worst, as long as we realise this.
• I'm not a big fan of overloading html attributes. I would better like only the <if> <else> <repeat> tags.
  

[Evan Gilbert]

Reinoud - thanks for the feedback.

Responses inline...

On Tue, May 13, 2008 at 3:41 AM, Reinoud Elhorst <rei...@hyves.nl> wrote:

I can't make it to the OS summit tomorrow. I like the proposal in general, some quick remarks:

• I can't seem to find and i18n support, how would this work?

Mike from hi5 has some good ideas on this front -  either he or I will post soon with more details.

• In http://groups.google.com/group/opensocial-and-gadgets-spec/web/outline-of-proposal the content-type text/os-template is being used, on other places text/template

text/os-template is the plan (or possibly x-os-template - does anyone know how to choose a mime type?) I'll clean the text/template references.

• Is it possible to include a (java)script block in a template, without the javascript </script> tag closing the template-script block. If so, does this mean that all HTML within the template should be XML-compatible.

The goal is to support <script> functionality, although you're right that the closing </script> will close the script block. We considered using the deprecated <xmp> tag instead of <script> for this reason (among a few others), but it felt too hacky. We'll probably add a special <JavaScript> tag to allow for JavaScript content.

HTML within the <script> template is a valid XML fragment - expectation is that the templating system will add the equivalent of a surrounding top level tag and namespaces.

• The suggested method of using variables means that some object members cannot be accessed. example: myvar = {}; myvar["foo.bar"] = hello. Not the worst, as long as we realise this.

You're right - this also impacts looking up by a variable that is a key. We'll probably need an addition that supports myvar[4], myvar["foo.bar"], and myvar[key] where "key" is another variable.

• I'm not a big fan of overloading html attributes. I would better like only the <if> <else> <repeat> tags.

This is common feedback :)
 
I'm a strong proponent of attributes for a couple of reasons:

• It is possible to create a validating schema. With elements, you have to allow the <if>/<repeate> elements everywhere which makes it nearly impossible to write a clean schema.
• It reduces nesting. This may seem trivial, but my experience with XSLT is that it becomes impossible to follow the structure because control flow statements dominate the markup.
  

I'll add a page soon to the proposal to discuss this issue, and include examples each way.
 

[Mike Austin [hi5.com]]

Hello Reinoud, this is Mike Austin from hi5...

Evan and I have been talking offline a bit about templates, especially
about localization. The main feedback from our developers was to make
it easy to write localized apps without much work. An option is to
provide a default message in an <os:Message> type tag, and possibly
extracting this information to build a resource XML file so developers
don’t have to think so much about managing resources.

There are a few possibilities for the message tag itself, with pros
and cons:


* Tag based, attribute parameters

<os:Message key="gave_gift" gift=”${theGift}” /> or
<os:Message key="gave_gift" gift=”${theGift}”>Optional default message
${gift}</os:Message>

The nice thing about this is that it’s short. The issue is that it
can’t be XML validated because you’re passing dynamic attributes.


* Tag based, tag parameters

<os:Message key="gave_gift">
<os:Param key="gift" value="${theGift}">
<os:DefaultText>Thanks for the ${theGift}</os:DefaultText>
</os:Message>

This validates, but is quite a lot to type. Our developers would
prefer the least amount of overhead.


* Attribute based, attribute parameters

<span msgId="gave_gift" gift=”${thiGift}” />

This goes more in line with a “microfotmat” style, and is possibly the
shortest. The issue is that if you start overloading attributes to do
different things, it can get confusing – for example when you provide
conflicting attributes.


As for the <if> <else> <repeat> tags, I am somewhat a fan of this
also. It is true, as Evan said, that sometimes the logic can start
dominating the markup. I guess it depends on your style. Maybe we
can have our cake and eat it too?


Regards,
Mike Austin

PS, I can't seem to add another address to this account so I can post
from my hi5 address. I guess I just need to create another account?

On May 12, 4:53 pm, Evan Gilbert <uid...@google.com> wrote:
> Hi all - I'm restarting the thread on adding template support to OpenSocial.
> Templates will be discussed in detail at the OpenSocial

> summit<http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th...>this

> upcoming Wednesday - please attend and join in the discussions if you
> have an interest in the subject.
>

> Draft proposal is up athttp://groups.google.com/group/opensocial-and-gadgets-spec/web/openso....

> Once we get agreement on the basics we will follow up with a more formal
> spec document.
>
> Some notes on the proposal:
>

> - You can embed template content directly into gadget <Content> sections

> or HTML documents using a <script> tag.

> - OpenSocial tags are prefixed (by convention) with "os:". However the

> templating system supports multiple markup libraries - containers, library
> developers and gadget authors can all define their own tags.

> - Templates can be processed using just a JavaScript include. The

> language also supports server-side processing for performance or security.

> - Expressions in templates can reference data returned from OpenSocial

[Kevin Brown]

We need to tread carefully here. Any localization needs to be supported generically enough to either be complimentary with existing message bundle localization, or to provide a complete replacement for it (I favor the latter).

As for the <if> <else> <repeat> tags, I am somewhat a fan of this
also.  It is true, as Evan said, that sometimes the logic can start
dominating the markup.  I guess it depends on your style.  Maybe we
can have our cake and eat it too?

Same here -- separate tags for conditionals seems a lot more natural for anyone that is used to any other declarative templating mechanism (XSLT, PHP, ASP, JSP, etc.)

[Evan Gilbert]

Hi everyone - we had a good breakout session on templating at the OpenSocial summit last week.

There was general support for the proposal, and we also found a few sections that need to be added:

• Localization. Need to be able to localize content. Mike Austin from hi5 responded earlier on this thread with a few options.
  
• Packaging of templates. Need a way to specify template definitions in a file that can be served and cached separately, both for more complex gadgets and for template libraries.
  
• Specifying styles for templates. Need to clarify how developers will customize style for OpenSocial tags - using custom CSS, named styles, or a combination thereof.
• Defining templates that use JavaScript. Need an overview of how to define templates that use <script> tags or equivalent.
  

Also, we had one open issue that the people in the room agreed on a resolution for:

• Attributes vs. elements for "if" and "repeat" tags. The group agreed that we should have both - we found compelling usage for both cases and didn't see it as confusing to support both options.
  

We will update the proposal soon with resolutions for the above issues, and our goal is still to reach consensus by June 2nd.

Note that there are a number of details we need to resolve beyond the proposal to get to a formal specification. The plan is to get consensus first on the high level approach - many of the details can be resolved in conjunction with building out a working implementation.

Next step (still): everyone gives feedback. If you have would like to give input on how templates will work in OpenSocial, please review the proposal and comment back to the list.

Thanks,
Evan

[Evan Gilbert]

Hi everyone - we had a good breakout session on templating at the OpenSocial summit last week.

There was general support for the proposal, and we also found a few sections that need to be added:

• Localization. Need to be able to localize content. Mike Austin from hi5 responded earlier on this thread with a few options.
  
• Packaging of templates. Need a way to specify template definitions in a file that can be served and cached separately, both for more complex gadgets and for template libraries.
  
• Specifying styles for templates. Need to clarify how developers will customize style for OpenSocial tags - using custom CSS, named styles, or a combination thereof.
• Defining templates that use JavaScript. Need an overview of how to define templates that use <script> tags or equivalent.
  

Also, we had one open issue that the people in the room agreed on a resolution for:

• Attributes vs. elements for "if" and "repeat" tags. The group agreed that we should have both - we found compelling usage for both cases and didn't see it as confusing to support both options.
  

We will update the proposal soon with resolutions for the above issues, and our goal is still to reach consensus by June 2nd.

Note that there are a number of details we need to resolve beyond the proposal to get to a formal specification. The plan is to get consensus first on the high level approach - many of the details can be resolved in conjunction with building out a working implementation.

Next step (still): everyone gives feedback. If you have would like to give input on how templates will work in OpenSocial, please review the proposal and comment back to the list.

Thanks,
Evan

On Tue, May 13, 2008 at 12:55 PM, Kevin Brown <et...@google.com> wrote: