# A Brief Introduction To XULRunner: Part 2

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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:

• A text editor of your choosing. If you don't have one with XML/XUL/JavaScript/CSS syntax highlighting, you might want to check out one of the many Scintilla-based editors: Geany is excellent for Linux (GTK+) users, and decent on Windows (SciTE is similar); Komodo Edit is excellent on any XULRunner-supported platform (Hooray for XULRunner!); and there are many others to choose from.
• 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:

1. Give your project a name. I chose "Hello World".
2. 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 "[email protected]" for mine. If you don't have a domain, you can just use your own name in place of one.
3. A short "package name" as well; for mine, "helloworld".
4. 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.
5. It also requires some author information (that's you!) Enter your name here.
6. 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 "1.9.2.0" and maximum is "1.9.2.*".
7. You may leave the other entries blank, or configure them to your liking.
8. 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.
9. Extract the zip file somewhere on your local drive. A "projects" folder for example.

The only thing left to do is write some XUL to make it look like a program, and some JavaScript to make it do something! Or, you could always run the base application, just to see if your XULRunner setup works. This isn't a bad idea, after all.

#### 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:

/Library/Frameworks/XUL.framework/xulrunner-bin /Users/parasyte/Desktop/helloworld-app-project/application.ini


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/

##### On Windows

From the "Run" window (Start -> Run...) use the following command:

"%PROGRAMFILES%\XULRunner\xulrunner.exe" "path\to\application.ini"


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:

/path/to/xulrunner-bin "/path/to/application.ini"


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.

#### Project ID

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.

### Hello World

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.

## Next Steps

Now that you have a Hello World XULRunner app, you can continue exploring the rest of what XULRunner has to offer. This means XUL and JavaScript... The following sections provide some helpful resources (API references, tutorials, etc.) which will get your on your way. Since you are up and running with a minimal application, it won't take much longer until you have a killer-app of your very own!

### Developer Resources

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.

#### 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

"Packaging" is the process of creating an installer for your application. So far as I know, you have two choices here:

1. Create a self-contained installer, which includes its own private copy of the XULRunner runtime.
2. 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.