As you may have heard via email and on the forums, the upcoming SP4 release for the Boxee Box will include the introduction of API keys for Boxee developers.  Only barely eclipsed by the news that the White Stripes are breaking up, the announcement of this new process has generated a lot of questions and we’re happy to report that the interface to get your API key is now live here.

In the next release of Boxee, all apps running on the Boxee Box will need to be signed by an API key.  What does this mean for you and your application?

Here are some quick answers to the most common questions:

1) Why are you doing this?

This rollout is in reaction to an increasingly common security requirement among premium content providers.  Distributing API keys to create signatures for applications is a frequent feature of the Smart TV space and we’re following suit.

2) What do I need to do?

If your app is in the Boxee App Library, you don’t need to do anything.  Your app is already signed for you and will not be affected by the next release.  If you are distributing your app through your own repository, we recommend you get an API key and get your application signed.

3) How do I sign up for an API key?

You can sign up for a developer account and get issued an API key by going here and signing up for a developer account.  Developer accounts on Boxee are of course free and keys are generated automatically.

4) How do I sign my app?

Once you have signed up for a profile, you can get your app signed here.

1. Login to boxee.tv
2. Navigate to http://boxee.tv/developer
3. If you haven’t already, register as a developer by filling out the profile form
4. Click on the Apps tab
5. Upload the zip of your application that you will distribute in your repository
6. Click “All Versions and Signatures”
7. Click “Download Signature”
8. Place the downloaded xml file in your repository’s download directory

5) Should I sign up even if I don’t maintain my own repository?

Yes!  We’ll be using Boxee API keys in the future for making available new services and features for developers.  Sign up now and register your apps.

We are encouraging all developers maintaining their own repositories sign their apps as soon as possible.  If you have any problems or questions,  I’m here – you can get ahold of me through the following media:

Updated: 6) Are there any changes to the API?

Be sure your descriptor.xml has a <repository> element – it is now a required.  For apps submitted to the App Library this value should be “http://dir.boxee.tv/apps/”.

• Email: developer [at] boxee [dot] tv
• Twitter: @boxee_api
  
• IRC: #boxee on FreeNode

We’re 15 days away from the launch of the Boxee Box from D-Link, our first dedicated hardware device to hit the market! Boxee HQ is buzzing with anticipation of the release and I know you in our developer community are as well.  It’s a special time for this community that we’ve built together and a whole lot of engineering blood and sweat will be on display in a couple short weeks.

In anticipation of the release, I’ll be giving a talk to the New York Personal Computer User Group about how we use open source at Boxee, give a brief overview of the development platform, show off the new Boxee Box and of course answer a bunch of your questions.  Here are the details on this month’s meeting of NYPC:

At Ripley-Grier, 520 8th Ave, between 36th & 37th Street
10th floor, Room 10D
Doors Open 6pm, Presentation 6:45 – 8:45

And on launch day 10 November Boxee and D-Link will be throwing a Boxee Box launch in Manhattan.  We’ll be debuting the Boxee Box live, showing off some new surprises and pushing our baby out into the market in style.  Already 1,000 people have RSVPed – be sure to sign up now before the event sells out!

A great new feature in our last client release that devs have been asking about is the introduction of the “dialog” window type to our platform UI.  Dialogs allow you to define frequently used combinations of UI elements in a separate XML file and activate them from any window.  This allows you to reduce the amount of duplicate markup in your app and make future maintenance far simple than duplicating similar controls in each window.  In this post we’ll look at a simple example demonstrating how to use this feature.

First, we create a simple skin with two controls: a background image and a button control in a file called main.xml and assign it Window ID 14000.

<?xml version="1.0"?>
<window type="window" id="14000">
	<defaultcontrol always="true">100</defaultcontrol>
	<allowoverlay>no</allowoverlay>
	<controls>
		<control type="image" id="101">
			<posx>0</posx>
			<posy>0</posy>
			<width>1280</width>
			<height>720</height>
			<texture>background-main.png</texture>
		</control>
		<control type="button" id="100">
			<posx>200</posx>
			<posy>200</posy>
			<width>145</width>
			<height>145</height>
			<label>Click Me!</label>
			<font>font36b</font>
			<textcolor>white</textcolor>
			<focusedcolor>gray</focusedcolor>
			<texturefocus>-</texturefocus>
			<texturenofocus>-</texturenofocus>
		</control>
	</controls>
</window>

The result looks a little like this:

Next, we create our dialog window with three controls in a file named dialog.xml and assign it Window ID 14001.

1. A diffused background image to darken the window we just created behind our new dialog.
2. A button control to close our dialog window.
3. A Boxee logo (who doesn’t need to see more of them?)

<?xml version="1.0"?>
<window type="dialog" id="14001">
 <defaultcontrol always="true">300</defaultcontrol>
 <allowoverlay>no</allowoverlay>
	 <controls>
	 	<control type="group" id="7001">
			<control type="image">
				<width>1280</width>
				<height>720</height>
				<texture>white.png</texture>
				<colordiffuse>DD202020</colordiffuse>
			</control>
			<control type="button" id="300">
				<posx>565</posx>
				<posy>75</posy>
				<width>145</width>
				<height>145</height>
				<label>Close Me!</label>
				<font>font36b</font>
				<textcolor>green</textcolor>
				<focusedcolor>green</focusedcolor>
				<texturefocus>-</texturefocus>
				<texturenofocus>-</texturenofocus>
			</control>
			<control type="image">
				<posx>244</posx>
				<posy>100</posy>
				<width>792</width>
				<height>612</height>
				<texture>logo.png</texture>
			</control>
		</control>
	 </controls>
</window>

Now we need to activate our dialog from our main window.  To do this, we add an onclick event to the button control in main.xml and introduce an easy ActivateWindow() method using the ID of our dialog (14001) as the argument.

		<control type="button" id="100">
			<posx>200</posx>
			<posy>200</posy>
			<width>145</width>
			<height>145</height>
			<label>Click Me!</label>
			<font>font36b</font>
			<textcolor>white</textcolor>
			<focusedcolor>gray</focusedcolor>
			<texturefocus>-</texturefocus>
			<texturenofocus>-</texturenofocus>
			<onclick lang="python"><![CDATA[
mc.ActivateWindow(14001)
]]></onclick>
		</control>

Once we restart the app, we can now see the three controls we created in our dialog appear over our window.  Bamf!

But, it is not merely enough to display a dialog window – we need the user to be able to close it as well.  So we use the xbmc module to execute a method called “Dialog.Close()”.  We do this by first importing the xbmc module in an onload event for the dialog.

<?xml version="1.0"?>
<window type="dialog" id="14001">
 <defaultcontrol always="true">300</defaultcontrol>
 <allowoverlay>no</allowoverlay>
 <onload lang="python"><![CDATA[
import xbmc
mc.LogDebug(message)
]]>
</onload>

We then can execute it by adding the following onclick event to our dialog’s button control.

			<control type="button" id="300">
				<posx>565</posx>
				<posy>75</posy>
				<width>145</width>
				<height>145</height>
				<label>Close Me!</label>
				<font>font36b</font>
				<textcolor>green</textcolor>
				<focusedcolor>green</focusedcolor>
				<texturefocus>-</texturefocus>
				<texturenofocus>-</texturenofocus>
				<onclick lang="python"><![CDATA[
xbmc.executebuiltin("Dialog.Close(14001)")
]]></onclick>
			</control>

Once we restart the app, we can now toggle between our dialog window and our main window!

The uses for dialogs in Boxee apps are limited only by your own creativity and can help keep your app’s XML tight and maintainable.  Enjoy!

Complete examples:

main.xml

<?xml version="1.0"?>
<window type="window" id="14000">
	<defaultcontrol always="true">100</defaultcontrol>
	<allowoverlay>no</allowoverlay>
	<controls>
		<control type="image" id="101">
			<posx>0</posx>
			<posy>0</posy>
			<width>1280</width>
			<height>720</height>
			<texture>background-main.png</texture>
		</control>
		<control type="button" id="100">
			<posx>200</posx>
			<posy>200</posy>
			<width>145</width>
			<height>145</height>
			<label>Click Me!</label>
			<font>font36b</font>
			<textcolor>white</textcolor>
			<focusedcolor>gray</focusedcolor>
			<texturefocus>-</texturefocus>
			<texturenofocus>-</texturenofocus>
			<onclick lang="python"><![CDATA[
mc.ActivateWindow(14001)
]]></onclick>
		</control>
	</controls>
</window>

dialog.xml

<?xml version="1.0"?>
<window type="dialog" id="14001">
 <defaultcontrol always="true">300</defaultcontrol>
 <allowoverlay>no</allowoverlay>
 <onload lang="python"><![CDATA[
import xbmc
mc.LogDebug(message)
]]>
</onload>
	 <controls>
	 	<control type="group" id="7001">
			<control type="image">
				<width>1280</width>
				<height>720</height>
				<texture>white.png</texture>
				<colordiffuse>DD202020</colordiffuse>
			</control>
			<control type="button" id="300">
				<posx>565</posx>
				<posy>75</posy>
				<width>145</width>
				<height>145</height>
				<label>Close Me!</label>
				<font>font36b</font>
				<textcolor>green</textcolor>
				<focusedcolor>green</focusedcolor>
				<texturefocus>-</texturefocus>
				<texturenofocus>-</texturenofocus>
				<onclick lang="python"><![CDATA[
xbmc.executebuiltin("Dialog.Close(14001)")
]]></onclick>
			</control>
			<control type="image">
				<posx>244</posx>
				<posy>100</posy>
				<width>792</width>
				<height>612</height>
				<texture>logo.png</texture>
			</control>
		</control>
	 </controls>
</window>

Jeremy Toeman over at Stage Two just posted a great piece on the 10 essentials of making a great Boxee app.  He opens up the list with a personal fave bit of advice for first time Boxee devs:

10 – Avoid Input Fields At All Costs

The Boxee Box comes with a clever remote that includes a full QWERTY keyboard on its reverse. That is awesome. Scratch that, it’s super-awesome. Hopefully you only use it when you should – specifically when you are searching for something, logging into something, or some other highly meaningful purpose. Content for the interactive television is not the same as content for a computer or mobile device. Smart couch surfing should feel like analogue couch surfing- not in the content delivered, but in the manner in which it is accessed. If your App asks the user to “type” every 2 minutes, you might as well be thinking of a computer experience, not a TV one.

Check out the full post over at Stage Two.

We’re huge fans of Hak5 over at Boxee Engineering and we were all dead excited to see Boxee show up in their segments over the past few weeks.  In particular, we loved Jason’s intro to developing on Boxee which has been the best video demonstration of how to develop on Boxee we’ve seen so far.

You can watch the intro below or – better yet – in the Revision3 app on Boxee.

Thanks Jason and Hak5! Keep hacking!

I got a great question this week from a developer looking to make a dynamic menu for his Boxee app.  Rather than create his menu with a Grouplist that would require a new release of his application if he wanted to add an item to his menu, he was looking to construct his menu on the fly with Python.  Not only was it possible on Boxee, but with the ListItems object it was super easy.

First, let’s define the three pieces that can make a dynamic menu possible.

1) List Container

The List Container is the UI control that is going to serve our dynamic menu.  Unlike a Grouplist where we would define each of our menu options with an individual button, we define the dimensions, how the the unfocused (itemlayout) and focused (focusedlayout) states should appear, and then feed it a ListItems object to construct our menu dynamically.  We’ll use the following as a quick example:

<control type="list" id="100">
	<width>600</width>
	<height>100</height>
	<orientation>horizontal</orientation>
	<itemlayout width="100" height="100">
		<control type="label">
			<width>100</width>
			<height>60</height>
			<font>sans18</font>
			<align>center</align>
			<aligny>center</aligny>
			<label>$INFO[ListItem.Label]</label>
			<textcolor>white</textcolor>
		</control>
	</itemlayout>
	<focusedlayout width="100" height="100">
		<control type="image">
			<width>100</width>
			<height>100</height>
			<texture>background-showfocused.png</texture>
		</control>
		<control type="label">
			<width>100</width>
			<height>60</height>
			<font>sans18</font>
			<align>center</align>
			<aligny>center</aligny>
			<label>$INFO[ListItem.Label]</label>
			<textcolor>white</textcolor>
		</control>
	</focusedlayout>
	<content type="action">
	</content>
</control>

2) ListItems

With the Boxee python API, ListItems are the data object that we use to populate List Containers.  They are constructed simply.

itemList = mc.ListItems()

3) ListItem

While ListItems is a data object, we still need individual datum to fill it with.  This is where the ListItem object comes in.  Each of our individual menu items is defined in a ListItem, appended to a ListItems object, and then fed to a List Container.  While the ListItem is a very diverse data object with a number of different uses on the Boxee platform, we can use the simple unknown type to make our menu items.

Now that we’ve defined the parts of the API we need, let’s roll them together for a functioning menu.  For the purposes of this post, we’ll assume you have already requested your menu items from some server-side resource and put them into a dictionary.  By way of example, we’ll assume the key is the label of the menu item and the value is path we want to use.  We’ll also assume in this case that our List Container is assigned ID 100.
First, we need to create our ListItems object.

dynamicMenu = mc.ListItems()

Then we create a ListItem for each entry in our dictionary and append it to the ListItems object.

for key, value in menuDictionary.iteritems():
	item = mc.ListItem(mc.ListItem.MEDIA_UNKNOWN)
	item.SetLabel(str(key))
	item.SetPath(str(value))
	dynamicMenu.append(item)

Finally, we populate our List Container with our ListItems object.

mc.GetActiveWindow().GetList(100).SetItems(dynamicMenu)

And viola! We have a dynamically created menu for our app.
If you’d like to get more tips and tricks and are in the New York area this evening, be sure to drop by this month’s NYC Python meetup where I’ll be introducing Boxee, showing off the Python API and answering your questions.
Also, we’d like to give a big shoutout to our friends at Atlassian who just hooked us up with licenses for their agile development product GreenHopper. If you are a Scrum or Agile shop and looking for a more intelligent way of managing your stories that integrates with tools you are already using like JIRA, the Boxee crew can wholeheartedly endorse GreenHopper for your next sprint.
			

Next week 20 July Rob is going to be joining the crew at New York Python Meetup Group to give a quick overview of Boxee’s Python API .  This deck is all code, no choad focused for Python developers looking to get kickstarted on the Boxee platform.

RSVP is required and space is filling fast – if you’re in New York and want to talk Python with Boxee, be sure to check out NYC Python’s registration page and get your name in with a quickness.

A common question from coders new to the Boxee platform is the storage of configuration settings for their users.  From display preferences for the user interface to ID/password combos for subscription systems, many of the apps on Boxee need the ability to store these user preferences.

Many developers ask how to easily write files to Boxee’s temporary directory, taking it upon themselves to develop their own file format to store their settings in.  However, if your preferences can be stored as key/value pairs, Boxee has a built in class that makes storing settings far easier called LocalConfig.

LocalConfig is the object all Boxee apps can use to store key/value pairs that will persist from user session to user session on the same Boxee install.  While these settings will have to be entered (for now at least) in every Boxee install the user logs into, it is an easy way to keep your users from having to input the same data for every session.

Let’s take a look at the LocalConfig object in action with the example storing a username and password combination.  The first thing we want to do is store a  username and password with our app.  We can do this easily first by creating a login button in our main.xml.

<control type="button" id="100">
	<description>Login</description>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-loginfocused.png</texturefocus>
	<texturenofocus>button-login.png</texturenofocus>	
</control>

Once the user clicks “Login,” we want to present the user to input their username and password with Boxee’s built-in keyboard interface.  We can accomplish this by adding two ShowDialogKeyboard requests to an onclick event for the login button.

<control type="button" id="100">
	<description>Login</description>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-loginfocused.png</texturefocus>
	<texturenofocus>button-login.png</texturenofocus>	
	<onclick lang="python"><![CDATA[
emailaddress = mc.ShowDialogKeyboard("Email", "", False)
userpassword = mc.ShowDialogKeyboard("Password", "", True)
]]></onclick>
</control>

Next we’ll check to make sure the user entered their username and password and, if so, store them in our LocalConfig.  We add this code to the login event.

<control type="button" id="100">
	<description>Login</description>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-loginfocused.png</texturefocus>
	<texturenofocus>button-login.png</texturenofocus>	
	<onclick lang="python"><![CDATA[
emailaddress = mc.ShowDialogKeyboard("Email", "", False)
userpassword = mc.ShowDialogKeyboard("Password", "", True)
if emailaddress and userpassword:
	config = mc.GetApp().GetLocalConfig()
	config.SetValue("username", emailaddress)
	config.SetValue("password", userpassword)
	mc.ShowDialogNotification("Credentials stored.")
       # Insert login code here
else:
	mc.ShowDialogNotification("Please enter username and password.")
]]></onclick>
</control>

Now that we have stored the username and password, we want to make sure the app knows this and logs the user every time the application is launched without asking the user for his/her credentials again.  With the LocalConfig object, we can check if values exist in an onload event for the window and then take appropriate action if it does.

config = mc.GetApp().GetLocalConfig()
emailaddress = config.GetValue("username")
userpassword = config.GetValue("password")
 
if emailaddress:
	mc.ShowDialogNotification("Logging in...")
        # Insert login code here

Lastly, we would be remiss in our duties as courteous developers if we didn’t also give our users the ability to logout.  With the paradigm we’ve set up here using LocalConfig, all we have to do is clear the LocalConfig for the app and the user will not no longer login on app start.

<control type="button" id="101">
	<description>Logout</description>
	<posx>200</posx>
	<posy>0</posy>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-logoutfocused.png</texturefocus>
	<texturenofocus>button-logout.png</texturenofocus>
	<onclick lang="python"><![CDATA[
config = mc.GetApp().GetLocalConfig()
config.ResetAll()	
mc.ShowDialogNotification("Logging out...")
# Insert logout code here
]]></onclick>
</control>

Here’s the complete main.xml as an example.  Enjoy!

<?xml version="1.0"?>
<window type="window" id="14000">
<onload lang="python"><![CDATA[
config = mc.GetApp().GetLocalConfig()
emailaddress = config.GetValue("username")
userpassword = config.GetValue("password")
 
if emailaddress:
	mc.ShowDialogNotification("Logging in...")
	# Insert login code here
]]></onload>
	<defaultcontrol always="true">111</defaultcontrol>
	<allowoverlay>no</allowoverlay>
	<controls>
		<control type="group">
			<control type="button" id="100">
				<description>Login</description>
				<width>114</width>
				<height>37</height>
				<texturefocus>button-loginfocused.png</texturefocus>
				<texturenofocus>button-login.png</texturenofocus>	
				<onclick lang="python"><![CDATA[
emailaddress = mc.ShowDialogKeyboard("Email", "", False)
userpassword = mc.ShowDialogKeyboard("Password", "", True)
if emailaddress and userpassword:
	config = mc.GetApp().GetLocalConfig()
	config.SetValue("username", emailaddress)
	config.SetValue("password", userpassword)
	mc.ShowDialogNotification("Credentials stored.")
else:
	mc.ShowDialogNotification("Please enter username and password.")
]]></onclick>
			</control>
			<control type="button" id="101">
				<description>Logout</description>
				<posx>200</posx>
				<posy>0</posy>
				<width>114</width>
				<height>37</height>
				<texturefocus>button-logoutfocused.png</texturefocus>
				<texturenofocus>button-logout.png</texturenofocus>
				<onclick lang="python"><![CDATA[
config = mc.GetApp().GetLocalConfig()
config.ResetAll()	
mc.ShowDialogNotification("Logging out...")
]]></onclick>
			</control>
		</control>
	</controls>
</window>

Penguin enthusiasts in the Big Apple be warned, I will be giving a talk at this month’s meeting of the New York Linux Users Group.  The presentation will be a quick intro on Boxee, how open source is woven into the fabric of our product and our culture, and (always my favorite topic) how developers can get involved making apps for Boxee.  Held at NYLUG’s hosts IBM at 57th and Madison, the talk will kick off at 6:30pm followed by a friendly drink up nearby.

I’ll have an arm load of T-shirts in tow, plenty time for Q&A and a wide array of terrible jokes for your consuming pleasure.

You must RSVP here first for the talk.

More info on the talk and location are available at NYLUG.

When: Wednesday, 16 June 2010, 6:30pm
Where: IBM, 590 Madison Avenue, 12th Fl, New York, NY

View Larger Map

Here at Boxee we pride ourselves in being the open alternative to other television partners and this philosophy extends to our development community.  Developing apps on Boxee is and always will be free for anyone who wants to bring their content to the platform.  Distributing these apps occurs through two mechanisms – the Boxee App Library and third-party repositories.   Let’s take a look at both of these two options and why one is likely preferable to the other for your Boxee app.

What is the Boxee App Library?

Also called the “App Box” and the “main repo” on the forums, the Boxee App Library is the default app repository pre-configured on every Boxee install.  Every app in in the Library is vetted and approved by Boxee’s Quality Assurance team, ensuring every user can be confident that the experience he/she will find in the App Library will be great.

What are third-party repositories?

In addition to submitting to our App Library, developers have the option of adding their own repositories using our open specification.   Just as any one can build an app on Boxee, anyone can build a library for Boxee apps.  In keeping with our open source culture, this gives our community an option available on few other development platforms (and fewer still for the TV): the freedom to control the distribution of their work.

Why should my app be submitted to the App Library?

With the ability to distribute your software yourself, some developers wonder what the benefits are to submitting their app to the App Library.  There are three big wins that the App Library brings to every app:

1) Visibility

A very strong majority of Boxee users never install a third-party repository.  This creates a gate between Boxee’s 1.1 million user audience and your app.  By submitting to the App Library, you ensure that every single user of Boxee can access your app without having to follow any instructions or encounter any obstructions.  All the most popular apps on Boxee are distributed through the App Library.

2) Quality Assurance

Like many other app ecosystems, each app that is published in the App Library gets screened by Boxee’s crack Quality Assurance group.  Coding always means bugs and even the best among us let some get through the cracks.  There is no one in the Boxee community as adept at finding bugs as our QA group and their assistance will always ensure a better end product.

3) Maintenance Tools

Every developer that submits their app to the App Library also gets access to our tools to maintain apps, most notably JIRA.   As the central bug tracker for all things Boxee, this means that users can submit quality bugs for your app, giving you instant feedback on the app’s function and quality.  In addition, you can integrate your IDE with Boxee’s JIRA install quickly and easily with tools like Mylyn, giving you even easier control over the maintenance of your app.

In short, the Boxee App Library gives your app the distribution, the tools and the tender-lovin’-care it needs to thrive in our wide development ecosystem. In addition, it is super simple!

How To Submit:

Submitting to our App Library is easy and transparent.  All you have to do is follow the Application Submission process found on our developer wiki.

Your app with then get into our queue and you will start receiving communication from our QA group within 1 business day.

We’ve invested significant effort in our submission process as of late.  While we feel we still have a way to go before we are satisfied, we strongly believe that it is more open and transparent than many other submission processes developers have to endure when making the software they love.

As always, I welcome your feedback – find me on FreeNode in #boxee or on Twitter @boxee_api.