password
username
Sponsored by CakeMail, an email marketing software.
Newsletter preview


IBM developerWorks Web services/XML tip newsletter
----------------------------------------

IBM's resource for developers
http://www.ibm.com/vrm/newsletter_10802_3548_78780_email_DYN_2IN/wsf136238161

----------------------------------------
21 July 2008, Vol. 8, Issue 6
----------------------------------------

"USE THE NEW MICROFORMATS API IN YOUR FIREFOX 3.0 EXTENSIONS"
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_13IN/wsf136238161

Level: Intermediate

Rob Crowther (robert@crowther.info)
Freelance Web developer


Hello, tip readers.

The new Firefox 3.0 release has built-in support for microformats
in the form of an API that you can access from a Firefox extension.
In this tip, you follow a simple example of how to use this API from
within your extension code. You take a skeleton Hello World extension
and give it the ability to store an hCard from any Web page and then
use that stored hCard to populate a Web form.

For the full tip, read on below.

Until next time,
The Web services/XML tip team at developerWorks

Correspondence:
mailto:dwnews@us.ibm.com


_________________________________________________________________
INTRODUCTION

To follow along with this tip you'll need a basic understanding of how
extensions are built for Firefox. Fortunately, if you write JavaScript
and HTML, you already have almost all the knowledge you need. For an
overview of extension development, check out the Resources for this
tip (see link at the bottom of this page). We'll only cover the basics
of it in this tip. You will also need Firefox 3.0. If you don't have
it installed, then download and install the latest release candidate
or a nightly build. If you want to avoid anything from happening to
your existing Firefox profile, set up a separate profile for
developing. For further details on how to set up an extension
development environment on Mozilla Developer Center, see the tip
Resources.


_________________________________________________________________
CREATE THE EXTENSION FRAMEWORK

You'll use the extension wizard to build the basic structure for you.
The file I generated is available from the tip Downloads (see link at
the bottom of this page). Download and extract that file into your
working directory if you want to follow along.

Rather than build the extension and install it, you'll map the working
directory into the Firefox extension folder. Create a text file with
the name hcardformfiller@rob.crowther and put it in the path to the
extension files in your working directory (see Listing 1). Then save
this file in the extensions directory of your development profile,
which for me is
/home/robert/.mozilla/firefox/r6z6s4yl.default30/extensions (see the
Mozillazine knowledge base in the tip Resources for more details).


------------------------------------------------------------
Listing 1. The hcardformfiller@rob.crowther file

/home/robert/code/xpcom/hcardformfiller


After you've done this, restart your Firefox development version using
the script built in Listing 1. The extension should install and you
should be able to access the default Hello World elements.


_________________________________________________________________
ADD UI ELEMENTS

Since you want your users to be able to trigger the extension
functionality, you'll provide them with a couple of toolbar buttons.
To add toolbar buttons, you'll need to describe them in the XUL
overlay. Open the file hcardformfiller/content/firefoxOverlay.xul and
replace what's already there with the code in Listing 2 (see live
article for Listing 2):
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_14IN/wsf136238161

Listing 2 gives you two toolbar buttons, a Grab button and a Paste
button. For convenience, they both use the same icon,
hcardformfiller.png, which is available in the Download file. If you
save everything at this point and restart Firefox, you can drag the
buttons onto your navigation toolbar if you right click on each of
them and select Customize. You can see the end results in Figure 1 of
the live article:
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_15IN/wsf136238161


_________________________________________________________________
GRABBING MICROFORMATS FROM THE PAGE

Now that you have toolbar buttons, you need them to do something when
users click them. This means you'll have to write the JavaScript
functions that support toolbar buttons defined in Listing 2. First,
when the user clicks the Grab toolbar button, you want it to search
the current page for microformats and store the first one it finds.
Open up hcardformfiller/content/overlay.js and replace the code with
Listing 3.


------------------------------------------------------------
Listing 3. The overlay.js file

Components.utils.import("resource://gre/modules/Microformats.js");
var hcardformfiller = {
onLoad: function() {
this.initialized = true;
this.strings = document.getElementById("hcardformfiller-strings");
this.uF = {};
},
onToolbarButtonGrabCommand: function(e) {
var uFcount =
Microformats.count('hCard', content.document, {recurseExternalFrames: true});
if (uFcount > 0) {
var uFlist =
Microformats.get('hCard', content.document, {recurseExternalFrames: true});
this.uF = uFlist[0];
}
}
};
window.addEventListener("load", function(e) { hcardformfiller.onLoad(e); }, false);


The first line of Listing 3 loads the microformats API, which is
needed for anything else to work. Further down, you define the
onToolbarButtonGrabCommand, which is the code that runs when a user
clicks the Grab toolbar button. Next, call Microformats.count() to see
if the page has any hCards. This method accepts a microformats name, a
document reference to start the search from, and an optional array of
parameters. Here you search for hCards anywhere in the current window,
and you allow the parser to recurse down through any frames it
encounters. After you determine that you have at least one hCard, you
then get a list of all hCards on the page using the Microformats.get()
method. The parameters are identical to your previous call, but this
time the code returns an array of objects of type hCard. To keep the
example simple, you only grab the first one and store it in your
global variable.


_________________________________________________________________
INSERTING THE HCARD INTO A FORM

Now that you've grabbed the hCard, you want to do something with it.
I created a simple form in Listing 4 for the extension to populate
with hCard details. Just put it into a standard HTML Web page and save
it locally -- you don't need to process the submit form for the
purposes of this tip.


------------------------------------------------------------
Listing 4. A simple target form for the extension

hCardFormFiller Target Form





















Now you need to define the function attached to the Paste button
defined in Listing 2, so when the user clicks the button, the form is
filled in. See the code for your extension to fill this form in
Listing 5.


------------------------------------------------------------
Listing 5. Adding the paste command to overlay.js

onToolbarButtonPasteCommand: function(e) {
if (this.uF.fn) {
content.document.getElementById('name').value = this.uF.fn;
content.document.getElementById('email').value = this.uF.email[0].value;
content.document.getElementById('homepage').value = this.uF.url[0];
content.document.getElementById('address1').value = this.uF.adr[0]['street-address'];
content.document.getElementById('address2').value = this.uF.adr[0].locality;
content.document.getElementById('city').value = this.uF.adr[0].region;
content.document.getElementById('postcode').value = this.uF.adr[0]['postal-code'];
}
}


The first step is to see if there is an hCard to paste -- the fn is
one of the two required fields in the hCard microformat. If fn exists,
then you have an hCard. You then put that fn in the first field of the
form. An hCard can have multiple e-mail values, so the email property
on hCard is an array -- you just grab whatever the first one is -- and
each email has two properties: type, which can be internet, x400, or
pref for preferred; and value, which is the actual e-mail address. The
url property of hCard is also an array, but this time without
subproperties; whereas, the adr property is an array of the atomic adr
microformat, which you can also manipulate directly outside hCard. The
main point to note on these adr properties is that I used the
alternative reference syntax in JavaScript, because the hyphen gets
treated as a minus otherwise. You can see the results in Figure 2 of
the live article:
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_16IN/wsf136238161

In Figure 2, I grabbed the hCard from the about page of my Web site,
then used it to fill in the form -- seven fields filled in with a
couple of clicks of the mouse!


_________________________________________________________________
SUMMARY

In this tip, you took a standard Firefox extension template and
quickly gave it the ability to use hCard microformats thanks to
the new APIs in Firefox 3.0. You can see that the API makes
manipulating microformats data very easy. With very little code, you
can build an extension that is a massive time saver, and to add
similar features to your own extensions will be very little work.

As a next step, you might consider generalizing the paste action to
provide a mapping file for any form, and allow use of an hCard
microformat to fill it. A shared repository of mappings can vastly
simplify the process of filling in forms on the Web.


=================================================================
LINKS TO OTHER GOOD STUFF

::: Full text of this tip on the Web :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_13IN/wsf136238161

::: Resources related to this tip :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_17IN/wsf136238161

::: Downloads related to this tip :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_18IN/wsf136238161

::: IBM developerWorks XML zone :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_19IN/wsf136238161

::: IBM developerWorks SOA and Web services zone :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_20IN/wsf136238161

::: Subscribe to the developerWorks weekly newsletter :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_21IN/wsf136238161

::: IBM's privacy policy :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_22IN/wsf136238161

::: IBM's copyright and trademark information :::
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_23IN/wsf136238161


=================================================================

THIS NEWSLETTER IS FOR INFORMATION ONLY. This newsletter should not be
interpreted to be a commitment on the part of IBM, and, after the
publication date, IBM cannot guarantee the accuracy of any information
presented. You may copy and distribute this newsletter, as long as:

1. All text is copied without modification and all pages are included.
2. All copies contain IBM's copyright notice and any other notices
provided therein.
3. This document is not distributed for profit.

IBM developerWorks
http://www.ibm.com/vrm/newsletter_10802_3548_78781_email_DYN_24IN/wsf136238161

----------------------------------------
About this newsletter

Manage your subscriptions:
http://www.ibm.com/vrm/newsletter_10802_3548_43352_email_DYN_1IN/wsf136238161

Subscribe:
http://www.ibm.com/vrm/newsletter_10802_3548_43352_email_DYN_4IN/wsf136238161

***:
http://www.ibm.com/vrm/newsletter_10802_3548_43352_email_DYN_3IN/wsf136238161

Contact editor:
mailto:dwnews@us.ibm.com

To ensure proper delivery please add enewsletter@us.ibm.com to your address book.

You received this e-mail because you are subscribed to IBM's developerWorks Web services/XML newsletter as: TAYLLORCRISS@GMAIL.COM

© International Business Machines Corporation 2007. All rights reserved.

IBM Corporation
Attn: Developer Communications, M/D 241
150 Kettletown Road
Southbury, CT USA 06488

Contact IBM:
http://www.ibm.com/vrm/newsletter_10802_3548_43352_email_DYN_2IN/wsf136238161