User Tools

Site Tools


developer_center:creating_feathers

Creating Feathers

Required Knowledge: CSS, HTML, XML

Optional Knowledge: General aesthetics, feng shui, and color theory

Introduction

Feathers are add-ons that customize Nightingale's appearance and layout. By creating and installing feathers you can change Nightingale's color scheme, replace button images, or design a completely new player window.

Nightingale's user interface is like a web page. The layout is built using XUL (XML User-interface Language, a markup language similar to HTML) and the appearance is controlled with Cascading Style Sheets (CSS). If you've designed a web site, you can design a new user interface for Nightingale.

Getting Started

Developer Tools

You can make feathers creation easier by downloading and installing the Nightingale Developer Tools Add-on. Installing the add-on will:

  • auto-generate the initial files needed
  • disable user interface caching so you can see the results of the changes your feathers make.
  • add a number of utilities to the Tools menu that you'll find helpful when you're designing and testing your feathers.
  • enable debug output

(To install the add-on, simply download the XPI within the Nightingale web browser)

Making a New Profile

Nightingale stores your music library, preferences, bookmarks, and add-ons in a profile folder. To create feathers, start by creating a new Nightingale profile. Creating a dedicated profile for development makes it easier to create and test feathers, isolating changes and making it easy for you to experiment.

To do this, after you've installed the Developer Tools add-on, select Tools > Enable Profile Manager from Nightingale's main menu, then restart Nightingale. You should then see the Profile Manager every time Nightingale loads. Use this dialog to create and select separate profiles for development, testing, and everyday use.

Creating a Feathers Project

The Developer Tools add-on contains a wizard that enables you to set up a feathers project and create the necessary supporting files. Launch the Feathers Wizard by selecting Tools > Create New Feathers from the main menu.

After you run the wizard, Nightingale should restart, and your feathers project should appear at the location you selected. The wizard registers your project directory in the current profile as a test-mode extension, and then switches to your new feathers.

The feathers project created by the wizard is in a folder comprised of a number of files. You can edit these files to customize your feather.

Project Files

Configuration

In the root of the project folder there are two configuration files. These files are created by the wizard, and should not require modification:

  • install.rdf - Contains information about your feather, including its name, version, and description. For more information see the Mozilla reference docs.
  • chrome.manifest - Declares the internal chrome: URL paths used in your feather. For more information see the Mozilla reference docs.

CSS

The files that define the appearance of your feathers are found in the chrome/skin/ folder.

  • feathers.css - The main CSS file that applies colors, borders, backgrounds, etc.
  • colors.css - CSS rules that margins, padding, and font-sizes.
  • images.css - Extra image rules that are specific to your feather. This can include additional branding and background images, or whatever else you want to add.
  • html.css - CSS rules applied to extensions that use HTML content, such as Concerts, mashTape, Last.fm, & LyricMaster.
  • You should ignore all other CSS files such as globalImport.css, formsImport.css, and songbird.css

Many of the CSS rules that deal with applying images and setting sizes are not found in the feathers project. Since they are common to almost all feathers, these CSS rules have default styles set by Nightingale. If you need to, you can override these rules by copying them into your CSS files in your feather.

Images

You can customize the images used by Nightingale in your feather. Image files are found in the subfolders of chrome/skin/.

Customizing the Default Look

To customize Nightingale's default look, start by making simple changes to the images and CSS files in your feathers project folder. To test your modifications, make sure your feathers are active by selecting the feathers option on the main menu. Then select the Tools > Refresh UI menu item. The Nightingale window should immediately reload with your changes.

Colors

To change Nightingale's color scheme, edit chrome/skin/feathers.css. feathers.css contains foreground, background, and border color rules for nearly everything you see in Nightingale.

For example, you can test your feathers project by changing the window background color. To do this, locate the following rule at the start of colors.css:

wizard,
dialog,
window,
prefwindow,
playlist
{
	background-color: #313131; /* color of the Main Window **/
	color: #B3BAAC; /* Light Color 1 */
}

Replace #313131 with red, save the file, and then select Tools > Refresh UI from Nightingale's main menu. You should be able to see that the window background color has changed color. See the troubleshooting section if you have problems.

Images

For your first feathers, experiment with modifying the default images found in the subfolders of chrome/skin. For example, try tinting chrome/skin/buttons/player-controls.png and then reloading Nightingale.

You'll notice that we put multiple buttons and button states in a single image. This allows Nightingale to load more quickly and prevents flickering on button state changes. The display area within an image can be controlled with the moz-image-region and background-position CSS properties, but if you keep your changes within the dimensions of the default images you wont have to worry about making CSS changes.

Advanced Customization

Image CSS

Much of the CSS responsible for applying images is kept outside of feathers. If you wish to override these rules, copy them from the application source code into the images.css file in your feathers. If all you wish to do is simply change the images applied, you can just substitute new images into the chrome/skin directory on top of the old images. As long as the dimensions are the same - no CSS will need to be modified.

Creating Additional Rules

Determining which CSS rules apply to an interface element can be confusing. To help with this, there is an add-on called DOM Inspector, which enables you to explore the structure of XUL documents and view the CSS rules that apply to each element.

You can start DOM Inspector from the Tools menu.

To inspect the Nightingale interface, select File > Inspect Chrome Document > [Document] from the DOM Inspector menu. Note that [Document] may change, and that you may need to try several items before you find the right window. When you have the correct window selected, the address bar should read chrome://gonzo/content/xul/mainplayer.xul (if you're using the default Gonzo Feather) The left pane of the DOM Inspector shows the structure of the Nightingale window. Double-click the elements in the list to open and close them.

The right pane shows information about the node selected in the left pane. Use the selector at the top of the right pane to determine what information is displayed. Selecting “CSS Style Rules” will show you the rules that apply to the current node and the order in which they appear.

The select button in the top left corner of the toolbar is used to jump directly to an element in the interface. Click the select button, then click on an element in the Nightingale interface. The left pane of the DOM Inspector should immediately show the location of the clicked element.

For more information, see the MozillaZine DOM Inspector article.

Mozilla CSS

Mozilla has added several useful extensions to CSS that can be used in Nightingale. For example:

  • -moz-border-radius applies rounded corners to an element without using any images.
  • You can use the -moz-image-region style to display a region of an image.
  • The Mozilla color style supports an opacity parameter, which enables you to make layout elements translucent.
  • The -moz-appearance style displays a user interface control according in the client operating system's native style. This gives you the ability to display controls such as buttons, toolbars and scroll bars in a way that users expect based on their operating system. Songbird's default skin removes the -moz-appearance setting which enables us to apply our own look and feel to the user interface; your CSS can do this as well.

Another feature to be aware of is the Mozilla ”!important” modifier. ”!important” is used to force a CSS value and override the normal specificity rules. If you are having trouble getting a rule to work, try adding ”!important”.

For example:

.faceplate-intro-image
{
	list-style-image: url(chrome://songbird/skin/yourLogo.png)  !important; 
}

A complete list of Mozilla CSS extensions is available here.

XBL Elements

Mozilla's eXtensible Binding Language (XBL) defines behaviors for XUL tags. You don't need to know anything about XBL to create feathers that change basic aspects of Nightingale's appearance, but to create feathers that make drastic changes to Nightingale's functionality and layout, you'll need to dive into XBL.

Concepts

XBL widgets can encapsulate a XUL tree, script, and event handling into a single element in a XUL document.

For example:

<button label="Hello" image="World.png" />

The behavior of this tag is defined by the CSS rule:

button {
	-moz-binding: url("button.xml#button");
}

This binds the following anonymous XUL content below the button tag:

<xul:hbox class="box-inherit button-box" align="center" pack="center" flex="1">
<xul:image class="button-icon" xbl:inherits="src=image"/>
<xul:label class="button-text" xbl:inherits="value=label,accesskey,crop"/>
</xul:hbox>

For more information visit The Mozilla Developer Center.

Nightingale Usage

Nightingale uses XBL to reuse functionality in different window layouts. For example, the <sb-player-artist-label /> tag provides a custom label that automatically displays the artist for the track that's currently playing.

You can apply styles to Nightingale's XBL widgets in your feathers. To learn more about Nightingale's XBL widgets, explore the existing XUL layouts, and the XBL source code.

Styling

Feathers have control over which stylesheets are loaded. This means that feathers use the default XBL styles bundled with Nightingale, or replace them as desired. Feathers can import styles found in chrome://songbird-bindings/skin/, selectively import from chrome://songbird-bindings/skin/ and override some of the styles, and use the chrome.manifest to specify that the feathers add-on contains a replacement provider for the http://songbird-bindings/skin/ package.

To replace the widget CSS, start by copying the existing rules and making modifications. If the existing rules do not meet your needs, use DOM Inspector to understand the structure of the widget and how to style it.

Layouts

In addition to images and CSS styles, feathers can provide XUL player window layouts and XBL elements (content). With an alternate layout you can create a new miniplayer mode, or completely redesign the main Nightingale window.

To add a layout to feathers, you can add XUL to the chrome/content folder, and then register it with a Songbird:Feathers block in the feather's install.rdf file. There is no documentation for this yet, so eager developers should look at the More Gonzo feathers for an example (it adds two layouts: Medium Player, and Main Alternate).

Sharing Your Feathers

To share your feathers with others, you must package them for distribution. Feathers are packaged in .xpi zip archives just like other Nightingale extensions. The simplest way to share your feathers is to create a zip file containing the contents of your feathers project, then rename the file to use a .xpi extension.

For example, in Windows:

  • Select chrome.manifest, install.rdf, and the chrome directory from your project
  • Right-click and choose Send To > Compressed (zipped) Folder
  • Rename the file from archive.zip to archive.xpi

You can install the new feathers by dragging the .xpi into Nightingale. You can share your feathers with others by uploading them to the Nightingale Add-ons wiki.

Note that you cannot have the test-mode version of your feathers and the packaged XPI version installed in the same profile at the same time. You should create a new profile before testing the packaged version of your feathers.

Troubleshooting

  • Open the Tools > Error Console menu item and look for warning messages.
  • Close and reopen Nightingale to make sure that nothing is being cached.
  • Confirm that your feathers are selected using the Feathers menu.
  • Open the Tools > Add-ons menu item and confirm that your add-on is installed. The wizard will create a test-mode pointer to install your feathers, but if your profile is cleared or you uninstall the add-on this file will be removed. You may need to manually recreate the test-mode file.
  • When packaging an XPI confirm that the root contains your chrome.manifest, install.rdf and chrome directory. If you accidentally place your manifest files in a subfolder the add-on will not load.
  • If you are installing a feathers XPI, double check that the feathers are not already installed. You will have to uninstall the test-mode version of your feathers before installing an XPI packaged version.
  • Compare your install.rdf to the Rubberducky versionanother add-on. Check for XML errors or inconsistencies that might stop Nightingale from loading your extension.
  • Changes to your install.rdf file may not be detected unless you delete the addon-metadata.rdf file in your Nightingale profile directory. Your profile is located at:
    • Mac OSX: /Users/[User Name]/Library/Application\ Support/Nightingale
    • Windows XP: C:\Documents and Settings\[User Name]\Application Data\Nightingale
    • Windows Vista: C:\users\[User Name]\AppData\Roaming\Nightingale
    • Linux: ~/.nightingale
  • If the CSS files appear to be filled with garbage, try using a different text editor. On OS X, try TextMate. On Windows, try MetaPad.

Additional Resources

developer_center/creating_feathers.txt · Last modified: 2015/05/11 13:40 by zjays