nuvola-player-devel team mailing list archive

[Jiří Janoušek <janousek.jiri@xxxxxxxxx>]

Dear friends,

the Nuvola Player JavaScript API 2.0 has recently landed in the trunk
branch[1] and replaced the old APIs 1.0 and 1.01 used in Nuvola Player
1.0.x series. There is also a compatibility layer, so current service
integrations can run without any modifications, but the old API is
considered deprecated and the compatibility layer may be removed in
future releases (maybe  Nuvola Player 2.1.x series). The API reference
can be found at the Nuvola Player Project website[2], Service
integration tutorial[3] has been also updated.

[1] http://bazaar.launchpad.net/~fenryxo/nuvola-player/trunk/revision/369
[2] http://nuvolaplayer.fenryxo.cz/Contribute/Development/JavaScript_API.html
[3] http://nuvolaplayer.fenryxo.cz/Contribute/Development/Service_Integration.html

=== Compatibility ===

All scripts are executed in a 1.x compatibility mode by default. The
compatibility layer[4]

* creates window._Nuvola object
* translates old API calls to the new API counterparts
* disables almost all new API functions
* creates Nuvola.CMD_* constants

In order to disable the compatibility layer, you have to specify
required API version in service's "metadata.conf" - add a line
"api_major = 2"[5].

[4] http://bazaar.launchpad.net/~fenryxo/nuvola-player/trunk/view/369/data/nuvolaplayer/js/compat-1.x.js
[5] example: http://bazaar.launchpad.net/~fenryxo/nuvola-player/trunk/view/369/data/nuvolaplayer/services/googleplay/metadata.conf

=== Improved Sandbox ===

The main Nuvola JavaScript object is no longer globally available,
i.e. "window._Nuvola" is gone. As a result, unprivileged scripts in
the web view don't have access to the Nuvola Player JavaScript API.
The service integration scripts are executed in a special context,
where the "this" keyword refers to the main Nuvola objects. The
recommended way is to use anonymous function[6] to create a closure[7]
for local variables and pass the main API object as an argument:

------------- 8< --------------
/* Anonymous function is used not to pollute environment */
(function(Nuvola){

/* Your code here, do not forget to use `var` to create local variables. */
var message = Nuvola.API_VERSION + "." + Nuvola.API_VERSION_MINOR;
alert(message);

// Immediately call the anonymous function
// with Nuvola JS API main object as an argument.
// (window._Nuvola doesn't work anymore)
})(this);
------------- 8< --------------

[6] http://helephant.com/2008/08/23/javascript-anonymous-functions/
[7] http://lostechies.com/derekgreer/2012/02/17/javascript-closures-explained/

=== API Version Information ===

API version is stored in two variables - Nuvola.API_VERSION contains
major version (2), Nuvola.API_VERSION_MINOR contains minor version
(0).

=== Removed methods ===

The method Nuvola.dataChanged was used to send information about a
song and available actions. It was replaced by two methods:

* Nuvola.updateSong(song, artist, album, album_art, state) updates
information about a song and playback state
* Nuvola.updateAction(name, active) updates information about available actions.

The callback Nuvola.command was replaced by Nuvola.onMessageReceived

=== Service-specific settings ===

Services can store their specific settings to an object Nuvola.config.
Modified configuration object can be saved by a method
Nuvola.saveConfig() or restored by a method Nuvola.reloadConfig().
User can change service-specific settings in the Preferences dialog,
but service integration must provide a script "settings.js"[8] that
creates a form. Call of Nuvola.saveSettings() in the Preferences
dialog will send a message Nuvola.CONFIG_CHANGED to the main web view,
so the script integration.js can apply changes immediately. However,
sometimes it is necessary to reload the main web view to apply
changes, use form.showReloadNotice() in settings.js in that case.

Implementation detail: The Nuvola.config object is serialized to JSON
file $HOME/.config/nuvolaplayer/services/$ID.json

[8] example: http://bazaar.launchpad.net/~fenryxo/nuvola-player/trunk/view/369/data/nuvolaplayer/services/googleplay/settings.js

=== Nuvola Player actions ===

Integration scripts can trigger an action via
Nuvola.triggerAction(name). Basic action names related to playback are
stored in Nuvola.ACTION_* variables. There is also a method
Nuvola.updateAction(name, active) used to enable/disable the action.

=== More helper functions ===

The Nuvola object has more helper functions: makeElement, makeText,
makeClass, makeButton and getSettingsForm. See reference[2] for
details.

=== Form widgets ===

There are some primitive widgets that can be used to create a form for
service-specific settings in the Preferences dialog: Nuvola.Checkbox,
Nuvola.Entry, Nuvola.FormBox, Nuvola.ReloadNotice and
Nuvola.FormMessage. See reference[2] for details.


Best regards,

Jiří Janoušek
Nuvola Player Project Leader