getting started with mozilla ui hacking

"What if… non-programmers could design the look and feel of a product using W3C standards instead of C++? Where platform differences could be expressed in stylesheets, not hardcoded with #ifdefs? "

Contributing code to the Mozilla project has never been as easy as it is today. In the past, you had to be some C/C++/platform toolkit hotshot to add code, today all you really need is an understanding of JavaScript, HTML4.0, the W3C DOM, CSS, and most importantly a sense of adventure.

If you've ever downloaded a Mozilla build, and looked inside the chrome folder, and inside one or two of the little XUL or JS files residing there, you would have guessed that something interesting was going on with Mozilla. The whole user interface is built on eXtensible User interface Language ("XUL") and some HTML4.0 components, styled with CSS1 and 2, and made interactive by using JavaScript to do UI code and to make calls to the compiled core via the exposed APIs.

The Good News

• JavaScript is not hard to learn (especially if you know another language)
• Neither is CSS, or HTML 4.0
• You don't need a meaty machine to do UI hacking, no compilation is required, the entire Mozilla UI is interpreted so you only need to reload your XUL to see your changes
• Your UIs will be easy to translate into other languages
• And best of all, we want your input!

And In Case You're Not Convinced…

Here's a snippet of sample UI code (for a toolbar):

<toolbox>   <toolbar class="main-bar" chromeclass="toolbar" style="height: 27px;">     <titledbutton value="Foo 1" onclick="onFoo(1);"/>     <titledbutton value="Foo 2" onclick="onFoo(2);"/>     <html:input type="text" id="location"/>     <titledbutton value="Foo 3" onclick="onFoo(3);"/>   </toolbar> </toolbox>

which yields:

now, in practice we'd use entities for the button captions, and put the real text string in DTD files (to make localisation easier), but for this simple example adding the captions directly into the XUL is permissible.

Get to the point, Ben!

So have an idea for a feature you want to add? See something busted in the browser you suspect might be just a UI issue you can fix? Well, load up your text editor, find yourself some documentation if you need it (see links at the bottom of this document), and get hacking! Here's a general guide:

Chrome Folder Structure

The chrome folder is divided into components. Under each folder are content, locale and skin folders. Content contains all the JS and XUL files that define the structure and behaviour of the user interface. Locale contains text strings for specific languages (in DTD files), and Skin contains CSS files which define the appearance of the contents XUL files.

This is not a XUL, CSS, JavaScript or XML tutorial, but have a look in the files in these folders and you'll quickly get a sense of how things work. If you want to make a new dialog, start by getting an existing one, and pruning out unneeded features. I've found the best way to learn was to play with existing code, and try and write some myself.

Hacking XUL

Before getting started with the XUL widgets, I suggest you have an extended play with them first, create a test XUL document, and try embedding each in. This is especially important for trees, which are the most complicated widget to use. Also, have a play with boxes (boxes are used to contain other widgets, similar to GTK boxes I guess), they're fundamental to controlling the way your interface is displayed on screen. Relatively comprehensive (although sometimes out-of-date, beware!) documents can be found at mozilla.org's XPToolkit page.

You interact with the objects in your UI using W3C DOM calls. If you don't know much DOM, try reading this document, or learn by reading existing code. (You might find it useful to bookmark that doc though, it's a handy reference).

Accessing Mozilla APIs

Once you've successfully created your UI and made it interactive, you'll probably want to interact in some way with the core of Mozilla (unless you've written your own component, in which case you'll want to interact with that as well). Accessing these components appears to differ in subtle ways depending on what you're using, but the general form is fairly similar - you access core components using a process called XPConnect. Again this isn't a tutorial, have a look at the JS files. After XPConnecting, you're normally left with an object that contains a lot of attributes and member functions you can tweak with JavaScript. For example, after XPConnecting to nsIEditorShell, your editorShell JavaScript variable can access all the scriptable methods and attributes listed in nsIEditorShell.idl

Where to find API Documentation

API documentation is fairly nonexistent at the moment, but if you XPConnect to an interface, the stuff you can use is described in the IDL (Interface Definition Language) file for that interface. Read existing code, and you'll get the general idea soon enough. For convenience, if you have the disk space, check out the SeaMonkey source code (see the Source Code page @mozilla.org), and then you can search through the IDL files locally, and use the actual source code to figure out what the functions do if need be. Otherwise, just search on LXR for the interface you need.

Localisation

Whenever you go to put a text string in a XUL file, stop. If this is for anything other than testing, it should be an entity, and it should be placed into a DTD file. Look at XUL files and DTD files for examples of how to do this. Why do we do this? To make it easy for people to translate into other languages. When they translate, they only need translate the DTD files, or use one of the programs that people have made to assist translation.

If you find yourself using strings in JavaScript, you can localise these by using string bundles. For examples on how to use these, see the file in the res folder called "strres-test.xul" and "strres-test.js".

That about covers it! Before, during or after your development, post to the appropriate newsgroup(s) (a listing of some of them are below). Everyone would love to hear about what you're working on, and if you need help, or want opinions or suggestions, posting to one of the Mozilla newsgroups is a great way to get it. You may find someone with the same wish, or someone already doing work that you can help with. Above all, get out there and be heard!

Key Points JavaScript APIs are described in Interface Definition Language files (*.idl). There are many, many interfaces, and even more functions and data members for you to work with. You can also write your own compiled modules and access them from script. XPConnect is the process by which you "grab on" to an interface, so you can use its functions and access its data. XUL is an XML derived language, similar to HTML, which allows you to define flexible user interfaces. Localisation is a very important part of creating applications. By placing all of your text strings into separate DTD and .properties files, you allow others to translate your work into another language easily. Hacking Mozilla is fun! and a rewarding challenge. By working with Mozilla's UI now you are working with a set of emerging technologies, some of which may shape the web and application development in years to come. There's never been a better time to get involved!

Useful Links

• XPFE Webpage contains links to useful documentation and design ideas for the Mozilla Cross Platform Front End: http://www.mozilla.org/xpfe
• XPToolkit Webpage contains the most comprehensive (yet often out-of-date) guide to XUL widgets: http://www.mozilla.org/xpfe/xptoolkit
• RDF is a standardised way of accessing and storing data. Examples exist in code, and there are lots of useful documents here: http://www.mozilla.org/rdf/doc/
• LXR (Linux Cross Reference) Seamonkey is a searchable, extensively cross-referenced HTML based version of the source code: http://lxr.mozilla.org/seamonkey
• Nightly Build FTP Directory is where you can get the latest builds from. More useful than Milestones, which are often out of date: ftp://ftp.mozilla.org/pub/mozilla/nightly/latest
• Bugzilla (for reporting and querying bugs): http://bugzilla.mozilla.org/
• Source Code page @mozilla.org (for getting source code, instructions on building etc): http://www.mozilla.org/source.html
• MozillaZine is also a good place to get some thoughts on your ideas, if you have an idea or write an article, send it in and watch the forums! http://www.mozillazine.org/

Newsgroups

See the mozilla.org Community page for a full list of Newsgroups. Some are listed here:

• netscape.public.mozilla.xpfe - the primary XPFE newsgroup.
• netscape.public.dev.xul - newsgroup for questions about XUL
• netscape.public.mozilla.dom - DOM implementation
• netscape.public.mozilla.jseng - javascript engine (not DOM!)
• netscape.public.mozilla.editor - Composer editor group
• netscape.public.mozilla.mail-news - Messenger Mail-news component
• netscape.public.mozilla.prefs - Preferences system
• netscape.public.mozilla.ui - User Interface newsgroup
• netscape.public.mozilla.wishlist - Wishlist - if you don't know what you want to add, try looking here for inspiration!

IRC

Point your IRC client at irc.mozilla.org, and join #mozilla to join in the live Mozilla discussion!