6. Objects

The framework provides a number of classes that enable the developer to easily build a content tree ready to be returned to Plex. All these classes inherit from one common Object class. The provided classes are very flexible, yet simple to use.

Each class represents a different kind of object, like a directory, photo or video. These objects have a number of attributes which define how they are displayed and what content they are linked to. There are three ways of setting an object’s attributes. They can be set when creating the object:

item = DirectoryItem(title="This is the title")

This would create a new object named item, and set the title attribute.

The second way of setting attributes is to modify an object that already exists:

item.subtitle = "This is the subtitle"

This would set the subtitle attribute of the item object created in the first example.

The final way of assigning attributes to objects is to set them directly on the class itself:

DirectoryItem.thumb = "http://www.mysite.com/thumbnail.png"

After setting the attribute on the class, all objects created after that point will inherit the attribute. In the example above, every new DirectoryItem object would have the thumb attribute set by default. Default attributes can be overridden in the constructor or after creating an object.

6.1. Container objects

Containers are objects that should be sent to Plex in response to a directory. There are two container classes available:

class MediaContainer(art=None, viewGroup=None, title1=None, title2=None, noHistory=False, replaceParent=False, noCache=False)

The media container class is one of the most important object types available. This is the object that will contain all the other objects to send back to Plex. To display a list of items in Plex, the developer will need to create a new MediaContainer instance, populate it, and return it.

Media containers respond to the following attributes:

Parameters:

• art (str) – The full path to the artwork to use when displaying the container
• viewGroup (str) – The name of the view group to use when displaying the container, previously defined by Plugin.AddViewGroup()
• title1 (str) – The first window title to display
• title2 (str) – The second window title to display

The MediaContainer class behaves like a standard Python list type. This means that standard Python syntax can be used to interact with them. For example, to find the number of items inside a container:

itemCount = len(mediaContainer)

Specific items within a container can also be accessed:

# Returns the third item in the container (the index starts at 0)
item1 = mediaContainer[2]

# Returns the last item in the container (negative indexes count back from the end)
item2 = mediaContainer[-1]

In addition to the standard syntax, there are a number of methods you can use to manipulate media containers:

Append(obj)

Appends a given object to the container. This object should be either a Function or a type of media item.

Parameter:obj – An object to append to the container

Count(obj)

Counts the number of times an object appears inside the media container.

Parameter:obj – The object to count Returns:The number of times the object appears Return type:int

Index(obj)

Finds the position of a given object in the container.

Parameter:obj – The object to find Returns:The position of the object Return type:int

Extend(container)

Appends all the items in the given container to the current container.

Parameter:container – The container including the items to append

Insert(i, obj)

Inserts an object at a given position in the container.

Parameters:

• i (int) – The position at which to insert the object
• obj – The object to insert

Pop(i)

Removes the object at the given position in the container and returns it.

Parameter:i (int) – The position of the object to remove Returns:The object at the given position

Remove(obj)

Removes the given object from the container.

Parameter:obj – The object to remove

Reverse()

Reverses the objects in the container. This can be useful when manipulating the objects within the container, as it is much quicker to add or remove items at the end of a list than the beginning, and the Reverse() function is very fast.

Sort(attr)

Sorts the items in a container based on the given attribute, for example title.

Parameter:attr (str) – The attribute to use when sorting

class MessageContainer(header, message)

The MessageContainer class displays a simple message dialog to the user. It is mainly used to respond to a directory request when no items are available (e.g. after a search query).

Parameters:

• header (str) – The header to display in the message dialog
• message (str) – The body text to display in the message dialog

The most common use of MessageContainer is as follows:

d = MediaContainer()

""" Try to populate the container with items """

if len(d) == 0: return MessageContainer("No items available", "There are no items available.")

return d

6.2. Media item objects

class DirectoryItem(key, title, subtitle=None, summary=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The DirectoryItem class provides a list item that links to another directory.

Parameters:

• key – The directory to navigate to when selecting this item. This should be a path string, or a callback function when used in conjunction with a Function object.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class PopupDirectoryItem(key, title, subtitle=None, summary=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The PopupDirectoryItem class behaves in a similar way to the DirectoryItem class, but the directory it links to will be displayed as a popup menu in the user interface.

Parameters:

• key – The directory to display when selecting this item. This should be a path string, or a callback function when used in conjunction with a Function object.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class InputDirectoryItem(key, title, subtitle=None, summary=None, thumb=None, art=None)

The InputDirectoryItem class is used to display the on-screen keyboard and retrieve user input before navigating to a directory. Instances of this class should be used in conjunction with a Function object. In addition to the standard sender argument, callback functions used with InputDirectoryItem objects should also accept a query argument.

Parameters:

• key – The directory to display when selecting this item. This should be a callback function and used in conjunction with a Function object.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.

class VideoItem(key, title, subtitle=None, summary=None, duration=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The VideoItem class provides a list item that links to a video file.

Parameters:

• key – The video to play when selecting this item. This should be a path string, or a callback function when used in conjunction with a Function object.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• duration (int) – The duration of the video, if known (in milliseconds)
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class WebVideoItem(url, subtitle=None, summary=None, duration=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The WebVideoItem class provides a list item that links to a web-based file (a Flash or Silverlight player embedded in a web page). A site configuration that handles the provided URL must be available.

TODO: Link to site config info

Parameters:

• url – The URL of the page containing a video to play when selecting this item.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• duration (int) – The duration of the video, if known (in milliseconds)
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class RTMPVideoItem(url, clip=None, width=640, height=480, live=False, title=None, subtitle=None, summary=None, duration=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The RTMPVideoItem class provides a list item that links to a RTMP video stream.

Parameters:

• url – The URL of the RTMP player.
• clip – The path of the clip to play.
• width – The width of the video.
• height – The height of the video.
• live (boolean) – Specifies whether the item links to a live stream or not.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• duration (int) – The duration of the video, if known (in milliseconds)
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class WindowsMediaVideoItem(url, width=720, height=576, title=None, subtitle=None, summary=None, duration=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The WindowsMediaVideoItem class provides a list item that links to a Windows Media video stream.

Parameters:

• url – The URL of the Windows Media stream.
• width – The width of the video.
• height – The height of the video.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• duration (int) – The duration of the video, if known (in milliseconds)
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class PhotoItem(key, title, subtitle=None, summary=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The PhotoItem class provides a list item that links to an image file.

Parameters:

• key – The image to display when selecting this item. This should be a path string, or a callback function when used in conjunction with a Function object.
• title – The title to display in user interface.
• subtitle – The subtitle to display in the user interface when the item is selected.
• summary – The summary to display in the user interface when the item is selected.
• duration (int) – The duration of the video, if known (in milliseconds)
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class TrackItem(key, title, artist=None, album=None, index=None, rating=None, duration=None, size=None, thumb=None, art=None, ratingKey=None)

New in version Plex: 0.8.3 The ratingKey parameter.

The TrackItem class provides a list item that links to an audio file.

Parameters:

• key – The audio file to play when selecting this item. This should be a path string, or a callback function when used in conjunction with a Function object.
• title – The title to display in user interface.
• artist – The artist to display in the user interface.
• album – The album name to display in the user interface.
• index – The position of the track in the album.
• rating – The rating to display in the user interface.
• duration (int) – The duration of the track, if known (in milliseconds)
• size – TODO
• thumb – The thumbnail image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• art – The artwork image to display in the user interface when the item is selected. This should be the full path to an image, an exposed resource, or a data function when used in conjunction with a Function object.
• ratingKey – The unique key used to identify the item being rated for the SetRating() function

class PrefsItem(title=None, subtitle=None, summary=None, thumb=None)

The PrefsItem class represents a link to the plug-in’s preferences dialog. No key is required for this object; it simply needs to be added to the content tree.

Parameters:

• title (str) – The title to display in the user interface
• subtitle (str) – The subtitle to display in the user interface
• summary (str) – The summary to display in the user interface
• thumb (str) – The path to a thumbnail to display in the user interface

6.3. Function objects

class Function(obj, ext=None, **kwargs)

TODO: Function information

6.4. Other objects

class Redirect(url)

The Redirect class redirects Plex to a different URL. This is useful for resolving the final path of an item (e.g. a photo or video) when adding it directly to a MediaContainer is complicated or takes a long time to compute.

Parameter:url (str) – The URL to return to Plex

Note

It is the responsibility of the developer to ensure that an appropriate URL is returned to Plex. For example, a request for a VideoItem should not respond with a music or photo URL.

Note

Redirects can currently only be used to redirect to a URL using the same protocol (i.e. HTTP). This problem will be resolved in a future version of the Plex client application.