Add opensocial.IdSpec.GroupId enum

[Arne Roomann-Kurrik]

Working through some sample code for 0.8, I realized that it was going to be difficult to reconcile the new IdSpec construct with the current capabilities of the RESTful API.  One such area is the concept of groups. 

The RESTful spec defines the following:

  selector : One of
    * A user-defined local group name to select a group of contacts (a collection)
    * @self to select the person record for guid
    * @all to select all the universal set of contacts (a collection)
    * @friends to select the subset of contacts which are friends (a collection)

The IdSpec JS file states that IdSpec supports the following field:

  <static> object GROUP_ID
      A string representing the group id.

My proposal is to add an opensocial.IdSpec.GroupId enum with values corresponding to the RESTful group selectors, and to modify the description of GROUP_ID to specify that it can accept either a string representing the group or one of the opensocial.IdSpec.GroupId values.

Index: idspec.js
===================================================================
--- idspec.js   (revision 745)
+++ idspec.js   (working copy)
@@ -66,7 +66,8 @@
   USER_ID : 'userId',

   /**
-   * A string representing the group id.
+   * A string representing the group id or one of the
+   * opensocial.IdSpec.GroupId values.
    * @member opensocial.IdSpec.Field
    */
   GROUP_ID : 'groupId',
@@ -108,6 +109,28 @@
 };

 /**
+ * @static
+ * @class
+ * Constant group IDs available when fetching collections of people.
+ *
+ * @name opensocial.IdSpec.GroupId
+ */
+opensocial.IdSpec.GroupId = {
+ /**
+  * @member opensocial.IdSpec.GroupId
+  */
+  SELF : 'SELF',
+ /**
+  * @member opensocial.IdSpec.GroupId
+  */
+  FRIENDS : 'FRIENDS'
+ /**
+  * @member opensocial.IdSpec.GroupId
+  */
+  ALL : 'ALL'
+};
+
+/**
  * Gets the id spec's data that's associated with the specified key.
  *
  * @param {String} key The key to get data for;

[Cassie]

+1 as long as we are clear that not setting the groupId means that it
is equal to "SELF"

[Louis Ryan]

+1!

[Chris Chabot]

As with other threads, i think it would be good to try to finish up this week. This proposal currently has 3 +1 votes. If people want to see this as a part of the 0.8.1 spec revision, please vote for or against in the next few days.

-- Chris

[Arne Roomann-Kurrik]

This is a pretty unsexy change, so I'm just going to bump for a couple more votes. 

~Arne

--
OpenSocial IRC - irc://irc.freenode.net/opensocial

[Chris Chabot]

+1

Anyone else willing to add the last required +1 vote?

[Maxwell Newbould]

+1

[Gonzalo Aune]

+1

G.-

[Cassie]

As Chris has noted that this spec change is approved here:
http://spreadsheets.google.com/pub?key=pPfuwC1QE-ss_uvVOIMrCTA

the patch has been committed to the spec svn repository with some very slight changes.
- it was missing a comma after 'FRIENDS'
- added text that says GroupId defaults to SELF
- added text to the UserId field that mentions its enum (modeling the text after the new GroupId text)

This will get picked up into the opensocial js docs shortly.
Thanks.

- Cassie