NAME

XUL::App - Nifty XUL apps in a XUL::App

VERSION

This document describes XUL::App 0.09 released on August 13, 2008.

SYNOPSIS

    $ xulapp app --name YSearchAll

    $ cd YSearchAll

    $ xulapp view --name Overlay --type overlay

    # Edit lib/YSearchAll/App.pm to add the following lines:
    package YSearchAll::App; our $VERSION = '0.09';

    use XUL::App::Schema;
    use XUL::App schema {
    +     xulfile 'overlay.xul' =>
    +         generated from 'YSearchAll::View::Overlay',
    +         includes qw( xulapp/jquery.js overlay.js ),
    +         overlays 'chrome://browser/content/browser.xul';
    +
        xpifile 'ysearchall.xpi' =>
            name is 'YSearchAll',
            id is 'ysearchall@agentz.agentz-office',
            version is '0.0.1',
            targets {
                Firefox => ['2.0' => '3.0.*'],  # FIXME
                Mozilla => ['1.5' => '1.8'],  # FIXME
            },
            creator is 'The YSearchAll development team',
            developers are ['agentz'],
            contributors are [],
            homepageURL is 'http://searchall.agentz.org', # FIXME
            iconURL is '',  # like 'chrome://helloworld/content/logo.png'
            updateURL is ''; # This should not set for AMO extensions.
    };
    1;

    # Add and edit js/ysearchall.js manually
    $ xulapp overlay -p dev11
    $ xulapp bundle .  # generate XPI ready for deployment

DESCRIPTION

XUL::App is a nifty Firefox extension development framework based on Perl. It has a lot of parallels with Jifty. In particular, this framework allows you to build real-world modern Firefox extensions using Perl. But the resulting XPI installation file is completely portable and contains 0 Perl.

This framework has the following highlights:

• Jifty love on the Firefox extension development land.
• Building a realworld Firefox extension can be even much easier than GreaseMonkey hacks.
• Use 100% Perl to specify XUL layout via Template::Declare, no XML pain.
• Automatic extension registration/unregistration for easy debugging. And no more frustration from Firefox's XUL/ext cache. (XUL::App will ensure the developer version defeats Firefox's cache.)
• Transparent jar-based XPI bundling, no chrome.manifest, install.rdf, and zip panic. XUL::App generates all of them for you according to your (declarative) Perl code.
• The resulting XPI file contains 0% Perl and could run everywhere (Win32, Mac, Linux, and etc). It's a compiler-style framework.
• I18N support via the Locale::Maketext::Lexicon module (same as Jifty, but actually emulated by XUL's native I18N mechanism).

Currently the module is still in alpha stage and we're in severe lack of documentation and tests. (Although a real-world fully-fledged Firefox extension named SearchAll (https://addons.mozilla.org/en-US/firefox/addon/5712) is already developed atop it.

You can get a lot of information from the slides that I used in the following talk:

http://agentzh.org/misc/slides/xulapp/xulapp.xul (a JS-enabled Firefox is required to view these slides)

If you're having problems in displaying the slides given above, please try out the PowerPoint (PPT) version below:

http://agentzh.org/misc/slides/xulapp.ppt

or the PDF version:

http://agentzh.org/misc/slides/xulapp.pdf

CAVEATS

• Because XUL::App writes to your ~/.mozilla/firefox directory directly, it's always recommended to backup that directory to somewhere else to prevent unexpected corruption occurring to your Firefox profiles.
• After applying Firefox updates or switching to a new Firefox profile, it's required to restart your Firefox one more time so as to load your extensions. So please don't fire bug report for this.
• Only Firefox 2.0.0.* and Firefox 3.0 on Linux has been tested against this framework. So you're warned when you're going to do XUL::App hacking on other platforms, such as Windows.

  (BTW, I'm very willing to apply patches for other platforms.)

SOURCE CONTROL

You can always get the latest source of XUL::App from the following SVN repository:

http://svn.openfoundry.org/xulapp/trunk/

I really need help in improving this module's docs, tests, and implementation. If you find this thing useful and feel like contributing to it, please write to me and get a commit bit! ;)

SAMPLES

• SearchAll is a real-world Firefox extension that is built upon XUL::App, which can serve as a big demo for the usage of the framework:

  http://svn.openfoundry.org/searchall/trunk/

  And it's already on the mozilla official site AMO:

  https://addons.mozilla.org/en-US/firefox/addon/5712

• ExportReader: A Firefox extension to dump entries from Google Reader to JSON:

  http://svn.openfoundry.org/xulapp/trunk/demo/ExportReader/

  This extension only costed me about 10 lines of Perl and 20 lines of JavaScript, in addition to a few shell commands. The process is easy and enjoyable.

  Because it's mostly for personal use, The usage of this addon deserves some explanation though:

  1. Click the XPI file from your Firefox browser:

     http://svn.openfoundry.org/xulapp/trunk/demo/ExportReader/exportreader.xpi

     After installation, please remember to restart the browser.

  2. Enter the following chrome URL in your Firefox's address bar:

     chrome://exportreader/content/exportreader.xul

     Then you will see the main UI of this extension.

  3. Login to your Google Reader and then click the site on the left-hand-side menu whose entries are what you want to export, say, "chromatic's Journal". Ensure that the "Expanded View" is used in the right-hand-side on the Google Reader page.
  4. Click the "Extract!" button on the right-upper corner. Then you'll see an alert dialog saying how many entries were found. Click "OK" then the corresponding JSON string will be in the right-most textbox which is ready for copy-and-paste.

     Note that, by defaul, Google Reader lazily loads just the top 5 entries or so. So in order to export all the entries in the subscribed site, say, "chromatic's Journal", you'll have to scroll down the Reader's Expanded View and force it to retrieve more entries.

• A helloworld sample extension is given in my XUL::App talk's slides:

  http://agentzh.org/misc/slides/xulapp.pdf

INSTALLATION

    perl Makefile.PL
    make
    sudo make install

BUGS

Sadly XUL::App does not run on Win32 yet. I've only tested it on Ubuntu Linux so far. If you have any problems or would love to help, please let me know ;)

AUTHOR

Agent Zhang <agentzh@yahoo.cn>

COPYRIGHT AND LICENSE

Copyright 2007, 2008 by Yahoo! China EEEE Works, Alibaba Inc. (http://www.eeeeworks.org)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Artistic or GPL.

SEE ALSO

xulapp, Locale::Maketext::Lexicon, Template::Declare, Jifty.