Labs/F1/Modularity/WebMod-API

F1 defines the following javascript postMessage/jschannel based APIs.

For simplicity, the functions are described as if they are regular blocking functions (ie, they specify a return value). However, as they are implemented using jschannels, the actual implementation will be that the caller obtains the "return value" via jschannel 'success' callback.

Authentication

Authentication is all performed by the WMF library - see Labs/F1/Modularity#Authentication for details.

Sharing

To be implemented by the app (ie, APIs called by F1)

link.send.getShareCharacteristics()

Get enough metadata about the application so the necessary UI for the service can be dynamically built. This is similar to the current F1 "services" global, and allows F1 to offer "send to wall" for facebook versus "send to my contacts" for linkedin.

The information returned by this method is static and must not depend on the logged-in user, if any. IOW, this method may be called before a user is logged in and may not be called again after login/logout events.

 NOTE: As all the information here is relatively static, there was some 
 discussion about putting them directly in the app manifest.  However, 
 in the interests of keeping the manifest small and not requiring regular 
 refreshes of the manifest to get new information, it is currently defined 
 as a method.  This may want to be re-evaluated if these calls add to a 
 perception of poor performance.

The result is an object with the following fields (mostly taken from the current F1 implementation)

name

The (localized) name of the service as displayed to the user. If not specified the service name as defined in the manifest will be used. The name may be rendered as a link to the 'serviceUrl'.

serviceUrl; A link to the 'home page' for this particular service. If not specified the application's origin (as defined by the app manifest) will be used.

subject

Whether the app supports a 'subject' field.

shareTypes

A list of ways an item can be shared with this service. If the service supports direct messaging, then this must be reflected in shareTypes. Each element in the list may have fields type (an identifier passed back to the service if this item is selected), label (what is shown to the user) and toLabel (the label for the 'to' field - if not specified, the 'to' field is hidden)

textLimit

The maximum number of characters allowed. If specified, a counter will be displayed and the limit will be enforced.

Note the following fields from the current F1 implementation have been removed (mainly as they can be derived from the above fields.)

shorten

A boolean indicating if links must be shortened, but this can be derived on a per-share basis based on the specified textLimit and the amount of text currently entered.

icon

The webapp manifest already defines the icons.

features/direct

Indicated if direct messaging is supported, but this can be reflected in the 'shareTypes' field and need not have its own flag.

revokeUrl

This URL is (or may be) specific to the currently logged in user,

so is reflected in the user-info field.

accountLink

As above.

signOutUrl

The service logout() method will be used.

forceLogin

Why is this needed in F1 and why can't the service work this out itself?

overlays

This referred to F1 implementation details so can't be supported generically. If F1 still chooses to use overlays for selected services, these will need to be defined internally and not reflected here.

features/medium

Seems to be a hangover from an old F1 impl?

shareTypes[].showTo

Can be derived from whether the 'toLabel' field exists.

link.send.getAutocompleteEntries(user_info, send_to, to_prefix, callback)

Get all the autocomplete entries for the "to" field based on the current setting of the "send to" field for the specified user and the text currently entered in the 'to' field. For example, the facebook app might return the (filtered) list of all groups you are a member of if send_to="group wall", and twitter would send a (filtered) list of all your followers for send_to="direct".

There is no concept of "paging" the results as it seem unlikely users will actively "page" an auto-complete list - instead they should focus on providing a shorter list of relevant results.

The size of the returned list is not constrained by this method, but WebMods will be encouraged to keep the result list to a reasonable (but relevant) size, or risk offering a poor UX for users of that service.

If the above size restrictions are a problem, we probably need to add the concept of a "chooser ui" which is different from the auto-complete UI?

 NOTE: This method exists as a way to avoid introducing a full-blown Contacts
 concept and the complexity that would involve.  However, a key downside is 
 that cross-service sharing of this information becomes impossible - eg, if 2
 different services provide email addresses, nothing in this spec allows F1
 to notice that fact and reuse the email addresses for all services which
 support sending emails.

 NOTE: This might need fine-tuning for performance reasons - currently F1 uses
 a cache of contacts, but the technique described here probably needs one
 call per character typed.  I guess we can still make the caching (or lack
 thereof) the responsibility of the service itself (so while we may still make
 one call per character typed, that call need not result in network activity)

send(user_info, data)

Send an item as described by "data" - ie, perform the actual share.