User:Pline

This is a staging area for some rewrites to the Python add-on documentation. Ok, let's go!

Python add-ons

The structure of an add-on

TODO: Move most of Add-on_development to a separate page, clean it up, and then reference it here somehow.

EDIT zag: This is now done ;) Feel free to update any of the tutorials though

Hello, World!

The simplest form of Python add-on is one that gets run, adds some list items, and exits to let XBMC take over the navigation; people who have written server-side code for the web should be familiar with how this works. (More complex add-ons can process user input in real-time, but we'll discuss those later.) Let's start by looking at an extremely basic example script:

import sys
import xbmcgui
import xbmcplugin

addon_id = int(sys.argv[1])

url = 'http://localhost/some_video.mkv'
li = xbmcgui.ListItem('My First Video!', iconImage='DefaultVideo.png')
li.setInfo(type='video')
xbmcplugin.addDirectoryItem(handle=addon_id, url=url, listitem=li)

xbmcplugin.endOfDirectory(addon_id)

While not particularly exciting, this shows the minimal amount of code you need to get an XBMC add-on up and running in Python. Most important is that we first create an xbmcgui.ListItem with the name and icon we want ('DefaultVideo.png' comes from the XBMC skin), set it to be a video item, and then add it to the directory. Once we're done adding items, we need to be sure to call xbmcplugin.endOfDirectory to let XBMC know we're done!

The entry point

As we saw above, XBMC passes some arguments to us via sys.argv. This is important, since it's what will let us tailor the output on the add-on based on user input. Remember, much like a web site, each folder (or page) in an XBMC add-on is the result of a separate invocation of our script. The arguments available to us are:

Index	Description
0	The base URL of your add-on, e.g. 'plugin://plugin.video.myaddon/'
1	The process handle for this add-on, as a numeric string
2	The query string passed to your add-on, e.g. '?foo=bar&baz=quux'

Of particular interest is sys.argv[2], which is what we'll generally use to show different things in the add-on.

Navigating between pages

import sys
import urllib
import urlparse
import xbmcgui
import xbmcplugin

xbmcplugin.setContent(addon_id, 'movies')

base_url = sys.argv[0]
addon_id = int(sys.argv[1])
args = urlpase.parse_qs(sys.argv[2])

def build_url(query):
    return base_url + '?' + urllib.encode(query)

mode = args.get('mode', None)

if mode is None:
    url = build_url({'mode': 'folder', 'foldername': 'Folder One'})
    li = xbmcgui.ListItem('Folder One', iconImage='DefaultFolder.png')
    xbmcplugin.addDirectoryItem(handle=addon_id, url=url,
                                listitem=li, isFolder=True)

    url = build_url({'mode': 'folder', 'foldername': 'Folder Two'})
    li = xbmcgui.ListItem('Folder Two', iconImage='DefaultFolder.png')
    xbmcplugin.addDirectoryItem(handle=addon_id, url=url,
                                listitem=li, isFolder=True)

    xbmcplugin.endOfDirectory(addon_id)

elif mode[0] == 'folder':
    foldername = args['foldername'][0]
    url = 'http://localhost/some_video.mkv'
    li = xbmcgui.ListItem(foldername + ' Video', iconImage='DefaultVideo.png')
    li.setInfo(type='video')
    xbmcplugin.addDirectoryItem(handle=addon_id, url=url, listitem=li)
    xbmcplugin.endOfDirectory(addon_id)