3. Plug-in functions

The framework includes several functions providing a layer of abstraction between the developer and the core Python environment. These functions eliminate a great deal of boilerplate code from plug-ins, allowing the developer to focus on the task at hand, not how it should be performed.

3.1. Framework functions

Framework functions are functions with predefined names that are called automatically by the framework when certain events occur. Most of the framework functions are optional; the only required function is Start(). Other functions can be implemented at the developer’s discretion, depending on the functionality they wish to provide in a plug-in.

The following framework functions can be implemented by the developer:

Start()

This function is called during a plug-in’s initialization routine. By this point, all pre-start checks have completed and all framework modules will be available. The function should be used to set up the plug-in’s environment by adding view groups (using Plugin.AddViewGroup(), setting default attributes (see Objects for more details) and performing user login if necessary.

Note

This function is mandatory.

CreatePrefs()

This function is called when setting up a plug-in’s user preferences, either during a plug-in’s initialization routine or after a reset of the preferences. If implemented, this function will be called before the Start() function. The developer should add a call to Prefs.Add() for each preference they wish to include.

Note

Preferences can also be set up using the DefaultPrefs.json file. See Prefs and Bundles for more details.

ValidatePrefs()

This function is called when the user changes the plug-in’s preferences in Plex’s user interface. The developer can use this function to perform additional actions after preferences have been provided (e.g. logging in to a website) or to alert the user if they have made a mistake by returning a MessageContainer object.

SetRating(key, rating)

New in version Plex: 0.8.3

This function is is called when a user rates an item using the context menu.

Parameters:

• key – unique key which helps the plugin identify which item is being rated
• rating – rating from 1-10 which the user has selected

In order for your plugin to indicate that an item may be rated, the ratingKey will need to be passed in to the DirectoryItem, PopupDirectoryItem, VideoItem, WebVideoItem, RTMPVideoItem, WindowsMediaVideoItem, PhotoItem, or TrackItem. In other words, if the ratingKey is not passed, the item may not be rated.

The ratingKey is an arbitrary string but note that it should be unique and that it will be passed back to the SetRating() function so that you can identify which item is being rated.

example excerpt from a plugin:

def MyMenu(sender):
   #...
   dir.Append(
     VideoItem(
         theUrl,
         # ... other params ...
         ratingKey=theUrl # This item can be rated and will be passed theUrl
     )
   )
   #...

def SetRating(key,rating):
   # when a user has selected a rating, it will be passed
   # the key and the rating

   #... plugin specific handling of rating if needed ...

   return MessageContainer("Rating Success","The video %s was rated as %s" % (key,rating))

CreateDict()

This function is called when creating the plug-in’s dictionary, either during a plug-in’s initialization routine or after a reset of the dictionary. The developer should add a series of calls to Dict.Set() to set up default values within the dictionary.

Note

The dictionary can also be set up using the DefaultDict.json file. See Dict and Bundles for more details.

CreateDatabase()

This function is called when creating the plug-in’s database. The developer should add a series of calls to Database.Exec() containing SQL statements that create all required tables and insert any default data.

Note

The database can also be created using the DefaultDatabase.sql file. See Bundles for more details.

Note

In order to keep the memory footprint of plug-ins low, the SQLite module is not loaded by default. The database will not be created when a plug-in first starts; it is created in response to the first call to Database.Exec().

3.2. Handler functions

Handler functions are used to give plug-ins a “starting point” within Plex’s user interface by assigning the function a path prefix. They accept no arguments. Each handler responds when the user selects a specific item in the Videos, Music, Pictures or Applications sections in Plex. Multiple handlers can be registered.

The icon & artwork used within Plex are loaded from the Resources directory. The default filenames are icon-default.png and art-default.png respectively.

To assign a prefix to a function, use the @handler decorator:

@handler("/video/myplugin", "My Plug-in")
def MainMenu():

  """ Function code here """

This will assign the prefix /video/myplugin to the Mainmenu() function, and add an icon labelled “My Plug-in” to the Videos section in Plex. The @handler decorator also accepts the two keyword arguments art and thumb. These allow the developer to override the default icon & artwork filenames.

Note

Prefixes should always be added under one of the four main root directories: /video, /music, /photos or /applications. These correspond to the main areas of Plex’s user interface.

3.3. Callback functions

Using Function objects, functions can be assigned to items returned to Plex. These functions are called when the item is selected in Plex’s user interface.

Callback functions should accept at least one argument: sender. This argument will contain an ItemInfoRecord object, including information about the previous window state and the item that initiated the function call. Additional arguments can easily be defined.

This is an example of a callback function definition:

def CallbackFunction(sender, arg):
  d = MediaContainer(title1 = sender.title2, title2 = arg)

  """ Add some items """

  return d

To assign a callback function to an item, a Function object should be created:

Function(DirectoryItem(CallbackFunction, title = "Item title"), arg = "Argument")

This code would wrap the previously defined CallbackFunction() in a DirectoryItem object. This object could then be added to a MediaContainer and returned to Plex. It would behave like any other directory within Plex, but would call the function when selected, passing the provided arg argument. See Function for more information.

Note

It is the responsibility of the developer to ensure that functions return an appropriate response for the selected item. For example, functions responding to a call from a VideoItem should only return or redirect to appropriate video data.

3.4. Data functions

Data functions are similar to callback functions, but they are used to populate attributes of items instead of in response to a selection. Using data functions, a plug-in can provide thumbnails and artwork directly rather than returning a resource file or URL. Data functions accept any number of optional arguments (like callback functions) and should return a DataObject containing the appropriate image data.

This is an example of a data function definition:

def DataFunction():
  return DataObject(data = Data.Load("AnImage"), contentType="image/jpeg")

The function can then be assigned to an attribute:

DirectoryItem(path, title, thumb = Function(DataFunction))