Mozilla development
there is no data, there is only xul

Update by Laurent Jouanneau <laurent@xulfr.org>

XUL Overview

~~Introduction~~ — see part1 ⇒ http://kazhack.org/xpt/comete-xul.zip
Developer profile
Chrome URLs
Chrome manifests
Chrome packages
XPI extensions
XUL applications

Developer Profile

Where is Firefox?

Windows          "C:\%ProgramFiles%\Mozilla Firefox\firefox.exe"
Windows (64bit)  "C:\%ProgramFiles(x86)%\Mozilla Firefox\firefox.exe"
MacOS X          /Applications/Firefox.app/Contents/MacOS/firefox-bin
Linux            /usr/bin/firefox -no-remote -profile ~/.xul

Starting Firefox with a specific profile:

<firefox> -no-remote -profile C:\[…]\_xul

Creating a specific profile: -CreateProfile profilename
```
<firefox> -no-remote -CreateProfile dev
```
Start Firefox with a registered profile: -P dev
```
<firefox> -no-remote -P dev
```

Developer Profile

Install Firebug and DOM Inspector

Check the important files in this profile directory:

xxxxxxxx.default/
    chrome/
    extensions/
        comete@mozilla.org/                   <-- your futur extension
        firebug@software.joehewitt.com/
        inspector@mozilla.org/
    compreg.dat
    extensions.cache
    prefs.js                                  <-- your preferences

“proxy” your extension directory

Developer Preferences (about:config)

Add these prefs with about:config:

Log errors in chrome files to the Error Console:
```
javascript.options.showInConsole = true
```
Disables the XUL cache so that changes to windows and dialogs do not require a restart. This assumes you're using directories rather than JARs. Changes to XUL overlays will still require reloading of the document overlaid.
```
nglayout.debug.disable_xul_cache = true
```
```
nglayout.debug.disable_xul_fastload = true      (for Gecko 2.0 / Firefox 4+)
```
Enables the use of the dump() statement to print to the standard console:
```
browser.dom.window.dump.enabled = true
```
Enables strict JavaScript warnings in the Error Console:
```
javascript.options.strict = true
```
Send more detailed information about installation and update problems to the Error Console
```
extensions.logging.enabled = true
```

Developer Preferences (prefs.js)

Alternative: add these lines to %profile%/prefs.js

      user_pref("browser.dom.window.dump.enabled",     true);
      user_pref("extensions.logging.enabled",          true);
      user_pref("javascript.options.strict",           true);
      user_pref("javascript.options.showInConsole",    true);
      user_pref("nglayout.debug.disable_xul_cache",    true);
      user_pref("nglayout.debug.disable_xul_fastload", true);

warning: don't touch %profile%/prefs.js while Firefox is running!

More details on MDN: Setting up an extension development environment.

Questions?

Chrome URLs

Security: content in remote sources (e.g. http://localhost/~username)
are limited in the type of operations they can perform
Mozilla provides a way to install content locally
and register in in the chrome system
chrome URLs get elevated privileges to access local files, prefs, bookmarks…

syntax:

chrome://[package_name]/[part]/[file.xul]

chrome://browser/content/

Firefox, Thunderbird and others are accessible through chrome URLs
Chrome registration is done with a manifest file

Chrome Manifests

Packages
- = sets of XUL files and scripts that define a User Interface
- can be stored either as a directory or as a *.JAR archive
- can be installed into Mozilla and referenced with chrome URLs
(Firefox 3.x) the “chrome” directory is parsed at startup time
=> *.manifest files map chrome packages to disk locations

Simple syntax:

content [package] [location]

content comete    chrome/content/

Real case: browser.manifest in Firefox 3.6

content  branding  jar:browser.jar!/content/branding/   xpcnativewrappers=yes
content  browser   jar:browser.jar!/content/browser/    xpcnativewrappers=yes contentaccessible=yes
overlay  chrome://browser/content/browser.xul               chrome://browser/content/safebrowsing/report-phishing-overlay.xul
overlay  chrome://global/content/console.xul                chrome://browser/content/jsConsoleOverlay.xul
overlay  chrome://global/content/viewPartialSource.xul      chrome://browser/content/viewSourceOverlay.xul
overlay  chrome://global/content/viewSource.xul             chrome://browser/content/viewSourceOverlay.xul
overlay  chrome://mozapps/content/downloads/downloads.xul   chrome://browser/content/downloadManagerOverlay.xul
overlay  chrome://mozapps/content/extensions/extensions.xul chrome://browser/content/extensionsManagerOverlay.xul
overlay  chrome://mozapps/content/update/updates.xul        chrome://browser/content/softwareUpdateOverlay.xul
override chrome://global/content/license.html               chrome://browser/content/license.html
style    chrome://global/content/customizeToolbar.xul       chrome://browser/content/browser.css
style    chrome://global/content/customizeToolbar.xul       chrome://browser/skin/

Chrome Packages

content: windows and scripts

browser.jar
content/
   browser/
      browser.xul
      browser.js
      -- other browser XUL and JS files go here --
      bookmarks/
         -- bookmarks files go here --
      preferences/
         -- preferences files go here --

skin: stylesheets and images

classic.jar
skin/
   classic/
      browser/
         browser.css
         -- other browser skin files go here --
      global/
         -- global skin files go here --

locale: *.dtd and *.properties files
```
en-US.jar
        
```

XPI Extension Structure

example:

exampleExt.xpi:
    chrome/
        content/
        locales/
        skin/
    components/
        components/cmdline.js
    modules/
         myJSmodule.js
    defaults/
        preferences/*.js
    chrome.manifest
    install.rdf

install.rdf

install.rdf stores the extension’s metadata:

<?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>inspector@mozilla.org</em:id>
    <em:version>2.0.4</em:version>

    <em:targetApplication>
      <!-- Firefox -->
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>3.0a1</em:minVersion>
        <em:maxVersion>3.7a1pre</em:maxVersion>
      </Description>
    </em:targetApplication>

    <em:targetApplication>
      <!-- Thunderbird -->
      <Description>
        <em:id>{3550f703-e582-4d05-9a08-453d09bdfdc6}</em:id>
        <em:minVersion>3.0a1pre</em:minVersion>
        <em:maxVersion>3.1a1pre</em:maxVersion>
      </Description>
    </em:targetApplication>

    <!-- front-end metadata -->
    <em:name>DOM Inspector</em:name>
    <em:description>Inspects the structure and properties of a window and its
    contents.</em:description>
    <em:creator>mozilla.org</em:creator>
    <em:homepageURL>http://www.mozilla.org/projects/inspector/</em:homepageURL>

  </Description>
</RDF>

Bootstrapped extensions

restartless extensions
Provide a script bootstrap.js with some functions: startup(), shutdown(), install(), uninstall()
Each functions are called with an object for data, and an integer indicating the reason
Gecko 4 to 7: no more overlays. New elements should be added "by hand" by bootstrap.js
In install.rdf : <em:bootstrap>true</em:bootstrap>

XULRunner Applications

XULRunner apps and XPIs have a very similar file structure:

myApp/
    chrome/
        content/
            main.xul
        locale/
        skin/
    defaults/
        preferences/
            prefs.js
    application.ini
    chrome.manifest

The startup UI is defined in a pref:

pref("toolkit.defaultChromeURI", "chrome://myapp/content/main.xul");

application.ini links the application to XULRunner.
You can run your application with:
```
xulrunner application.ini
```
or with Firefox:
```
firefox -app application.ini
```

application.ini

[App]
Vendor=MIAGE Evry
Name=CoMETE
Version=0.1
BuildID=20101207
Copyright=Copyleft MIAGE Evry
ID=comete@mozilla.org

[Gecko]
MinVersion=1.8
MaxVersion=2.0.*

[XRE]
EnableExtensionManager=1
EnableProfileMigrator=0

[App] specifies metadata about the application
[Gecko] specifies what version of XULRunner is required
[XRE] enables specific XULRunner features

Chrome “Proxy”

download this archive: http://kazhack.org/xpt/comete-xul.zip

open the "browser.xul" file in Firefox

file:///[…]/chrome/content/browser.xul

⇒ #fail

Now let’s “proxy” this archive to get a chrome URL:

open your profile directory:
about:support ⇒ Profile Directory ⇒ click
open the "extensions" directory

create a "{%profile}/extensions/comete@mozilla.org" text file:

Windows        C:\full\path\to\comete@mozilla.org\
Mac/Linux      /full/path/to/comete@mozilla.org/

open the "browser.xul" file in Firefox
```
chrome://comete/content/browser.xul
```
⇒ #win

Congrats: you’ve just turned a XUL page into an extension! :-)

Questions?

XUL Overlays

Overlays are XUL files used to describe extra content in the UI.

Base file:

…
<menupopup id="menu_FilePopup">
  <menuitem label="New"/>
  <menuitem label="Open"/>
  <menuitem label="Save"/>
  <menuitem label="Close"/>
</menupopup>
…

Overlay:

<?xml version="1.0"?>
<overlay xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <menupopup id="menu_FilePopup">
    <menuitem label="Quit"/>
  </menupopup>
</overlay>

Result:

…
<menupopup id="menu_FilePopup">
  <menuitem label="New"/>
  <menuitem label="Open"/>
  <menuitem label="Save"/>
  <menuitem label="Close"/>
  <menuitem label="Quit"/>
</menupopup>
…

Overlays on Firefox

when designing an extension, there are three main places where you’d be likely to add a button:

in the main toolbar palette:

  <toolbarpalette id="BrowserToolbarPalette">
    <toolbarbutton […] />
  </toolbarpalette>

in the status bar:

  <statusbar id="status-bar">
    <statusbarpanel>
      <toolbarbutton […] />
    </statusbarpanel>
  </statusbar>

and in the main menu.

Use DOM Inspector to inspect the browser UI:

chrome://browser/content/

and find where you can attach overlays.

Placing Overlaid Elements

By default, overlaid elements are put at the end of the parent container.
These three attributes can help:

insertbefore(elementID)
insertafter(elementID)
position(ordinal)

Note #1: the values of insertbefore and insertafter can be comma-separated lists
⇒ the first matching id in the list is used to determine the position.

Note #2: overlays can also be used to remove elements
e.g. to remove the “about” menu entry:

<menupopup id="help-popup">
  <menuitem removeelement="true" id="help-about">
</menupopup>

Using Overlays

3 main reasons to use an overlay:

add new UI components
e.g. add a menuitem and a toolbar button with an add-on (extension)
override small pieces of a XUL file
e.g. replace a menu item by a sub-menu, or replace a XUL attribute
reuse particular pieces of the UI
e.g. that's how OK/Cancel buttons are defined in all dialog boxes

3 ways to load an overlay:

explicitely, by inserting a processing instruction before the DOCTYPE in the base file:
```
<?xul-overlay href="chrome://component/content/componentOverlay.xul"?>
```

dynamically, by adding a line in the chrome.manifest:

overlay chrome://URI-to-be-overlaid chrome://overlay-URI

at run-time, using the document.loadOverlay function
```
document.loadOverlay(url, observer);
```

Questions?

Keyboard shortcuts

attribute accesskey, containing the letter

accesskey="A" == ALT+A

            <menu label="test" accesskey="t">

<keyset>
  <key id="sample-key" modifiers="shift" key="R"/>
</keyset>

modifiers: alt, meta ("command" key), ctrl, shift, accel (depends on the platform)
keycode attribute, instead of key: the key code (VK_*). ex: VK_F5, VK_ENTER, VK_A (list of code)

key attribute on any element to link to the shortcut

            <menu label="test" key="sample-key" accesskey="t">

Windows

Opening a window

var win = window.open(url, name, features);

features:
- centerscreen, top, left, alwaysRaised
- menubar, toolbar, location, personalbar, status, titlebar
- resizable, scrollbars, close
- chrome, modal, dialog

Dialog

Opening a dialog

var dlg = window.openDialog(url, name, features, param1, param2, ...);

features: same as window.open. default: chrome,dialog
In the dialog, to retrieve parameters:
```
 var arg1 =  window.arguments[0]
```

to return value:

            var retVals = { address: null, delivery: null };
            openDialog("mydialog.xul", "dlg", "modal", "pizza", 6.98, retVals);

In the dialog:

            var ret = window.arguments[2];
            ret.address='avenue des champs';

Let’s see! :-)

to fire the table.xul window, add:

a button in the status bar
an entry in the “Tools” menu

…and register the overlay properly.

Bonuses:

in the statusbar, an icon is always good to see
the best place in the “Tools” menu to put an entry is between the “Add-ons” section and the “Private Browsing” one
rearrange table.xul so it looks nicer in its own window

Mozilla development there is no data, there is only xul

XUL Overview

Developer Profile

Developer Profile

Developer Preferences (about:config)

Developer Preferences (prefs.js)

Questions?

Chrome URLs

Chrome Manifests

Chrome Packages

XPI Extension Structure

install.rdf

Bootstrapped extensions

XULRunner Applications

application.ini

Chrome “Proxy”

Questions?

XUL Overlays

Overlays on Firefox

Placing Overlaid Elements

Using Overlays

Questions?

Keyboard shortcuts

Windows

Dialog

Let’s see! :-)

Mozilla development
there is no data, there is only xul