Detailed feedback thread: 5-opensocial_0_8_JS.html

[Dan Peterson]

As per below, please use this thread to discuss potential improvements to the OpenSocial JS Doc (v0.8):
http://opensocial-and-gadgets-spec.googlegroups.com/web/5-opensocial_0_8_JS.html

Much appreciated,
-Dan

---------- Forwarded message ----------
From: Dan Peterson <dpet...@google.com>
Date: Fri, May 9, 2008 at 6:27 PM
Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related spec updates
To: opensocial-and-gadgets-spec <opensocial-an...@googlegroups.com>


Hi folks,

As discussed last week, the full draft of OpenSocial v0.8 specification is ready for your review. This draft specification includes updates to existing specs, inclusion of the RESTful spec, release notes, and detailed JavaScript doc (JSDoc). The intent was to clearly capture all of the 40+ changes/additions that we have developed on this mailing list since version 0.7 of the spec (as tracked in http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). Let's use the next week or two to make improvements to these docs and then we can lock down 0.8.

You can find all 6 of these documents uploaded into the "Files" section of this Google Group: http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name

The draft documents published are (please note that some of the links in the files might not work as this is only a staged copy):

• 1 - OpenSocial 0.8 Release Notes
• 2 - OpenSocial 0.8 Specification
• 3 - OpenSocial 0.8 RESTful API Specification
• 4 - gadgets Specification
• Canonical gadgets XSD
• Extended gadgets XSD
• gadgets Message Bundle XSD
  
• 5 - opensocial.* 0.8 JS doc
• 6 - gadgets.* JS doc

I have conveniently numbered these documents so it is easier for you to walk through them in a clear order. In addition, documents 1 through 4 have their additions/updates highlighted for ease of reference. To better organize detailed feedback for each document, I will now start a thread for each of the 6 documents. Please be sure to direct your feedback to the appropriate thread.

Also, as a reminder, this coming Wednesday, May 15, we'll be holding an OpenSocial Summit in Mountain View, California. This event is an ideal opportunity to discuss this draft specification, propose ideas for future iterations, and learn about the latest happenings in the community -- as well as get to know each other in person.

You can learn more about the event at: http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
(RSVP is here: http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )

Looking forward to your feedback (in the appropriate thread ;),
-Dan

[Louis Ryan]

getContainerUrlTemplate - Doc does not match agreement to use IETF proposal for templates.

Heres what Bob Evans and I worked on...

/**
 * Returns a string URI template conforming to the
 * <a href=http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html">
 * W3C spec draft</a> with variables for substitution.
 * 

 * The four supported variables are:
 * - name: the name or id of the application
 * - owner: the id of the owner of the page
 * - path: an array of path steps
 * - params: associative array or array [param1,value1,param2,value2,...]
 *

 * Simple examples of URL template strings:
 * http://container.com/{-list|/|name,owner,path}?{-join|&|params}
 * http://container.com/apps/{name}/{owner}{-prefix|/|path}{-opt|?os_|params}{-join|&os_|params}
 *
 * Given the params
 * {
 *  name : 'Wilma',
 *  owner : 'Betty',
 *  path : ['dino','car'],
 *  params = { a : 'Barney', b : 'Fred'}
 * }
 *
 * The above two examples yield
 * http://container.com/Wilma/Betty/dino/car?a=Barney&b=Fred
 * http://container.com/apps/Wilma/Betty/dino/car?os_a=Barney&os_b=Fred
 *
 * @return {String} A template which can be used to construct urls for
 *     navigating throughout this container.
 * @member opensocial
 */
opensocial.getContainerUrlTemplate = function() {};

[Robert Evans]

I also mentioned this on thread 6 feedback, but it seems to me that the opensocial.getContainerUrlTemplate, and the new opensocial.bindUrlTemplate, both belong in gadgets.views next to requestNavigateTo, which is what they are designed to support.

If agreed, then I'lll make the change.

Bob

[Dan Peterson]

Thanks, looks like this is coming to closure on the original thread about these proposals.

-Dan