Updating 0.4 Feathers to be 0.5 Compatible

Applicable to Songbird version: 0.5
Required Knowledge: CSS

Introduction

As Songbird grows, it is inevitable that feathers and other extensions will sometimes break between releases. After 1.0, we will try to be nicer about this, but for now we're more concerned with making things better.

Luckily most feathers created for 0.4 will work just fine in 0.5.

This document lists important Rubberducky changes that you may want to copy in your feathers. The code listings shown are styled such that this represents removed lines, while

this represents added lines. For details see the complete patches to Rubberducky and the Basic Layouts package.  If you run into problems, come to irc.mozilla.org#songbird.

Install.rdf Changes

Really the only thing preventing 0.5 compatibility is the version target in your install.rdf. The Extension Manager reads the min and max version when you try to install an .XPI, and decides whether or not to proceed.

The first thing you should do is change your minVersion to 0.5pre and your max version to 0.6pre.

<em:targetApplication>
	<Description>
		<em:id>songbird@songbirdnest.com</em:id>
		<em:minVersion>0.4pre</em:minVersion>
		<em:maxVersion>0.5pre</em:maxVersion>
		<em:minVersion>0.5pre</em:minVersion>
		<em:maxVersion>0.6pre</em:maxVersion>
	</Description>
</em:targetApplication>

Also, we've slightly simplified the install.rdf file. You no longer need a <feathers/> element in the install.rdf, just <skin/>s and <layout/>s. An add-on with the <feathers/> element will continue to work for this release, but will log an error to the console. A future version will remove this backwards compatibility feature.

<feathers/> <Description> <skin><!-- the rest goes here --></skin> </Description></feathers>
<skin><!-- the rest goes here --></skin>

Chrome.manifest Changes

The most important change in 0.5 is the addition of the chrome://songbird-mozapps/skin provider. We've decided to fork the the chrome://mozapps/skin/ in the Mozilla Toolkit (which contains styles for things like the download window, the add-on manager) in order to avoid dependency problems and platform specific ugliness.

To override the Mozilla styles we add the following line to our chrome.manifest (jar.mn.in in the Songbird build system):

skin  mozapps  rubberducky/0.2  chrome://songbird-mozapps/skin/ 

This says that when the "rubberducky/0.2" skin is active, the chrome://mozapps/skin path should point to chrome://songbird-mozapps/skin. As a result, the current feathers have complete control over the standard Mozilla dialogs.

If your feathers are similar to Rubberducky, and require complete control, simply copy the above line into your chrome.manifest. If your feathers try to blend in with the operating system (e.g. do not use the songbird-global package) then you can safely ignore this line.

Style Changes

Rubberducky styles changed very little in 0.5. You may want to copy some of our cosmetic fixes into your feathers, but it is completely optional. See this changeset if you are curious.

Layout Changes

If your feathers include an alternate layout (mainplayer.xul or miniplayer.xul), you'll need to update them to use our new extension overlay structure. Rather than include an overlay for each type of content, we now include a single overlay which provides everything required.

There are two overlays available:

1. layoutWithBrowserOverlay.xul, which includes all the scripts and content needed for a player window that includes a tab browser element.
2. layoutWithoutBrowserOverlay.xul, which includes the basics needed for a simple browserless player window.

Here is an example of layoutWithBrowserOverlay in the main songbird layout:

 	<!-- Include this to automatically import the standard scripts for the main window --> 
 	<?xul-overlay href="chrome://songbird/content/xul/mainScriptsOverlay.xul"?> 
 	<?xul-overlay href="chrome://songbird/content/xul/popupOverlay.xul"?> 
	<?xul-overlay href="chrome://songbird/content/xul/actionSetsOverlay.xul"?> 
 	<?xul-overlay href="chrome://songbird/content/xul/menuOverlay.xul"?> 
	<?xul-overlay href="chrome://songbird/content/xul/browserToolbarOverlay.xul"?> 
 	<?xul-overlay href="chrome://songbird/content/xul/statusBarOverlay.xul"?> 
 	<?xul-overlay href="chrome://songbird/content/xul/controlToolbarOverlay.xul"?> 
	<!-- Include this to import the standard overlays for a window containing a gBrowser element --> 
 	<?xul-overlay href="chrome://songbird/content/xul/layoutWithBrowserOverlay.xul"?> 

       ....

 	 <!-- 
 	     Standard sets, filled by overlay files.   
 	    NOTE: These items must retain their IDs for Firefox extension compatibility. 
 	  --> 
 	 <popupset id="mainPopupSet" /> 
 	 <commandset id="mainCommandSet" /> 
 	 <broadcasterset id="mainBroadcasterSet" /> 
 	 <keyset id="mainKeyset" />   
 	 <stringbundleset id="stringbundleset">  
 	 <stringbundle id="songbird_strings" src="chrome://songbird/locale/songbird.properties"/> 
 	 </stringbundleset>  

 	 <!-- standard overlays insertion point for popups, commands, broadcasters, keys and stringbundles --> 
	 <sb-support id="mainSupportSet"/> 

See the basic layouts changeset for details.

Additional Resources

• Complete list of changes to Rubberducky between 0.4 and 0.5
• Complete list of changes to the Basic Layouts package between 0.4 and 0.5
• Updating 0.3 Feathers to be 0.4 Compatible