Writing Your First Boxee AppAuthor: Tom Philip | Filed under: tutorial
This is a step by step guide to writing your first Boxee app. This is basically how I got started, so I hope it helps.
Boxee apps are written in Python and use xml markup to describe the UI, called skins.
1. Get Yourself an IDE
It’s not absolutely necessary but a good IDE will really help with organising your files, Source Control, Refactoring, Test Running, Syntax and Coding Intellisense.
My development background is in .NET, so Python is totally new to me. I was dying to get started so I only had took quick look at editors. Mainly I wanted something free and good support to help me get to grips with the syntax. I thought I’d give NetBeans a whirl to see how that goes. It supports writing code in other languages, so personally I thought it might be of use as I expand my coding horizons.
The version for Python is still in Early Access release but I’ve had no problems from the IDE. It runs on the most popular OS’s. I’m using WinXP for my sins but I’m trying. It seems it’s also available as a plugin if you already have NetBeans.
Download NetBeans IDE for Python and install.
2. Configure the IDE for Boxee Development
First of all I downloaded and installed the version of Python that Boxee uses, which is 2.4, so that NetBeans can compile my code against this and also provide intellisense for this version. Then I set this up as my default Python platform for NetBeans (Tools > Python Platforms).
Next I got NetBeans to recognise the Boxee api. This gives you intellisense for the api, along with its documentation (the same on the Boxee developer site).
3. Create the NetBeans Project for Your App
Find the Boxee apps directory on your dev machine. Mine on WinXP is: C:\Documents and Settings\tom\Application Data\BOXEE\userdata\apps
Create a new NetBeans project (File > New Project…)
Choose Apps as the directory to create the project in and give the project a name. This will also be the unique identity of your app. How you choose your unique app id depends on how you’re going to host it.
every application in a repository must have the application repository id as a prefix to the application id. For example: if your repository is called com.myboxee and you want to build app called “facebook”, then the application id MUST be com.myboxee.facebook. This is required in order to assure global uniqueness in the application ids. – http://developer.boxee.tv/Custom_Repository
or with Boxee
Unique identifier for the application. Must be all lower case, alphanumeric and dashes (-). For example: the-wb. Dot characters are not allowed in the application id, unless the application is stored in a 3rd party repository. – http://developer.boxee.tv/App_Anatomy#Descriptor
To avoid conflicts and help identify your apps prefix them with your name or company name. As I’m hosting my own apps, mine are:
4. Build the Specified Directory Structure
In order for your app to work, files need to be located in a specified folder structure. Create the following folder structure in your netbeans project.
NetBeans wants you to use their Src folder, for python code files, that they create when you create a project. This isn’t useful at all for the boxee development, as you want to be able to edit your files and see the amendments in Boxee. It took me ages to work out why intellisense and the test runner wouldn’t run tests. The NetBean projects are initially setup to look in the Source folder for the intellisense and tests. Just remove the Src folder and add the root folder as a source, then delete the src folder as you wont need this. Right click the project to get the Properties dialog up.
5. Create an App Logo
To show your app in Boxee you need a thumbnail that represents the app. Use your favourite editor to create a png or jpeg image that is 200px by 200px.
You will then need to host this on the web, usually along with your app. This depends on whose repository your going to put the app. Your own, 3rd-party or Boxees. The Boxee Developer site has some details on the different ways to get your app released.
6. Create the First Screen
Create the first screen (or window) that will open when the app launches. Create and xml file and call it main.xml and save it in the 720p folder. This folder is where all of your UI skin files will go. This is just good practice, it can be named anything, so it’s easy to identify which is the initial opening screen.
The Boxee documentation goes into depth on the xml markup that makes up UI skins. In general each xml file contains a window that has controls on it.
To verify that everything so far has been setup correctly. Create a window and add a simple control to it in the main.xml. This will allow you to run the app with the bare minimum required. Something similar to the following.
<?xml version="1.0"?> <window type="window" id="14000"> <controls> <control type="label"> <label>Hello World!</label> <width>348</width> <height>60</height> <font>font48</font> </control> </controls> </window>
7. Describe It
Create an xml file named descriptor.xml in the root of the folder structure. This contains all the information that will describe your app to the Boxee client, some of which will appear in the Boxee Client. Boxee has the details of what should go into descriptor file.
startWindow will be the ID of the screen/window that will open when the app launches. This will be in your Main.xml, see previous step.
This is how mine looked.
<app> <id>GreatBoxee.Xkcd</id> <name>XKCD</name> <version>1.00</version> <description>A webcomic of romance, sarcasm, math, and language.</description> <thumb>http://dir.greatboxee.com/Apps/Xkcd/Thumb.png</thumb> <repositoryid>GreatBoxee</repositoryid> <repository>http://dir.greatboxee.com</repository> <media>pictures</media> <author>Great Boxee</author> <copyright>Conker Software Ltd</copyright> <email>email@example.com</email> <type>skin</type> <startWindow>14000</startWindow> <platform>all</platform> <minversion>0.9.11</minversion> <test-app>true</test-app> </app>
test-app is for local development purposes and will make the Boxee client recognise your app and show it in My Apps. Don’t forget to remove this when you deploy your app.
8. Run the App
Now start Boxee and marvel at the best looking hello world app that you will ever see on a TV.
Now once you’ve finished being impressed you’ll need to write some real code/xml. For that you’ll need a lot more than this, you’ll need the boxee developer site. Also Gonzee have just started a series on Building You First App which starts where this ends.
So far my experience with Netbeans has been ‘just OK’ (it had the bare minimum of refactorings, intellisense and a test runner). I’m used to using Visual Studio with Jetbrain’s Resharper, which for me the colour coding, refactorings, code templates, integrated test runner and intellisense make it a great IDE. I haven’t tried Eclispse or any other Python IDEs, so would love to hear what everyone else is using and your experiences.