.. _quickstart: Quickstart ============ If you haven't already installed xbmcswift2, head over to the `installation` page. The purpose of xbmcswift2 is to empower plugin writers to develop and debug their plugins faster. This is faciliated by: * A bootstrap script to create an empty addon complete with folder structure and required files. * Seamless testing of addons by enabling an addon to be run on the command line or in XBMC. xbmcswift2 handles mocking the xbmc python modules to ensure your addon will run (in a limited fashion) outside of XBMC *without* any code changes. * Basic URL routing code, so you can focus on writing the web parsing code specific to your plugin, and not deal with repeated boilerplate and url parsing. * A library of helpful functions and code patterns to enhance your addon's functionality. Introduction to XBMC Addons --------------------------- Before going any further, you should already be familiar with the general file structure and necessary files for an XBMC addon. If not, please spend a few minutes reading about addons in the XBMC wiki_. .. _wiki: http://wiki.xbmc.org/index.php?title=Add-on_development Creating the Plugin Skeleton ---------------------------- xbmcswift2 comes with a helpful console script that will create a plugin skeleton for you, including all the necessary folders and files to get started. Simply run `xbmcswift2 create` and answer a few questions to personalize your addon. Below is an example session:: $ xbmcswift2 create xbmcswift2 - A micro-framework for creating XBMC plugins. xbmc@jonathanbeluch.com -- I'm going to ask you a few questions to get this project started. What is your plugin name? : Hello XBMC Enter your plugin id. [plugin.video.helloxbmc]: Enter parent folder (where to create project) [/private/tmp]: Enter provider name : Jonathan Beluch (jbel) Projects successfully created in /private/tmp/plugin.video.helloxbmc. Done. Hello XBMC ---------- If you navigate to the newly created folder ``plugin.video.helloxbmc``, you'll find an ``addon.py`` exactly like the one below. .. sourcecode:: python from xbmcswift2 import Plugin plugin = Plugin() @plugin.route('/') def index(): item = { 'label': 'Hello XBMC!', 'path': 'http://s3.amazonaws.com/KA-youtube-converted/JwO_25S_eWE.mp4/JwO_25S_eWE.mp4', 'is_playable': True } return [item] if __name__ == '__main__': plugin.run() The above code is a fully functioning XBMC addon (not that it does much!). So what does the code do? 1. After importing the Plugin class, we create our plugin instance. xbmcswift will parse the proper addon name and id from the addon.xml file. 2. We are using the ``plugin.route`` decorator on the ``index`` function. This binds a url path of '/' to the index function. ('/' is the default URL path). Note: The url rule of '/' must always exist in a plugin. This is the default route when a plugin is first run. 3. The index function creates a single dict with some key/vals. This is how you create a listitem using xbmcswift2. At a minimum, most items have a ``path`` and ``label``. The ``is_playable`` flag tells XBMC that this is a media item, and not a URL which points back to an addon. 4. We return a list from the index function, that contains a single item. For a typical xbmcswift2 view, this is the proper way to add list items. 5. We call ``plugin.run()`` to run our plugin. It is imperative that this line is inside the ``__name__`` guard. If it is not, your addon won't run correctly on the command line. Running Addons from the Command Line ------------------------------------ One of the shining points of xbmcswift2 is the ability to run plugins from the command line. To do so, ensure your working directory is the root of your addon folder (where you addon.xml file is located) and execute ``xbmcswift2 run``.:: $ xbmcswift2 run 2012-05-02 19:02:37,785 - DEBUG - [xbmcswift2] Adding url rule "/" named "index" pointing to function "index" 2012-05-02 19:02:37,798 - DEBUG - [xbmcswift2] Dispatching / to once 2012-05-02 19:02:37,798 - INFO - [xbmcswift2] Request for "/" matches rule for function "index" ---------------------- # Label Path ---------------------- [0] Hello XBMC! (None) ---------------------- Right away we can see the output of our plugin. When running in the CLI, xbmcswift2 prints log messages to STDERR, so you can hide them by appending ``2>/dev/null`` to the previous command.. Below the logs we can see a simple display of our listitems, in this case a single item. See :ref:`commandline` for a more detailed explanation of running on the command line. URL Routing ----------- Another advantage of using xbmcswift2, is its clean URL routing code. This means you don't have to write your own code to parse the URL provided by XBMC and route it to a specific function. xbmcswift2 uses a a path passed to the :meth:`~xbmcswift2.Plugin.route` decorator to bind a URL to a function. For example, a route of ``/videos/`` will result in a URL of ``plugin://plugin.video.helloxbmc/videos/`` calling the decorated function. It's even possible to pass variables to functions from the URLs. You might have a function like this to list videos for a given category: .. sourcecode:: python @plugin.route('/categories//') def show_videos(category): '''Display videos for the provided category''' # An incoming URL of /categories/science/ would call this function and # category would have a value of 'science'. items = get_video_items(category) return plugin.finish(items) Currently, there is no type coercion, so all variables plucked from URLs will be strings. Now we have a way of directing incoming URLs to specific views. But how do we link list items to other views in our code? We'll modify our Hello XBMC addon: .. sourcecode:: python @plugin.route('/') def index(): items = [ {'label': 'Hola XBMC!', 'path': plugin.url_for('show_label', label='spanish')}, {'label': 'Bonjour XBMC!', 'path': plugin.url_for('show_label', label='french')}, ] return items @plugin.route('/labels/