Proposal: getFeatureParam() or equivalent

[Evan Gilbert]

gadgets.util.hasFeature(feature) says whether gadgets support a feature.

Proposing adding gadgets.util.getFeatureParam(feature, key) to get a specific property of feature support on a given container. Two known use cases are activity stream title length, maximum people to return from newFetchPeopleRequest()

[Kevin Brown]

On Fri, Apr 18, 2008 at 12:19 PM, Evan Gilbert <uid...@google.com> wrote:

gadgets.util.hasFeature(feature) says whether gadgets support a feature.

Proposing adding gadgets.util.getFeatureParam(feature, key) to get a specific property of feature support on a given container. Two known use cases are activity stream title length, maximum people to return from newFetchPeopleRequest()

This would be confusing because of the existence of getFeatureParameters, which returns the <Param> elements from the <Require> / <Optional> elements. http://code.google.com/apis/gadgets/docs/reference/gadgets.util.html#getFeatureParameters

The idea is good, but the name should probably be something else (getFeatureSetting maybe? I don't know).

--
~Kevin

[Evan Gilbert]

er - getFeatureParameters() may be what is needed. Possibly feature providers / containers can provide default parameters that aren't configurable.

getFeatureParameters('opensocial')['ActivityTemplate.MaxLength'] or similar (with enums).

Evan

[Zhen Wang]

On Fri, Apr 18, 2008 at 6:16 PM, Kevin Brown <et...@google.com> wrote:

Or maybe getFeatureCapabilities?

>
> >
> >
> >
> >
>
>
>
> --
> ~Kevin
>
>
> >
>

[Kevin Brown]

On Fri, Apr 18, 2008 at 6:25 PM, Evan Gilbert <uid...@google.com> wrote:

er - getFeatureParameters() may be what is needed. Possibly feature providers / containers can provide default parameters that aren't configurable.

getFeatureParameters('opensocial')['ActivityTemplate.MaxLength'] or similar (with enums).

This probably works, as long as published features explicitly identify what parameters may be overridden (via <Param>), and anything not identified may not be overridden.

Evan

On Fri, Apr 18, 2008 at 6:16 PM, Kevin Brown <et...@google.com> wrote:

On Fri, Apr 18, 2008 at 12:19 PM, Evan Gilbert <uid...@google.com> wrote:

gadgets.util.hasFeature(feature) says whether gadgets support a feature.

Proposing adding gadgets.util.getFeatureParam(feature, key) to get a specific property of feature support on a given container. Two known use cases are activity stream title length, maximum people to return from newFetchPeopleRequest()

This would be confusing because of the existence of getFeatureParameters, which returns the <Param> elements from the <Require> / <Optional> elements. http://code.google.com/apis/gadgets/docs/reference/gadgets.util.html#getFeatureParameters

The idea is good, but the name should probably be something else (getFeatureSetting maybe? I don't know).

--

~Kevin

--
~Kevin

[Cassie]

Okay, so it looks like the existing method might be good for our needs but we may need some enums if we want to agree on what params can be queried. Do we want enums? And if so, does someone want to suggest an enum set for the opensocial feature?

Thanks.

- Cassie

[Arne Roomann-Kurrik (Google)]

+1 to getFeatureParameters('opensocial')[ENUM]

Here are some enum values (at least functionally, not literally) I'd
like to see:

ActivityTemplate.MaxTitleLength
ActivityTemplate.MaxBodyLength
FetchPeopleRequest.MaxPageSize
ActivityStream.MaxUpdatesPerUserPerDay

~Arne


On Apr 18, 7:05 pm, "Zhen Wang" <wa...@google.com> wrote:

> On Fri, Apr 18, 2008 at 6:16 PM, Kevin Brown <e...@google.com> wrote:
> > On Fri, Apr 18, 2008 at 12:19 PM, Evan Gilbert <uid...@google.com> wrote:
>
> > > gadgets.util.hasFeature(feature) says whether gadgets support a feature.
>
> > > Proposing adding gadgets.util.getFeatureParam(feature, key) to get a
> > specific property of feature support on a given container. Two known use
> > cases are activity stream title length, maximum people to return from
> > newFetchPeopleRequest()
>
> > This would be confusing because of the existence of getFeatureParameters,
> > which returns the <Param> elements from the <Require> / <Optional> elements.

> >http://code.google.com/apis/gadgets/docs/reference/gadgets.util.html#...

[Kevin Brown]

I don't really care for enums in javascript (and we've already proven a few times that they're not flexible enough for opensocial in general between the mess with gadgets.views and the proliferation of dozens of Person fields), but those property names seem pretty good to me as a starting point.

[Cassie]

Kevin - we've also proven that they work really well with person.field and the other models, all the datarequest ones, the responseitem.error etc etc. One failure does not mean that enums are a bad idea, it just means that nobody really knows how we want to treat views :)

+ 1 on this querying capability.

As for Arne's enums, those sound good to me. Also remember that as usual for opensocial we should add a corresponding "supportsField" type. With the addition of a supportsField('featureParameter', <feature name>) then containers are free to add their own enums in their own namespace and choose to not support any feature types that don't make sense (ie if they don't support activities or something)

Thanks.

- Cassie

[Graham Spencer]

+1 on querying, and Arne's enums are fine.

--g

[Paul]

+1 to capability

-1 to method of using creating a function in gadgets namespace that
would take arguments specific to opensocial namespace. -1 to creation
of new function at all. There are all sorts of validation rules that
may be present on different fields...so I'd rather see them defined
(with consistency) on the Field objects directly.

why not simply: opensocial.Activity.Field.TITLE.maxLength ?

~Paul

[et...@google.com]

On 4/25/08, Paul <pjwa...@gmail.com> wrote:
>
> +1 to capability
>
> -1 to method of using creating a function in gadgets namespace that
> would take arguments specific to opensocial namespace.

We already do this in other places anyway, so it's probably irrelevant
now. It would just be key/ value pairs anyway.

[David Glazer]

+0 as a vote -- this is mostly a code style question, so I'll defer to active coders.

Re "creating a function in gadgets namespace that would take arguments specific to opensocial namespace" -- that doesn't bother me as proposed, since it's a generic function that just takes the feature name as an argument, and therefore would work with values in *any* namespace, not just "opensocial".  If that's done as a function at all, the gadgets namespace seems appropriate.

[Cassie]

Paul - to be more clear, this proposal does not involve creating any new methods. It is using an existing method and simply defining some enums and common ways to implement the method.

As for defining enums directly on the object, using the getFeatureParams simply puts all of these things in one easy to access place. This makes it easier to document for developers and easier to implement on the js side. So I guess my vote is for the original proposal.

Will other people chime in with more opinions here?
Thanks!

- Cassie

[Cassie]

This thread does not seem to be getting enough positive consensus so I would like to close this issue for 0.8. Don't worry, we can still continue the discussion and pick this up for 0.9.

Keep in mind that this functionality can also be implemented independently with container extensions.
Thanks!

- Cassie

[Scott Seely]

Would it make sense to add this functionality to the opensocial.Environment instead of a function called getFeatureParameters? I’d also be happy with both, but make the opensocial.Environment a ‘convenience’ mechanism to call the getFeatureParameters method.

 

It seems that we are really asking the container for limits on sizes of various things. Besides Arne’s proposal, could we do something like this:

 

Proposal:

Add a new Field to opensocial.Environment named Limits.

 

Field Summary:

<static> object APPDATA_MAX: A number indicating the total space the container makes available for appData.

<static> object APPDATA_REMAINING: A number indicating how much appData space is left for the current user/application.

<static> object MAX_NETWORKDISTANCE: A number indicating the maximum network distance supported by the container.

<static> object PERSON_MAX_RESULTS_COUNT: A number indicating the maximum number of opensocial.Person objects that can be retrieved in a collection.

<static> object PERSON_DEFAULT_RESULTS_COUNT: A number indicating the default number of opensocial.Person objects retrieved in a collection.

<static> object ACTIVITY_MAX_RESULTS_COUNT: A number indicating the maximum number of opensocial.Activity objects that can be retrieved in a collection.

<static> object ACTIVITY _DEFAULT_RESULTS_COUNT: A number indicating the default number of opensocial.Activity objects retrieved in a collection.

<static> object COLLECTION_MAX_RESULTS_COUNT: A number indicating the maximum number of opensocial objects that can be retrieved in a collection that is not specifically named in the opensocial.Environment.

<static> object COLLECTION_DEFAULT_RESULTS_COUNT: A number indicating the default number of opensocial objects retrieved in a collection that is not specifically named.

… (others as we come up with them)

 

 

 

 

Scott Seely

architect

email  sse...@myspace.com

 

 

---------- Forwarded message ----------

From: "Arne Roomann-Kurrik (Google)" <api.kur...@google.com>

Date: Apr 24, 3:58 pm

Subject: Proposal: getFeatureParam() or equivalent

To: OpenSocial and Gadgets Specification Discussion

[Arne Roomann-Kurrik]

I like this approach as well, and feel that the enums here make a lot of sense.  I would add a couple more around quota limits (activities/messages/app shares) with corresponding _MAX and _REMAINING values, but I wouldn't want to remove any of the ones you listed.

Can you share code indicating how you see developers retrieving the values of these fields if you don't like getFeatureParameters? 

~Arne

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

[Scott Seely]

My comments around getFeatureParameters are largely around the notion of looking for less verbose syntax, nothing more.

 

Anyhow, you asked for an example.

 

var maxFriendsPerGet = opensocial.Environment.Limits.PersonMaxResultsCount;

 

This is more terse than

 

var maxFriendsPerGet = gadgets.util.getFeatureParameters('opensocial')[opensocial.Environment.Limits.PERSON_MAX_RESULTS_COUNT];

 

and given the discussion around enums earlier this week, we could argue that the previous line is really just:

 

var maxFriendsPerGet = gadgets.util.getFeatureParameters('opensocial')['PERSON_MAX_RESULTS_COUNT'];

 

At the end of the day, I care more about getting the limits discoverability into the spec. Also, consistent syntax is important. If this is something with broad applicability to other gadgets features, then I probably prefer something like the gadgets.util.getFeatureParameters syntax. That syntax is just an interpretation of what I think was proposed in April—correct me if this is wrong.

[Kevin Brown]

On Wed, Aug 27, 2008 at 2:51 PM, Scott Seely <SSe...@myspace.com> wrote:

My comments around getFeatureParameters are largely around the notion of looking for less verbose syntax, nothing more.

 

Anyhow, you asked for an example.

 

var maxFriendsPerGet = opensocial.Environment.Limits.PersonMaxResultsCount;

 

This is more terse than

 

var maxFriendsPerGet = gadgets.util.getFeatureParameters('opensocial')[opensocial.Environment.Limits.PERSON_MAX_RESULTS_COUNT];

 

and given the discussion around enums earlier this week, we could argue that the previous line is really just:

 

var maxFriendsPerGet = gadgets.util.getFeatureParameters('opensocial')['PERSON_MAX_RESULTS_COUNT'];

I would argue against adding more capability querying mechanisms in favor of refining (and/or eliminating) the existing ones. This gets very confusing for developers if they have to query one API to determine that something is supported, another API to determine the maximum value for something, and then the resulting objects to determine what capabilities that they have.

[Arne Roomann-Kurrik]

On Wed, Aug 27, 2008 at 3:09 PM, Kevin Brown <et...@google.com> wrote:

I would argue against adding more capability querying mechanisms in favor of refining (and/or eliminating) the existing ones. This gets very confusing for developers if they have to query one API to determine that something is supported, another API to determine the maximum value for something, and then the resulting objects to determine what capabilities that they have.

I completely agree - every time I want to do a quick capabilities query, I wind up hunting through the OpenSocial docs looking for the correct method to use.  

Any suggestions as to what combining opensocial.Environment.supportsField(), gadgets.util.hasFeature(), opensocial.hasPermission(), and gadgets.util.getFeatureParams() might look like?

~Arne

[Kevin Brown]

I think the long term solution here is a proper merger of the gadgets and opensocial packages (they're so intertwined now, I don't see how you could separate them).

There is definitely a difference between hasPermission and the capability querying mechanisms, though.
 

[Arne Roomann-Kurrik]

hasPermission only works on VIEWER though.  If we can query for APPDATA_REMAINING, then it makes sense to me to eliminate the entire hasPermission call and add a field like VIEWER_AVAILABLE that an application could query on.

 

~Arne

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