Getting Started

TomTom HOME is like Mozilla Firefox

Remember, TomTom HOME is like Mozilla Firefox. If you already have experience developing extensions for Firefox a lot of this will sound very familiar. There is also a lot of information on developing extensions on http://developer.mozilla.org/

Setting up your environment

Before you get started you need to install the latest version of TomTom HOME. Go here http://www.tomtom.com/home to download the latest version. Remember that for some functionality in TomTom HOME you will need a TomTom device.

After installing you need to make some adjustments to your installation. You will need the TomTom HOME Debug Menu and the DOM Inspector. These tools will help you access the error console and the DOM of you XUL pages.

Both these extensions can be downloaded from the Tools page.

Files and Folders

Every extension has a specific file and folder structure. Below you find the contents of a typical extension archive.

		
extension.xpi: 
	/install.rdf 
	/chrome.manifest
	/components/*
	/components/cmdline.js 
	/defaults/ 
	/defaults/preferences/*.js 
	/plugins/*
	/chrome/icons/default/* 
	/chrome/
	/chrome/content/

We will need a similar structure to get started. First create a folder on your hard drive that will hold the extension, like c:\tomtom\myextension. Inside your new extension folder, create another folder called chrome, and inside the chrome folder create a folder called content. You also have to create two empty text files in your extension folder, install.rdf and chrome.manifest. When you are done your file structure should look like this below:

/install.rdf
/chrome.manifest
/chrome/content
		

Create the install manifest

Open the file install.rdf and paste the following information 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>gettingstarted@tomtom.test</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
   
    <!-- Target Application this extension can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>home2@tomtom.com</em:id>
        <em:minVersion>2.1</em:minVersion>
        <em:maxVersion>2.4.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>Sample</em:name>
    <em:description>A test extension</em:description>
    <em:creator>Martijn Gerrits</em:creator>
    <em:homepageURL>http://create.tomtom.com</em:homepageURL>
  </Description>      
</RDF>
		

Some of the values above are example values and have to be changed to something that matches to your extension.

  • gettingstarted@tomtom.test - this is the ID of the extension, it has to be in the format of an email address but is does not have to be your e-mail or a valid email addess .
  • <em:type>2</em:type> - the 2 specifies that we are installing an extension. Other values can be found on http://developer.mozilla.org/en/Install_Manifests#type
  • home2@tomtom.com - this specifies that your extension is working with TomTom HOME.
  • 2.4 - the minimum version of Firefox you're saying this extension will work with. Set this as the minimum version you're going to commit to testing and fixing bugs with.
  • 2.4.* - 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, "2.4.*" indicates that the extension works with TomTom HOME 2.4 and any subsequent 2.4.x release.

Extending TomTom HOME with XUL

The user interface of TomTom HOME is written in XUL and JavaScript. XUL stands for XML User interface Language and is an XML grammar for describing the user interface of an application. We can modify the XUL based UI by adding and modifying widgets using an overlay.

XUL Overlays are a way of attaching other UI widgets to a XUL document at run time. A XUL Overlay is a .xul file that specifies XUL fragments to insert at specific merge points within a "master" document. These fragments can specify widgets to be inserted, removed, or modified.

Overlays need a merge point to identify the place where they have to be attached to the DOM of the XUL page. Below you see a part the TomTom HOME menu bar in XUL:

<toolbox id="main-toolbox" orient="horizontal">
  <menubar id="nav-menubar"/>
  <spacer flex="1"/>
  <ttloginbutton id="login-button"/>
</toolbox>
		

In this piece of XUL code the <menubar id="nav-menubar"> is the merge point for a XUL overlay

Example XUL overlay document

<?xml version="1.0"?>
<overlay id="sampleOverlay"
      xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <menubar id="nav-menubar">
    <menu id="nav-menubar-sample" label="Sample">
      <menupopup id="nav-menubar-sample-menupopup">
        <menuitem id="sample-menuitem-helloworld"
                  label="Hello World"
                  oncommand="alert('Hello World')" />
      </menupopup>
    </menu>
  </menubar>
</overlay>
		

The <menubar> called nav-menubar specifies the "merge point" within the HOME window that we want to attach to.

The <menu> child is a new menu with one menu item that we want to insert within the merge point.

Take this sample code above and save it into a new file called sample.xul inside the chrome/content folder you created.

Create a chrome manifest

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

Paste the line below in the file:

content     sample    chrome/content/

This specifies the:

  1. type of material within a chrome package
  2. name of the chrome package (make sure you use all lowercase characters for the package name ("sample"))
  3. location of the chrome packages' files

So, this line says that for a chrome package sample, we can find its content files at the location chrome/content which is a path relative to the location of chrome.manifest.

Register an Overlay

You need TomTom HOME to merge your overlay with the window whenever it displays one. So add this line to your chrome.manifest file:

overlay chrome://tthome/content/ui/overlays/menubarOverlay.xul chrome://sample/content/sample.xul

Test

Before we can test our extension we have to let TomTom HOME know where to find it. Normally when you install an extension from an XPI package TomTom HOME will copy it to its extension folder. Because we are not installing we need to place a file in the extension folder manually

  1. Find your profile folder, how to do that is described in Tools > The Profile Folder
  2. Go into the extensions folder
  3. Create an empty text file and give it the same name as you extensions. In our example this is gettingstarted@tomtom.test. Inside this file enter the path to the extension: c:/tomtom/myextension/ (Don't forget the trailing slash!)

Package

Before other people can use your extension you have to package it first. To package your extension you have to zip up the contents of your the myextension folder and then simply rename the .zip file to a .xpi file.

Further reading

More information on XUL
How to package an extension
More about chrome