User:Pline: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
(Blanking this, since I moved it to Audio/Video tutorial)
 
(8 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 process handle 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.
===  Multiple content types ===
{{See also|Addon.xml#<provides> element}}
If your add-on provides multiple content types, e.g. <code>audio</code> and <code>video</code>, when the user invokes your add-on from the add-on list, XBMC will add a <code>content_type</code> parameter to your add-on's query string. For example: <code>'?content_type=audio'</code>. This will allow you to modify the output depending on what context your add-on was invoked in.
== 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>. With this information, we can tailor the output of our add-on to the supplied arguments.
We also need to be able to create links back to our add-on in order to display related pages (e.g. subfolders). We can do this by creating an <code>xbmc.ListItem</code>, passing <code>isFolder=True</code>, and setting the URL of the item to point back to our add-on. We create the URL in the helper function <code>build_url()</code>, which gives us a URL that looks something like:
plugin://plugin.video.myaddon/?mode=folder&foldername=Folder+One
= Showing additional metadata =
We've already seen how to show some basic metadata, like the icon image and the type of the item (<code>'video'</code> in our case). However, there are many more pieces of metadata that XBMC understands, and adding them can make life easier on your users. We'll take a look at some of the more important ones. You can also find a full list in the [http://mirrors.xbmc.org/docs/python-docs Python documentation] for <code>[http://mirrors.xbmc.org/docs/python-docs/12.2-frodo/xbmcgui.html#ListItem xbmcgui.ListItem]</code>.
== Icons and thumbnails ==
== Info labels ==
== Stream info ==
= Adding context menus =
= Working with user settings =

Latest revision as of 00:33, 18 December 2013

Retrieved from "https://kodi.wiki/index.php?title=User:Pline&oldid=66924"