A Brief Introduction To XULRunner: Part 2
Now that you are familiar with what XULRunner is, let's explore how to use it. More generally, let's explore how to use Mozilla tools that were designed to make building XULRunner applications easier.
How to Use XULRunner
Setting Up a XULRunner Development Environment
Setting up your XULRunner development environment is very easy. You need just a few programs to get started:
- The XULRunner Runtime itself. Download the latest stable version from Mozilla: http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/ (Note: Go into the most recent sub-directory and then the "runtimes" sub-directory. You don't need the SDK.)
After installing the XULRunner runtime and text editor of your choice, you can begin creating a new project template.
Creating a XULRunner Application Template
Developers familiar with C and C++ know that all C/C++ applications must have a function called main(). Or in Win32 development, things are even more convoluted; a WinMain() function is required, along with a message pump and some other nonsense. Similarly, all XULRunner applications have a series of requirements (functional and structural) to "bootstrap" the application.
Often, this task of creating a new project is tedious, mundane, and repetitive (to name just a few adjectives). This is why most C/C++ developers just copy startup (and maybe other) code from an existing project when creating a whole new one. That takes care of the bootstrapping process, without having to remember everything required to get up and running. This can certainly be done with new XULRunner applications, if you like. But there is an easier way...
FizzyPop, Or "How I Made My XULRunner Application"
Those clever folks at Mozilla know how bothersome it is to create a base XULRunner application (for the curious among you, have a look at the official tutorial, steps 3 - 7). And so they created a project called FizzyPop which will create all that fun boilerplate stuff for you; just give your project a name, maybe a version number, give it your name as the author, select a few options ... and BAM! Instant XULRunner Application: Just Add Water (tm).
So here we go! To use this magical "FizzyPop" thing, just point your web browser to it! There are currently two different resources available for it (to my knowledge). The latter has been tagged a "prototype" so it might not be the one you want to use. But don't quote me on that! Without further ado, just go there:
Choose the "Application" Start link. Now there are just a couple of [very, very simple] steps to follow, and you'll be on your way:
- Give your project a name. I chose "Hello World".
- And an ID. The ID is in the form of an email address, which seems odd at first, but makes sense in the proper context (#Project ID). I chose "firstname.lastname@example.org" for mine. If you don't have a domain, you can just use your own name in place of one.
- A short "package name" as well; for mine, "helloworld".
- You can leave the version number and build ID at their default values (note that the "prototype" does not give you any default values) ... or go ahead and punch in some different numbers. It won't matter much.
- It also requires some author information (that's you!) Enter your name here.
- Set the Platform Details minimum and maximum version numbers according to the XULRunner runtime version you're using. In my case, minimum is set to "18.104.22.168" and maximum is "1.9.2.*".
- You may leave the other entries blank, or configure them to your liking.
- Click the final "Create" button, and it will start to download a zip archive containing all of the necessary files and directory structures for a basic XULRunner application.
- Extract the zip file somewhere on your local drive. A "projects" folder for example.
Testing and Installation
On Mac OS X
To test your application boilerplate, run XULRunner from the command line, passing the path to the "application.ini" as an argument. For example, on Mac OS X, I run this from the Terminal:
Note: XULRunner on OS X requires the full path to the application.ini file
After making sure it works (you should be given a blank window) you can install the application to make it act more like a real app. (For example, installation will give it a Dock icon, menu bar, etc.) To install on OS X:
/Library/Frameworks/XUL.framework/xulrunner-bin --install-app /Users/parasyte/Desktop/helloworld-app-project
Note: Don't include the "/application.ini" when installing the app!
With the application installed, you can find it in your /Applications/ directory. If you set a "Vendor" when you created the boilerplate, then it will be put into /Applications/vendor-name/
From the "Run" window (Start -> Run...) use the following command:
Where "path\to\application.ini" is the actual path the the actual application.ini file. If it works, you will get a blank window. You can then install the application with the following:
"%PROGRAMFILES%\XULRunner\xulrunner.exe" --install-app "path\to\application"
Where "path\to\application" is the path to the application's top-level directory; NOT the application.ini file. This will install the application to "%PROGRAMFILES%\application-name\", or if you set the "Vendor" field when you created the boilerplate, in "%PROGRAMFILES%\vendor-name\application-name\".
On Ubuntu Linux
In a terminal:
A blank window appearing means all worked well. To install:
/path/to/xulrunner-bin --install-app "/path/to/application"
Note: Do not point the installer to the application.ini file; point it instead to the application's top-level directory.
The XULRunner Project ID is a unique identifier, which allows certain features of XULRunner to work properly. I can't exactly name any specific use for it off-hand, but I believe it can be used by extensions to access specific data local to your application.
To complete the first step towards world domination with XULRunner, you'll want to make the application do something (or at least, say something) ...
Open the file /chrome/content/main.xul in your application directory. You will be greeted with a lot of XML. This is the file that defines the complete GUI for your application's main window. You can add any XUL elements to this file to create any kind of widget in your main window. For starters, just add a simple label element before the </vbox> tag, near the end of the file. Something like this:
<hbox id="main_box" flex="1"> <vbox id="workspace_box" flex="1"> <label value="Hello, World!"/> </vbox> </hbox> </window>
Run the app to see your changes. Reinstall it, if you like. When reinstalling, it is a good idea to first delete the old already-installed application, but this is not always necessary.
This is a list of websites relevant to XULRunner and creating applications for it. While this list is produced entirely without any specific order, I've attempted to keep the most important of these near the top.
- Mozilla Developer Central: XUL Tutorial (Slightly old, but still one of the best sources of information on XUL.)
- Mozilla Developer Central: XUL Information (Specifically, the complete XUL Reference.)
- Mozilla Developer Central: XULRunner Information
- Mozilla Developer Central: XUL School (Targets Firefox Extension developers, but contains XUL tutorial)
- XUL.fr Tutorial
- Creating Applications With Mozilla (Online book.)
- Rapid Application Development With Mozilla (Online book.)
- Creating XPCOM Components (Online book.)
- Mozilla XPCOM Reference (All interfaces and components; always kept up-to-date.)
- Mozilla Add-on Developer Hub (Mostly related to Firefox add-on development; but useful for XULRunner, too.)
- IBM developerWorks: An introduction to XML User Interface Language (XUL) development (PDF, mirrored here because IBM requires compulsory registration to download this from their website. Original location: http://www.ibm.com/developerworks/edu/x-dw-x-xulintro.html)
- MozillaZine: Development Resources (Semi-outdated.)
- Cover Pages: Extensible User Interface Language (XUL) (Extremely outdated, but historically relevant.)
XUL Editors and Designers
I've found these applications helpful, while learning XUL.
- Ted Mielczarek's Real-Time XUL Editor (Great for quickly testing XUL from directly within Firefox.)
- XUL Explorer (Similar to the Real-Time XUL Editor above, but as a XULRunner application.)
- XULPIX (A great XUL editor; the closest thing to a form designer that we currently have ... without Eclipse! Yucky...)
- Pencil Project (Firefox extension for "sketching". It allows you to prototype/mockup UI elements. Not really a form designer, but pretty close.)
"Packaging" is the process of creating an installer for your application. So far as I know, you have two choices here:
- Create a self-contained installer, which includes its own private copy of the XULRunner runtime.
- Create an XPI; an archive that can be installed as a XULRunner application by a pre-existing XULRunner runtime.
The latter option requires that your users install the XULRunner runtime (just like you did at the beginning of this introduction). The former option just requires that the user download the installer and install it. This option has the disadvantage that the file the user must download is a *LOT* larger than just the simple XPI. About 9MB for Windows and Linux, or 17MB for Mac OS X; compared to just a few KB (typically 10KB for a small app, like our Hello World) for the XPI!
I haven't yet investigated XULRunner application packaging. This section is in need of completion.