|
|
| (15 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| This is a staging area for some rewrites to the Python add-on documentation. Ok, let's go!
| |
|
| |
|
| = Before we get started =
| |
| {{See also|Add-on structure}}
| |
|
| |
| The first step to making an add-on is to put the basic structure in place. Make sure your directory is properly named, e.g. <code>plugin.video.my-addon</code>, and that you have a properly-constructed <code>[[addon.xml]]</code> file. Once these are done, you can get started writing the actual code for your add-on!
| |
|
| |
| = 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:
| |
|
| |
| <source lang="python">
| |
| import sys
| |
| import xbmcgui
| |
| import xbmcplugin
| |
|
| |
| addon_id = int(sys.argv[1])
| |
|
| |
| xbmcplugin.setContent(addon_id, 'movies')
| |
|
| |
| 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)
| |
| </source>
| |
|
| |
| While not particularly exciting, this shows the minimal amount of code you need to get an XBMC add-on up and running in Python. First, we get the add-on's id from <code>sys.argv[1]</code>. We need this to tell XBMC who we are. Next, we tell XBMC that we're going to show a list of <code>'movies'</code>. There are other options, like <code>'audio'</code> or <code>'episodes'</code>; these just change some details of how XBMC presents your add-on.
| |
|
| |
| The most important part is that we create an <code>xbmcgui.ListItem</code> with the name and icon we want (<code>'DefaultVideo.png'</code> 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 <code>xbmcplugin.endOfDirectory</code> to let XBMC know we're done!
| |
|
| |
| = Navigating between pages =
| |
|
| |
| While the first example might be enough for extremely simple add-ons, most add-ons will want to have the ability to navigate between different pages. Most add-ons are designed to imitate a folder hierarchy where opening folder items shows a different list of items, and going "up" returns you to the parent folder.
| |
|
| |
| == Retrieving arguments ==
| |
|
| |
| As we saw in the first example, XBMC passes some arguments to us via <code>sys.argv</code>. 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:
| |
|
| |
| {| class="wikitable"
| |
| ! Index !! Description
| |
| |-
| |
| | 0 || The base URL of your add-on, e.g. <code>'plugin://plugin.video.myaddon/'</code>
| |
| |-
| |
| | 1 || The process handle for this add-on, as a numeric string
| |
| |-
| |
| | 2 || The query string passed to your add-on, e.g. <code>'?foo=bar&baz=quux'</code>
| |
| |}
| |
|
| |
| Of particular interest is <code>sys.argv[2]</code>, which is what we'll generally use to show different things in the add-on.
| |
|
| |
| == Passing arguments ==
| |
|
| |
| Now that we know how to retrieve the arguments passed to our add-on, we'll have to actually pass some along to it. Generally speaking, this involves creating a folder <code>ListItem</code> with a URL back to your add-on; then the next invocation of the add-on will parse those arguments and do something with them. Let's look at another brief example that adds some folders to let the user navigate between different pages of the add-on:
| |
|
| |
| <source lang="python">
| |
| import sys
| |
| import urllib
| |
| import urlparse
| |
| import xbmcgui
| |
| import xbmcplugin
| |
|
| |
| base_url = sys.argv[0]
| |
| addon_id = int(sys.argv[1])
| |
| args = urlparse.parse_qs(sys.argv[2][1:])
| |
|
| |
| xbmcplugin.setContent(addon_id, 'movies')
| |
|
| |
| 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)
| |
| </source>
| |
|
| |
| As you can see, many parts of our code are very similar to the first example. There are a few important additions, however. First, we want to respond to the arguments supplied to our script, so we parse the query string with:
| |
|
| |
| <source lang="python">
| |
| urlparse.parse_qs(sys.argv[2][1:])
| |
| </source>
| |
|
| |
| We skip the first character, since it's always <code>'?'</code>. This will give us a <code>dict</code> of <code>list</code>s; for example, <code>'?foo=bar&foo=baz&quux=spam'</code> would be converted to <code>{'foo': ['bar', 'baz'], 'quux': ['spam']}'</code>.
| |