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.

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. For example, the facebook app might return the list of all groups you are a member of if send_to="group wall", and twitter would send a list of all your followers for send_to="direct".

send(user_info, data)

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