B.1.1. new-from-template.pl Script

Though it's not named very elegantly, the new-from-template.pl Perl script takes information you provide in the form of a simple text file and uses it to create various parts of a Mozilla application. These parts include the XUL content, which has a basic menubar you can add to; an overlay that puts an item for your application into the Tools menu in the Mozilla browser; CSS for your XUL; and an installation script for the application package. You can base your application off of a couple of different templates, including a sophisticated one that lets you generate XPCOM interfaces for components you wish to use in your application, described below.

Using these scripts, you can add content and logic to your application, restyle it, or build your application however you would like. You can also register the resulting directory with the chrome registry to see it working in your local copy of Mozilla, and when you finish developing it, the application directory is already structured in exactly the way it must be to be checked into the Mozilla source tree's extensions directory (if you want to check it into this common location for applications that become a part of Mozilla). When you want to distribute your application as described in Chapter 6, you can use the other script in the XULKit, makexpi.pl, to package your application files into a cross-platform archive that can be installed from a regular web page.

To use the new-from-template.pl script, point it at a template that you filled out with your own information. It then generates the basic application code in the appropriate subdirectory structure:

new-from-template.pl      -t FILE [-o DIRECTORY] [-f[d]] [-h] [-?]

When you run the script, the XULKit creates a new top-level application directory. In this directory, the script creates the three main package directories, and it places some basic content in each one: a CSS file called mozreg.css in the skins subdirectory, a few XUL files in the content directory (including the overlay that defines a new menu item for the main browser that opens this new application), and localizable data in the mozref.dtd file in the locale subdirectory.

In addition to these files, the XULKit script creates contents.rdf files that describe each package, some Makefiles that instruct the Mozilla build process how to integrate this application into the build (which is a later step and not necessary to run the application), and an install.js file that executes the installation of this application when it appears in a XPI. (See Chapter 6 for more information about XPI, Mozilla's cross-platform installation file format.)

If you look at Example B-1 -- xul-app.tpl, which comes with the distribution of new-from-template.pl -- you can see how easy it is to fill out the basic information and create your own template.

# load default template for a XUL app
include "${top_wizard_dir}templates/xul-app.tpl"
# short app name (can not contain spaces.)
# until http://bugzilla.mozilla.org/show_bug.cgi?id=75670 is fixed, this needs
# to be all lowercase.
app_name_short=xulsample
# long app name (spaces are OK.)
app_name_long=Sample XUL Application (generated from sample.xul-app.tpl)
# name as it should appear in the menu
app_name_menu=Sample XUL App
# version to tell the .xpi installer
app_version=1.0
# author, used in various chrome and app registration calls
app_author=mozilla.org
# size of the package when installed, in kilobytes.
# this number is used by the install.js script to check for enough disk space
# before the .xpi is installed.  You can just guess for now, or put 1, and fix it
# in install.js before you make your .xpi file.
install_size_kilobytes=1

You can adapt the xul-app.tpl for your own purposes or use the sample.xul-app.tpl that is already filled out. Table B-1 details different options for new-from-template.pl.

-d

-f

-h

-o DIRECTORY

-t TEMPLATE

-?

# variables the user's .tpl file MUST declare
required_variables = ${component_name}, ${implementation_guid}, \
                     ${interface_name}, ${interface_guid}

# include default values
include "${top_wizard_dir}templates/xpcom-component.tpl"
component_name      = SampleComponent
implementation_guid = c6793b0c-1dd1-11b2-a246-92bf95c9d097
interface_name      = tstISampleComponent
interface_guid      = d03ea960-1dd1-11b2-9682-81ecad6a042a

B.1.2. makexpi.pl Script

In addition to the template-generating script described above, a second script takes your working application and creates an installable package, or XPI, out of it. This way, you can distribute it to others in the same way the various components of the Mozilla browser are distributed and installed when you use the Mozilla installer.

This script, makexpi.pl, takes an application directory as input and generates an XPI archive. It also manifests for various parts of your application, the installation script that goes inside this archive, and even the installation web page itself. While new-from-template.pl is designed to help you start your application, makexpi.pl takes your locally developed application and makes it into a package that can be distributed to other users and installed via the Web.

To use makexpi.pl, point it at a configuration file that you have edited to point at your application directory:

makexpi.pl      [-c <config-file>] [-d] [-r <revision>] [-?]

For example, to create a XPI out of your MyApp application directory, in which you created a file called MyApp.conf that defines the variables makexpi.pl needs, execute the script as follows:

perl makexpi.pl -c ~/appdev/MyApp/makexpi.conf -r 0.9.9

A makexpi.conf file defines the variables makexpi.pl needs to know about. Example B-3 shows an example of this file.

# directory where xpi should be created
workdir     = /home/rginda/src/xulkit/sample-app/
# directory where jar.mn is
mndir       = ${workdir}/sampleapp/resources/
# location of templatized install.js file
installfile = ${xulkit_dir}/templates/xpi/install.js
# directory where mozilla's make-jars.pl and friends are
mozcfgdir   = ${xulkit_dir}/bin/
# name of resulting xpi file
xpifile = ${app_name_short}-${revision}.xpi

Table B-2 lists the options that are recognized by makexpi.pl.

-c FILE

-d

-r REVISION

-?

When you run the script against the configuration file, you end up with two separate pieces -- the XPI in which your application and its installation script are stored and a web page that you can post on a server to guide the XPI's installation. As described in Chapter 6, the web page interacts with the XPI's install.js to install and register your application in Mozilla. If you start your application with the new-from-template.pl script, then a template-processed version of install.js that works with your application is included as templates/xpi/install.js as part of the XULKit package.

B.1.3. Using XULKit

Given these two scripts and the templates that go with them, the XULKit encourages and makes the following application development workflow possible:

1. Fill out a new-from-template.pl template with your application information.

2. Run the new-from-template.pl script to generate the application directory.

3. Register your application in flat mode: as a directory in your local copy of Mozilla.

4. Develop your application: the XUL content, the CSS, the application code in JS, etc.

5. Test the application code.

6. Run makexpi.pl against your working application to create an installable package.

7. Put the XPI and the web page up on a server to create an install for your application.

That's it!