The plugin object

When a plugin is loaded it will be so with an associated plugin object. The object can not be altered from the script (IE, no new properties can be defined on the object).

Properties

url

URL to the plugin's ECMAScript file

path

Path to the plugin root. This should be used to form fully qualified URLs to plugin resources (icons, etc)

URIRouting

If set to 'true' the plugin will participate in URI routing. IE. the handlers registered via plugin.addURI() will be invoked when a URI is opened that matches the registered regexp. The default value is 'true'. This value can be modified by the plugin itself (Usually via a setting)

search

If set to true the plugin will participate in search requests. In other words the handlers registered via plugin.addSearcher() will be invoked on search requests. The default value is true. This value can be modified by the plugin itself (Usually via a setting)

Functions

forceUnload()

Forces plugin to unload.

addURI(String Regexp, Function Handler)

Add a function for handling a URI matched by a regexp. This is a central function for adding browse pages that a user can navigate to.

  • Regexp - Regular expression matching the URI
  • Handler - Function to be invoked when the URI is opened

The Handler is called with one or more arguments. The first argument is always the page object. The second and further arguments are sub-strings as matched by the regexp

plugin.addURI("testplugin:foo:(.*)", function(page, arg) {
  showtime.print("The argument is " + arg);
})

If the testplugin:foo:bar URI is opened in Movian this will print The argument is bar in the console

addSearcher(String Title, String Icon, Function Handler)

Add a searcher handler when universal search is used.

  • Title - Title of the searcher.
  • Icon - Image to show that identifies this searcher in the search results.
  • Handler - Function to be invoked when the searcher is called.

Note: This function should specify the number of search entries with page.entries in order to this searcher being displayed.

addHTTPAuth(String Regexp, Function Handler)

Add a handler for authenticating HTTP requests.

Important: This will modify ALL HTTP requests. Even those that does not originate directly from the plugin. The reason for this is that some servers would require special headers when loading images, subtitles, video, etc which are not directly loaded from the plugin. Please keep this in mind and do not add too greedy matches.

Plugins may add handlers for dealing with authentications for various URLs. This is typically used for OAuth based streaming services and such. Even though the browsing and searching of content is handled in the plugin the actual streaming of Audio / Video never passes through the plugin itself. To make it possible to authenticate requests which are not touched by the plugins (and to ease authentication of requests from within the plugin itself) the plugin can register HTTPAuth handlers.

  • Regexp - Regular expression matching the URIs for which to handle authentication.
  • Handler - Function invoked when requests needs to be authenticated.

The handler is invoked with one argument 'A authreq object' and the plugin should return true to indicate that the authentication was successful, false otherwise.

Example that modifies all HTTP requests that goes to *.example.com to have User-Agent set to QuickTime:

plugin.addHTTPAuth("http://.*\\.example\\.com", function(req) {
  req.setHeader("User-Agent", "QuickTime");
})

The authreq object have these methods:

oauthToken(String ConsumerKey, String ConsumerSecret, String UserToken, String UserSecret)

If you need to use OAuth 1.0 you know what those are for and how to get them

rawAuth(String data)

Just send raw data as the HTTP Authentication Header. This can be used for a variety of things, including OAuth 2.0

setHeader(String header, String value)

Sets a HTTP header to the given value

setCookie(String name, String value)

Sets a cookie to the given value.

Added in Movian 4.3.576

createService(String Title, String URL, String Type, Boolean Enabled, String Icon)

Create a service (that will appear on the home screen) and return an Object representing the service.
The created service is resource-tracked and will be removed when the plugin is unloaded (or reloaded)

  • Title - Display name of the service
  • URL - Initial route of the service
  • Type . Service type, can be used for grouping the service. This should be one of the following:

video
music
tv
image
other

  • Enabled - Sets if service should be enabled. If true, the service may be used.
  • Icon - Image that identifies the service.

createSettings(String Title, String IconURL, String Description)

Create a setting group (that will appear in the settings page) and return a settings object.
The created settings group is resource-tracked and will be removed when the plugin is unloaded (or reloaded). The object has a destroy method that can be used to destroy the object.

  • Title - Display name of the service
  • IconURL - URL Path to icon
  • Description - Long description of the settings

createStore(String ID, [Boolean PerUser])

Creates an object that will be persisted on disk.
The store object is not resource tracked and explicitly destroyed like most other plugin related objects. Rather it is finalized when the Javascript garbage collector will destroy it.
Available from 3.1.162

  • ID - Identifies the object. Each plugin can create multiple stores, each with a different ID.
  • PerUser - When Movian will support switching between multiple identities this will indicate that the store should be unique per user. This is not something that is currently supported.

getAuthCredentials(String Source, String Reason, Boolean QueryUser, [String ID], [Boolean ForceTemporary])

Ask the user for authentication credentials.

  • Source - Display name of the service/entity requiring authentication. This should be rather short but should still identify the service uniquely. IE, it should inform the user from what the popup originates.
  • Reason - Reason for asking for authentication credentials. This can be things like "Service requires authentication" or in case the user tries a username/password but it fails, it should be something like: "Invalid Password". IE. it should inform the user why the request popped up.
  • QueryUser - If set to true the user will be queried for input. If this is false Movian will only look in the keyring for previously entered credentials.
  • ID - Extra ID for storing the credentials in the keyring. This will be appended to the plugin's own ID. If you only have one authentication point to worry about you don't need to supply this.
  • ForceTemporary - Do not allow Movian to store the credentials on disk. This also removes the 'remember me' option from the popup. Some online services, when using token based authentication, allows Movian to get a token that can be renewed to retain authentication against the service. For these type of services it makes no sense to store the Username/Password in clear text.

getDescriptor()

Parses each element of plugin.json to plugin object.

var plugin_info = plugin.getDescriptor();
var PREFIX = plugin_info.id;

cachePut(String Name, String Key, Object Values, Int Expire)

Stores an object in Cache (JSON encoded), expiring seconds after the colocation in cache (value given by Expire).

Warning! You shouldn't cachePut JSON encoded stuff becuse in cacheGet you will get back unpredictable(corrupted) content.

Example:

// store json object in cache for 24 hours
plugin.cachePut("ItemStash", "ItemKey1", {
   title: 'Item title',
   thumb: 'http://localhost/thumb.jpg'
}, 86400);

cacheGet(String Name, String Key)

Parses the object in Cache with key equal to Key and name of Cache equal to Name.

Example:

var o = plugin.cacheGet("ItemStash", "ItemKey1");

onEvent(String Event, Function Handler)

Receive global events.
Available from 3.5.6

  • Event - Name of the event to listen.
  • Handler - Function to be executed when the event is called.

subscribe(String Key, Function Handler)

Subscribe to a key's changes.

  • Key - Key of variable to subscribe.
  • Handler - Function invoked when the variable subscribed changes.

addSubtitleProvider(Function Handler)

Function that is called when a user enters a video and if the current plugin is a subtitle provider.

  • Handler - Function invoked when the plugin is asked for subtitles.

copyFile(String URL, String desiredName)

Downloads file(html or binary) from URL to .cache/showtime/plugins/PluginName/desiredName