mozilla

Revision 129883 of Building a Theme

  • Revision slug: Building_a_Theme
  • Revision title: Building a Theme
  • Revision id: 129883
  • Created:
  • Creator: jkinkead
  • Is current revision? No
  • Comment 92 words added, 109 words removed
Tags: 

Revision Content

Introduction

This tutorial will take you through the steps required to build a very basic theme - one which updates color of the text in the statusbar in Firefox.

Note This tutorial is about building themes for Firefox 3.0 and later.  Other tutorials exist for building themes for earlier versions of Firefox.  For an older tutorial, see Creating a Skin for Firefox.

Setting up the Development Environment

Themes and extensions are packaged and distributed in ZIP files or Bundles, with the XPI (pronounced “zippy”) file extension.

An example of the content within a typical XPI file for a theme:

example.xpi:
              /install.rdf
              /chrome.manifest
              /preview.png
              /icon.png
              /browser/
              /communicator/
              /global/
              /mozapps/

We'll want to create a file structure similar to the one above for our tutorial, so let's begin by creating a folder for your theme somewhere on your hard disk (e.g. C:\themes\my_theme\ or ~/themes/my_theme/).  Inside your new theme folder, create two new empty text files, one called chrome.manifest and the other called install.rdf.  The file preview.png is shown as a preview of the theme in the themes panel of the add-ons window.  The file icon.png is used as an icon in the same panel.  We'll leave both of them out for now, unless you have something picked out that you want to use.

The remaining directories will be extracted from the default theme.  First, you'll want to create a temporary directory located somewhere, called 'classic'.  Copy your Firefox installation's classic.jar into this directory.  This file's location differs by operating system:

Linux: /usr/lib/MozillaFirefox/chrome/classic.jar or /usr/lib/firefox-*.*.*/chrome/classic.jar

Windows: \Program Files\Mozilla Firefox\chrome\classic.jar

Mac OS X: /Applications/Firefox.app/Contents/MacOS/chrome/classic.jar

Now, unzip this file into the directory you created.  It contains two image files, plus a directory called skin.  Copy the four directories in skin/classic to the root of your theme directory.  This gives us a base set of styles to work with.

You should end up with this directory structure:

<ext path>/
          /install.rdf
          /chrome.manifest
          /browser/
          /communicator/
          /global/
          /mozapps/


After this, it would be a good idea to read the article Setting up extension development environment and follow the directions there.  It's especially important to install the DOM Inspector, which we'll be using in later steps.

Create the Install Manifest

Open the file called install.rdf that you created at the top of your extension's folder hierarchy and put this inside:

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>sample@example.net</em:id>
    <em:version>1.0</em:version>
    <em:type>4</em:type>
   
    <!-- Target Application this theme can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>3.0</em:minVersion>
        <em:maxVersion>3.5.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>My Theme</em:name>
    <em:internalName>sample</em:internalName>
    <em:description>A test extension</em:description>
    <em:creator>Your Name Here</em:creator>
    <em:homepageURL>http://www.example.com/</em:homepageURL>
  </Description>      
</RDF>
  • sample@example.net - the ID of the extension.  This is a value you come up with to identify your extension in email address format (note that it should not be your email).  Make it unique.  You could also use a GUID.  NOTE: This parameter MUST be in the format of an email address, although it does NOT have to be a valid email address.  (example.example.example)
  • 4 - the type of the add-on.  '4' declares that it is installing a theme.  If you were to install an extension it would be 2 (see Install Manifests#type for other type codes).
  • {ec8030f7-c20a-464f-9b0e-13a3a9e97384} - Firefox's application ID.
  • 3.0 - the exact version number of the earliest version of Firefox you're saying this extension will work with. Never use a * in a minVersion, it almost certainly will not do what you expect it to.
  • 3.5.* - the maximum version of Firefox you're saying this extension will work with.  Set this to be no newer than the newest currently available version!  In this case, "3.5.*" indicates that the extension works with Firefox 3.5 and any subsequent 3.5.x release.

If you get a message that the install.rdf is malformed, it is helpful to load it into firefox using the File->Open File command and it will report xml errors to you.

Themes designed to work with Firefox 3.0.0.x at the latest should set the maximum version to "3.0.0.*".

See Install Manifests for a complete listing of the required and optional properties.

Save the file.

Styling the Browser's UI with CSS

Firefox's user interface is written in XUL and JavaScript.  XUL is an XML grammar that provides user interface widgets like buttons, menus, toolbars, trees, etc.  User actions are bound to functionality using JavaScript.  These XUL elements are styled using CSS.  If you don't know CSS, it's going to be a steep learning curve, and you may want to try some HTML-based tutorials to start with.

The browser UI has absolutely no styling on its own - if you try to start up with an empty theme, Firefox will be unusable, as the button elements will be drawn as plain text.  This is why we copied the default styles in the setup step.

When writing a theme, the easiest way to determine what CSS selectors you need to write is to use the DOM Inspector which you should have installed in the setup step.  You can use this to inspect any element in a web page or an XUL document, which makes it invaluable for themes.

Updating the Statusbar's Styling

Open up the DOM Inspector now (located under the "Tools" menu), and go to "File->Inspect Chrome Document".  This will be a menu containing all the XUL documents currently open in Firefox.  Pick the first document with a web page title, like "Mozilla Firefox Start Page" and select it.  For this tutorial, we're going to update the styling of the status bar (the bar at the bottom of each web page).  Select the node finding tool (the arrow-plus-box in the top-left corner of the DOM Inspector), and click on the "Done" message in the status bar for the web page you're inspecting.  This should select a node of type "xul:label" in the DOM Inspector.

From here, you can play around with various different stylings for the status bar and associated elements.  By default, the right pane should show the DOM node, which has useful styling information like the CSS class and node id.  The label element itself is of class statusbarpanel-text, with no idea.  To change its style within our theme, we need to write a selector rule to select this class.

Open up the file browser/browser.css in your theme.  Search this file for the .statusbarpanel-text selector, and add a color: red; rule to it.

Save the file.

Chrome URIs

Next, we have to tell Firefox where to find the theme files for your theme.  CSS, XUL, and other files are part of "Chrome Packages" - bundles of user interface components which are loaded via chrome:// URIs.  Rather than load the browser from disk using a file:// URI (since the location of Firefox on the system can change from platform to platform and system to system), Mozilla developers came up with a solution for creating URIs to content that the installed add-on knows about.

The browser window is: chrome://browser/content/browser.xul. Try typing this URL into the location bar in Firefox!

Chrome URIs consist of several components:

  • Firstly, the URI scheme (chrome) which tells Firefox's networking library that this is a Chrome URI.  It indicates that the content of the URI should be handled as a (chrome).  Compare (chrome) to (http) which tells Firefox to treat the URI as a web page.
  • Secondly, a package name (in the example above, browser) which identifies the bundle of user interface components.
  • Thirdly, the type of data being requested.  There are three types: content (XUL, JavaScript, XBL bindings, etc. that form the structure and behavior of an application UI), locale (DTD, .properties files etc that contain strings for the UI's localization), and skin (CSS and images that form the theme of the UI)
  • Finally, the path of a file to load.

So, chrome://foo/skin/bar.png  loads the file bar.png from the foo theme's skin section.

When you load content using a Chrome URI, Firefox uses the Chrome Registry to translate these URIs into the actual source files on disk (or in JAR packages).

Create a Chrome Manifest

The Chrome Manifest is the file that maps these Chrome URIs to your theme's files.  For more information on Chrome Manifests and the properties they support, see the Chrome Manifest Reference.

Open the file called chrome.manifest that you created alongside the chrome directory at the root of your extension's source folder hierarchy.

Add in this code:

skin    browser         sample    browser/
skin    communicator    sample    communicator/
skin    global          sample    global/
skin    mozapps         sample    mozapps/

Don't forget the trailing slash, "/"!  Without it, the package won't be registered.  The third column needs to match your theme's internalName value from the install manifest above.

This maps skin directories to locations within your theme.  For example, the line skin browser sample skin/browser/ means "when the user has the sample theme selected, use the directory browser/ to look up skins for the browser package."  More concisely, this means that the URL chrome://browser/skin/some/path/file.css will look for a file browser/some/path/file.css in your theme's root directory.

Save the file.

Test

First, we need to tell Firefox about your theme. During the development phase for Firefox versions 2.0 and higher, you can point Firefox to the folder where you are developing the theme, and it'll load it up every time you restart Firefox.

  1. Locate your profile folder and beneath it the profile you want to work with (e.g. Firefox/Profiles/<profile_id>.default/).
  2. Open the extensions/ folder, creating it if need be.
  3. Create a new text file and put the full path to your development folder inside (e.g. C:\themes\my_theme\ or ~/themes/my_theme/). Windows users should retain the OS' slash direction, and everyone should remember to include a closing slash and remove any trailing spaces.
  4. Save the file with the id of your theme as its name (e.g. sample@example.net). No file extension.

Now you should be ready to test your theme!

Start Firefox. Firefox will detect the text link to your theme directory and install the theme. When the browser window appears you should see the theme dialog open.  Your theme will not be active the first time you install, and you will need to click "Use Theme" and restart before you can see your change.  After it restarts this second time, you should see the "Done" message - and any other statusbar messages - displayed in red instead of black.

You can now go back and make additional changes to your css files, close and restart Firefox, and see the updates.

Package

Now that your theme works, you can package it for deployment and installation.

Zip up the contents of your theme's folder (not the theme folder itself), and rename the zip file to have a .xpi extension. In Windows XP, you can do this easily by selecting all the files and subfolders in your extension folder, right click and choose "Send To -> Compressed (Zipped) Folder". A .zip file will be created for you. Just rename it and you're done!

On Mac OS or Linux, you can use the command-line zip tool:

 

zip -r my_theme.xpi install.rdf chrome.manifest browser communicator global mozapps

Note: The command-line tool will update an existing zip file, not replace it - so if you have files you've deleted from your theme, be sure to remove the .xpi file before running the zip command again.

If you have the 'Extension Builder' extension installed it can compile the .xpi file for you (Tools -> Extension Developer -> Extension Builder). Merely navigate to the directory where your extension is (install.rdf etc.), and hit the Build Extension button. This extension has a slew of tools to make development easier.

Now upload the .xpi file to your server, making sure it's served as application/x-xpinstall. You can link to it and allow people to download and install it. For the purposes of just testing our .xpi file we can just drag it into the extensions window via "Tools -> Add-ons", or open it using "File -> Open File...".

Installing from a web page

There are a variety of ways you can install extensions from web pages, including direct linking to the XPI files and using the InstallTrigger object. Extension and web authors are encouraged to use the InstallTrigger method to install XPIs, as it provides the best experience to users.

Using addons.mozilla.org

Mozilla Add-ons is a distribution site where you can host your theme for free. Your theme will be hosted on Mozilla's mirror network to guarantee your download even though it might be very popular. Mozilla's site also provides users easier installation, and will automatically make your newer versions available to users of your existing versions when you upload them. In addition Mozilla Add-ons allows users to comment and provide feedback on your theme. It is highly recommended that you use Mozilla Add-ons to distribute your themes!

Visit http://addons.mozilla.org/developers/ to create an account and begin distributing your themes!

Note: Your theme will be passed faster and downloaded more if you have a good description and some screenshots of the theme in action.

Registering Add-ons in the Windows Registry

On Windows, information about add-ons can be added to the registry, and the updates will automatically be picked up the next time the applications starts. This allows application installers to easily add integration hooks as extensions. See Adding Extensions using the Windows Registry for more information.

Further information

______________________________

Revision Source

<h4 class="editable"><span>Introduction</span></h4>
<p>This tutorial will take you through the steps required to build a very basic <a class="internal" href="/en/Themes" title="en/Themes">theme</a> - one which updates color of the text in the statusbar in Firefox.</p>
<div class="note">
<p><strong>Note</strong> This tutorial is about building themes for Firefox 3.0 and later.  Other tutorials exist for building themes for earlier versions of Firefox.  For an older tutorial, see <a class="internal" href="/en/Creating_a_Skin_for_Firefox//Getting_Started" title="en/Creating a Skin for Firefox//Getting Started">Creating a Skin for Firefox</a>.</p>
</div>
<div id="section_2">
<h4 class="editable"><span>Setting up the Development Environment</span></h4>
<p>Themes and extensions are packaged and distributed in ZIP files or <a href="../../../../en/Bundles" rel="internal">Bundles</a>, with the <code>XPI</code> (<em>pronounced “zippy”</em>) file extension.</p>
<p>An example of the content within a typical XPI file for a theme:</p>
<pre class="eval">example.xpi:
              /<a href="../../../../en/Install_Manifests" rel="internal">install.rdf</a>
              /<a href="../../../../en/Chrome_Registration" rel="internal">chrome.manifest</a>
              /preview.png
              /icon.png
              /browser/
              /communicator/
              /global/
              /mozapps/

</pre>
<p>We'll want to create a file structure similar to the one above for our tutorial, so let's begin by creating a folder for your theme somewhere on your hard disk (e.g. <code>C:\themes\my_theme\</code> or <code>~/themes/my_theme/</code>).  Inside your new theme folder, create two new empty text files, one called <code>chrome.manifest</code> and the other called <code>install.rdf</code>.  The file <code>preview.png</code> is shown as a preview of the theme in the themes panel of the add-ons window.  The file <code>icon.png</code> is used as an icon in the same panel.  We'll leave both of them out for now, unless you have something picked out that you want to use.</p>
<p>The remaining directories will be extracted from the default theme.  First, you'll want to create a temporary directory located somewhere, called 'classic'.  <strong>Copy</strong> your Firefox installation's <code>classic.jar</code> into this directory.  This file's location differs by operating system:</p>
<p><strong>Linux:</strong> <code>/usr/lib/MozillaFirefox/chrome/classic.jar</code> <em>or</em> <code>/usr/lib/firefox-*.*.*/chrome/classic.jar</code></p>
<p><strong>Windows:</strong> <code>\Program Files\Mozilla Firefox\chrome\classic.jar</code></p>
<p><strong>Mac OS X: </strong><code>/Applications/Firefox.app/Contents/MacOS/chrome/classic.jar</code></p>
<p>Now, unzip this file into the directory you created.  It contains two image files, plus a directory called <code>skin</code>.  Copy the four directories in <code>skin/classic</code> to the root of your theme directory.  This gives us a base set of styles to work with.</p>
<p>You should end up with this directory structure:</p>
<pre>&lt;ext path&gt;/
          /install.rdf
          /chrome.manifest
          /browser/
          /communicator/
          /global/
          /mozapps/


</pre>
<p>After this, it would be a good idea to read the article <a href="../../../../en/Setting_up_extension_development_environment" rel="internal">Setting up extension development environment</a> and follow the directions there.  It's especially important to install the <a class="internal" href="/en/DOM_Inspector" title="en/DOM Inspector">DOM Inspector</a>, which we'll be using in later steps.</p>
</div>
<div id="section_3">
<h4 class="editable"><span>Create the Install Manifest</span></h4>
<p>Open the file called <code><a href="../../../../en/Install_Manifests" rel="internal">install.rdf</a></code> that you created at the top of your extension's folder hierarchy and put this inside:</p>
<pre class="eval">&lt;?xml version="1.0"?&gt;

&lt;RDF xmlns="<a class=" external" href="http://www.w3.org/1999/02/22-rdf-syntax-ns#" rel="freelink">http://www.w3.org/1999/02/22-rdf-syntax-ns#</a>"
     xmlns:em="<a class=" external" href="http://www.mozilla.org/2004/em-rdf#" rel="freelink">http://www.mozilla.org/2004/em-rdf#</a>"&gt;

  &lt;Description about="urn:mozilla:install-manifest"&gt;
    &lt;em:id&gt;<strong><a class=" link-mailto" href="mailto:sample@example.net" rel="external nofollow" target="_blank" title="mailto:sample@example.net">sample@example.net</a></strong>&lt;/em:id&gt;
    &lt;em:version&gt;<strong>1.0</strong>&lt;/em:version&gt;
    &lt;em:type&gt;<strong>4</strong>&lt;/em:type&gt;
   
    &lt;!-- Target Application this theme can install into, 
         with minimum and maximum supported versions. --&gt; 
    &lt;em:targetApplication&gt;
      &lt;Description&gt;
        &lt;em:id&gt;<strong>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</strong>&lt;/em:id&gt;
        &lt;em:minVersion&gt;<strong>3.0</strong>&lt;/em:minVersion&gt;
        &lt;em:maxVersion&gt;<strong>3.5.*</strong>&lt;/em:maxVersion&gt;
      &lt;/Description&gt;
    &lt;/em:targetApplication&gt;
   
    &lt;!-- Front End MetaData --&gt;
    &lt;em:name&gt;<strong>My Theme</strong>&lt;/em:name&gt;
    &lt;em:internalName&gt;<strong>sample</strong>&lt;/em:internalName&gt;
    &lt;em:description&gt;<strong>A test extension</strong>&lt;/em:description&gt;
    &lt;em:creator&gt;<strong>Your Name Here</strong>&lt;/em:creator&gt;
    &lt;em:homepageURL&gt;<strong><a class=" external" href="http://www.example.com/" rel="freelink">http://www.example.com/</a></strong>&lt;/em:homepageURL&gt;
  &lt;/Description&gt;      
&lt;/RDF&gt;
</pre>
<ul> <li><strong><a class=" link-mailto" href="mailto:sample@example.net" rel="external nofollow" target="_blank" title="mailto:sample@example.net">sample@example.net</a></strong> - the ID of the extension.  This is a value you come up with to identify your extension in email address format (note that it should not be <em>your</em> email).  Make it unique.  You could also use a GUID.  NOTE: This parameter MUST be in the format of an email address, although it does NOT have to be a valid email address.  (example.example.example)</li> <li><strong>4 </strong>- the type of the add-on.  '4' declares that it is installing a theme.  If you were to install an extension it would be 2 (see <a href="../../../../en/Install_Manifests#type" rel="internal">Install Manifests#type</a> for other type codes).</li> <li><strong>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</strong> - Firefox's application ID.</li> <li><strong>3.0</strong> - the exact version number of the earliest version of Firefox you're saying this extension will work with. Never use a * in a minVersion, it almost certainly will not do what you expect it to.</li> <li><strong>3.5.*</strong> - the maximum version of Firefox you're saying this extension will work with.  Set this to be no newer than the newest currently available version!  In this case, "3.5.*" indicates that the extension works with Firefox 3.5 and any subsequent 3.5.x release.</li>
</ul>
<p>If you get a message that the install.rdf is malformed, it is helpful to load it into firefox using the File-&gt;Open File command and it will report xml errors to you.</p>
<p>Themes designed to work with Firefox 3.0.0.x at the latest should set the maximum version to "3.0.0.*".</p>
<p>See <a href="../../../../en/Install_Manifests" rel="internal">Install Manifests</a> for a complete listing of the required and optional properties.</p>
<p>Save the file.</p>
</div>
<div id="section_4">
<h4 class="editable">Styling the Browser's UI with CSS</h4>
<p>Firefox's user interface is written in XUL and JavaScript.  <a href="../../../../en/XUL" rel="internal">XUL</a> is an XML grammar that provides user interface widgets like buttons, menus, toolbars, trees, etc.  User actions are bound to functionality using JavaScript.  These XUL elements are styled using <a class="internal" href="/en/CSS" title="en/CSS">CSS</a>.  If you don't know CSS, it's going to be a steep learning curve, and you may want to try some HTML-based tutorials to start with.</p>
<p>The browser UI has absolutely no styling on its own - if you try to start up with an empty theme, Firefox will be unusable, as the button elements will be drawn as plain text.  This is why we copied the default styles in the setup step.</p>
<p>When writing a theme, the easiest way to determine what CSS selectors you need to write is to use the DOM Inspector which you should have installed in the setup step.  You can use this to inspect any element in a web page or an XUL document, which makes it invaluable for themes.</p>
<h4 class="editable">Updating the Statusbar's Styling</h4>
<p>Open up the DOM Inspector now (located under the "Tools" menu), and go to "File-&gt;Inspect Chrome Document".  This will be a menu containing all the XUL documents currently open in Firefox.  Pick the first document with a web page title, like "Mozilla Firefox Start Page" and select it.  For this tutorial, we're going to update the styling of the status bar (the bar at the bottom of each web page).  Select the node finding tool (the arrow-plus-box in the top-left corner of the DOM Inspector), and click on the "Done" message in the status bar for the web page you're inspecting.  This should select a node of type "xul:label" in the DOM Inspector.</p>
<p>From here, you can play around with various different stylings for the status bar and associated elements.  By default, the right pane should show the DOM node, which has useful styling information like the CSS class and node id.  The label element itself is of class <code>statusbarpanel-text</code>, with no idea.  To change its style within our theme, we need to write a selector rule to select this class.</p>
<p>Open up the file <code>browser/browser.css</code> in your theme.  Search this file for the <code>.statusbarpanel-text</code> selector, and add a<code> color: red; </code>rule to it.</p>
<p>Save the file.</p>
</div>
<div id="section_6">
<h4 class="editable"><span>Chrome URIs</span></h4>
<p>Next, we have to tell Firefox where to find the theme files for your theme.  CSS, XUL, and other files are part of "<a href="../../../../en/Chrome_Registration" rel="internal">Chrome Packages</a>" - bundles of user interface components which are loaded via <code><a class=" external" href="chrome://" rel="external nofollow" target="_blank" title="chrome://">chrome://</a></code> URIs.  Rather than load the browser from disk using a <code><a class=" external" href="file:///" rel="external nofollow" target="_blank" title="file://">file://</a></code> URI (since the location of Firefox on the system can change from platform to platform and system to system), Mozilla developers came up with a solution for creating URIs to content that the installed add-on knows about.</p>
<p>The browser window is: <code><a class=" external" href="chrome://browser/content/browser.xul" rel="external nofollow" target="_blank" title="chrome://browser/content/browser.xul">chrome://browser/content/browser.xul</a></code>. Try typing this URL into the location bar in Firefox!</p>
<p>Chrome URIs consist of several components:</p>
<ul> <li>Firstly, the <strong>URI scheme</strong> (<code>chrome</code>) which tells Firefox's networking library that this is a Chrome URI.  It indicates that the content of the URI should be handled as a (<code>chrome</code>).  Compare (<code>chrome</code>) to (<code>http</code>) which tells Firefox to treat the URI as a web page.</li> <li>Secondly, a package name (in the example above, <code><strong>browser</strong></code>) which identifies the bundle of user interface components.</li> <li>Thirdly, the type of data being requested.  There are three types: <code>content</code> (XUL, JavaScript, XBL bindings, etc. that form the structure and behavior of an application UI), <code>locale</code> (DTD, .properties files etc that contain strings for the UI's <a href="../../../../en/Localization" rel="internal">localization</a>), and <code>skin</code> (CSS and images that form the <a href="../../../../en/Themes" rel="internal">theme</a> of the UI)</li> <li>Finally, the path of a file to load.</li>
</ul>
<p>So, <code><a class=" external" href="chrome://foo/skin/bar.png" rel="external nofollow" target="_blank" title="chrome://foo/skin/bar.png">chrome://foo/skin/bar.png</a></code>  loads the file <code>bar.png</code> from the <code>foo</code> theme's <code>skin</code> section.</p>
<p>When you load content using a Chrome URI, Firefox uses the Chrome Registry to translate these URIs into the actual source files on disk (or in JAR packages).</p>
</div>
<div id="section_7">
<h4 class="editable"><span>Create a Chrome Manifest</span></h4>
<p>The Chrome Manifest is the file that maps these Chrome URIs to your theme's files.  For more information on Chrome Manifests and the properties they support, see the <a href="../../../../en/Chrome_Registration" rel="internal">Chrome Manifest</a> Reference.</p>
<p>Open the file called <strong>chrome.manifest</strong> that you created alongside the <code>chrome</code> directory at the root of your extension's source folder hierarchy.</p>
<p>Add in this code:</p>
<pre class="eval">skin    browser         sample    browser/
skin    communicator    sample    communicator/
skin    global          sample    global/
skin    mozapps         sample    mozapps/
</pre>
<p><strong>Don't forget the</strong><strong> trailing slash, "<code>/</code>"!</strong>  Without it, the package won't be registered.  The third column needs to match your theme's <strong>internalName</strong> value from the install manifest above.</p>
<p>This maps skin directories to locations within your theme.  For example, the line <code>skin browser sample skin/browser/</code> means "when the user has the <code>sample</code> theme selected, use the directory <code>browser/</code> to look up skins for the <code>browser</code> package."  More concisely, this means that the URL <a class="internal" href="/chrome://browser/skin/some/path/file.css" title="chrome://browser/skin/some/path/file.css">chrome://browser/skin/some/path/file.css</a> will look for a file <code>browser/some/path/file.css</code> in your theme's root directory.</p>
<p>Save the file.</p>
</div>
<div id="section_9">
<h4 class="editable"><span>Test</span></h4>
<p>First, we need to tell Firefox about your theme. During the development phase for Firefox versions 2.0 and higher, you can point Firefox to the folder where you are developing the theme, and it'll load it up every time you restart Firefox.</p>
<ol> <li>Locate your <a class="external" href="http://kb.mozillazine.org/Profile_folder" rel="external nofollow" target="_blank" title="http://kb.mozillazine.org/Profile_folder">profile folder</a> and beneath it the profile you want to work with (e.g. <code>Firefox/Profiles/&lt;profile_id&gt;.default/</code>).</li> <li>Open the <code>extensions/</code> folder, creating it if need be.</li> <li>Create a new text file and put the full path to your development folder inside (e.g. <code>C:\themes\my_theme\</code> or <code>~/themes/my_theme/)</code>. Windows users should retain the OS' slash direction, and <em>everyone</em> should remember to <strong>include</strong> a closing slash and <strong>remove</strong> any trailing spaces.</li> <li>Save the file with the id of your theme as its name (e.g. <code><a class=" link-mailto" href="mailto:sample@example.net" rel="external nofollow" target="_blank" title="mailto:sample@example.net">sample@example.net</a></code>). No file extension.</li>
</ol>
<p>Now you should be ready to test your theme!</p>
<p>Start Firefox. Firefox will detect the text link to your theme directory and install the theme. When the browser window appears you should see the theme dialog open.  Your theme will not be active the first time you install, and you will need to click "Use Theme" and restart before you can see your change.  After it restarts this second time, you should see the "Done" message - and any other statusbar messages - displayed in red instead of black.</p>
<p>You can now go back and make additional changes to your css files, close and restart Firefox, and see the updates.</p>
</div>
<div id="section_10">
<h4 class="editable"><span>Package</span></h4>
<p>Now that your theme works, you can <a href="../../../../en/Extension_Packaging" rel="internal">package</a> it for deployment and installation.</p>
<p>Zip up the <strong>contents</strong> of your theme's folder (not the theme folder itself), and rename the zip file to have a .xpi extension. In Windows XP, you can do this easily by selecting all the files and subfolders in your extension folder, right click and choose "Send To -&gt; Compressed (Zipped) Folder". A .zip file will be created for you. Just rename it and you're done!</p>
<p>On Mac OS or Linux, you can use the command-line zip tool:</p>
<p> </p>
<pre class="eval">zip -r my_theme.xpi install.rdf chrome.manifest browser communicator global mozapps
</pre>
<p><strong>Note:</strong> The command-line tool will <strong>update</strong> an existing zip file, not replace it - so if you have files you've deleted from your theme, be sure to remove the <code>.xpi </code>file before running the zip command again.</p>
<p>If you have the 'Extension Builder' extension installed it can compile the .xpi file for you (Tools -&gt; Extension Developer -&gt; Extension Builder). Merely navigate to the directory where your extension is (install.rdf etc.), and hit the Build Extension button. This extension has a slew of tools to make development easier.</p>
<p>Now upload the .xpi file to your server, making sure it's served as <code>application/x-xpinstall</code>. You can link to it and allow people to download and install it. For the purposes of just testing our .xpi file we can just drag it into the extensions window via "Tools -&gt; Add-ons", or open it using "File -&gt; Open File...".</p>
<div id="section_11">
<h5 class="editable"><span>Installing from a web page</span></h5>
<p>There are a variety of ways you can install extensions from web pages, including direct linking to the XPI files and using the InstallTrigger object. Extension and web authors are encouraged to use the <a href="../../../../en/Installing_Extensions_and_Themes_From_Web_Pages" rel="internal"> InstallTrigger method</a> to install XPIs, as it provides the best experience to users.</p>
</div>
<div id="section_12">
<h5 class="editable"><span>Using addons.mozilla.org</span></h5>
<p>Mozilla Add-ons is a distribution site where you can host your theme for free. Your theme will be hosted on Mozilla's mirror network to guarantee your download even though it might be very popular. Mozilla's site also provides users easier installation, and will automatically make your newer versions available to users of your existing versions when you upload them. In addition Mozilla Add-ons allows users to comment and provide feedback on your theme. It is highly recommended that you use Mozilla Add-ons to distribute your themes!</p>
<p>Visit <a class=" external" href="http://addons.mozilla.org/developers/" rel="external nofollow" target="_blank" title="http://addons.mozilla.org/developers/">http://addons.mozilla.org/developers/</a> to create an account and begin distributing your themes!</p>
<p><em>Note:</em> Your theme will be passed faster and downloaded more if you have a good description and some screenshots of the theme in action.</p>
</div>
<div id="section_13">
<h5 class="editable"><span>Registering Add-ons in the Windows Registry</span></h5>
<p>On Windows, information about add-ons can be added to the registry, and the updates will automatically be picked up the next time the applications starts. This allows application installers to easily add integration hooks as extensions. See <a href="../../../../en/Adding_Extensions_using_the_Windows_Registry" rel="internal">Adding Extensions using the Windows Registry</a> for more information.</p>
</div></div>
<div id="section_21">
<h4>Further information</h4>
<div id="section_23">
<ul> <li><a class="internal" href="/en/Themes" title="en/Themes">Themes</a></li>
</ul>
<p>______________________________</p>
</div>
</div>
Revert to this revision