{"id":511,"date":"2009-02-22T15:42:14","date_gmt":"2009-02-22T15:42:14","guid":{"rendered":"http:\/\/dalelane.co.uk\/blog\/?p=511"},"modified":"2009-02-22T15:45:04","modified_gmt":"2009-02-22T15:45:04","slug":"beginners-guide-to-writing-a-firefox-extension","status":"publish","type":"post","link":"https:\/\/dalelane.co.uk\/blog\/?p=511","title":{"rendered":"Beginner’s guide to writing a Firefox extension"},"content":{"rendered":"

Last week, I shared my hack for syncing my browsing between my computer and mobile<\/a>. It’s built around a Firefox extension, so I thought I’d share my notes on how I got it to work.<\/p>\n

\"screenshot\"This post is a complete sample for creating a Firefox extension to add a button to the browser toolbar. When you click on the button, it grabs the URL from the Firefox address bar and does something with it.<\/p>\n

I’ve gone through each file you need, explaining what it’s for and giving a sample ready for copy-and-pasting. <\/p>\n

In my browser sync hack<\/a> it sent the URL to my phone, but for this walkthrough I’m going with something simpler: opening the webpage in Internet Explorer. You can replace that bit of script with something more useful \ud83d\ude42<\/p>\n

I’m not an expert at this stuff by any means, and I found a lot of useful code snippets on mozilla.org<\/a> to get me going. But this seems to work, and as people that I’ve shown my extension to so far seemed surprised at how easy it was, I thought it might be useful to share.<\/p>\n

Apart from the Internet Explorer bit itself (which is a little Windows-specific), the rest of this should all work wherever Firefox does.<\/p>\n

Step 1 – Prepare a development environment<\/strong><\/p>\n

Create a working directory where you will work on your extension. <\/p>\n

Then create a text file in your Firefox extensions directory:
\n(e.g. C:\\Documents and Settings\\YourUserName\\Application Data\\Mozilla\\Firefox\\Profiles\\YourFirefoxProfile\\extensions\\)<\/p>\n

The file name should be named YourExtensionName@Your.Name
\ne.g. sendtoie@dale.lane<\/code><\/p>\n

The file should contain the path where you put the working directory for your extension.<\/p>\n

This is enough for Firefox to find your extension – although you will need to restart the browser every time you make a change.<\/p>\n

Step 2 – chrome.manifest<\/strong><\/p>\n

Create a chrome.manifest<\/code> file in your working directory where you will list the files we need for our extension<\/p>\n

For example:<\/p>\n

content sendtoie       content\/\r\nskin    sendtoie       classic\/1.0      skin\/\r\noverlay chrome:\/\/browser\/content\/browser.xul    chrome:\/\/sendtoie\/content\/firefoxOverlay.xul\r\nstyle   chrome:\/\/global\/content\/customizeToolbar.xul    chrome:\/\/sendtoie\/skin\/overlay.css<\/pre>\n
Step 3 – install.rdf<\/strong><\/p>\n
Create an install.rdf<\/code> file in your working directory where you describe the extension – information that will be shown in the Firefox Add-ons dialog.<\/p>\n
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<RDF xmlns=\"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#\" \r\n xmlns:em=\"http:\/\/www.mozilla.org\/2004\/em-rdf#\">\r\n  <Description about=\"urn:mozilla:install-manifest\">\r\n    <em:id>sendtoie@dale.lane<\/em:id>\r\n    <em:name>Send to Internet Explorer<\/em:name>\r\n    <em:version>0.1<\/em:version>\r\n    <em:creator>Dale Lane<\/em:creator>\r\n    <em:description>Send a webpage to Internet Explorer<\/em:description>\r\n    <em:homepageURL>http:\/\/dalelane.co.uk\/blog\/<\/em:homepageURL>\r\n    <em:iconURL>chrome:\/\/sendtoie\/content\/sendtoie.gif<\/em:iconURL>\r\n    <em:targetApplication>\r\n      <Description>\r\n        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}<\/em:id> <!-- firefox -->\r\n        <em:minVersion>2.0<\/em:minVersion>\r\n        <em:maxVersion>3.0.*<\/em:maxVersion>\r\n      <\/Description>\r\n    <\/em:targetApplication>\r\n  <\/Description>\r\n<\/RDF><\/pre>\n
Step 4 – content\/firefoxOverlay.xul<\/strong><\/p>\n
Create a ‘content<\/code>‘ sub-directory in your working directory and create a firefoxOverlay.xul<\/code> file. This is where you specify that a button should be added to the toolbar and identify what function should be run when you click on it.<\/p>\n
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<?xml-stylesheet href=\"chrome:\/\/sendtoie\/skin\/overlay.css\" type=\"text\/css\"?>\r\n<!DOCTYPE overlay SYSTEM \"chrome:\/\/sendtoie\/locale\/sendtoie.dtd\">\r\n<overlay id=\"sendtoie-overlay\"\r\n         xmlns=\"http:\/\/www.mozilla.org\/keymaster\/gatekeeper\/there.is.only.xul\">\r\n  <script type=\"application\/x-javascript\" src=\"overlay.js\"\/>\r\n\r\n  <toolbarpalette id=\"BrowserToolbarPalette\">\r\n     <toolbarbutton id=\"sendtoie-toolbar-button\" \r\n        autoCheck=\"true\"\r\n        label=\"send page to IE\"\r\n        tooltiptext=\"Send current page to Internet Explorer\"\r\n        oncommand=\"SENDTOIE.onToolbarButtonCommand();\"\r\n        class=\"toolbarbutton-1 chromeclass-toolbar-additional\"\/>\r\n  <\/toolbarpalette>\r\n<\/overlay><\/pre>\n
Step 5 – content\/overlay.js<\/strong><\/p>\n
Still in the ‘content<\/code>‘ sub-directory in your working directory, create an overlay.js<\/code> file where you put the main Javascript implementation of your extension.<\/p>\n
For this simple example, we use nsIProcess to invoke the Internet Explorer iexplore.exe process, passing it the URL from Firefox as an argument.<\/p>\n
var SENDTOIE = {\r\n\r\n    sendUrl : function() {\r\n\r\n        var urlbar = document.getElementById('urlbar');\r\n\r\n        if (urlbar) {\r\n            \/\/ create an nsILocalFile for the executable\r\n            var file = Components.classes[\"@mozilla.org\/file\/local;1\"].createInstance(Components.interfaces.nsILocalFile);\r\n            file.initWithPath(\"C:\\\\Program Files\\\\Internet Explorer\\\\iexplore.exe\");\r\n            \r\n            \/\/ create an nsIProcess\r\n            var process = Components.classes[\"@mozilla.org\/process\/util;1\"].createInstance(Components.interfaces.nsIProcess);\r\n            process.init(file);\r\n            \r\n            \/\/ Run the process.\r\n            \/\/ If first param is true, calling thread will be blocked until\r\n            \/\/ called process terminates.\r\n            \/\/ Second and third params are used to pass command-line arguments\r\n            \/\/ to the process.\r\n            var args = [urlbar.value];\r\n            process.run(false, args, args.length);\r\n        }\r\n    },\r\n\r\n    onToolbarButtonCommand : function(e) {\r\n        SENDTOIE.sendUrl();\r\n    },\r\n};<\/pre>\n
Step 6 – skin\/overlay.css<\/strong><\/p>\n
Create a ‘skin<\/code>‘ sub-directory in your working directory and create an overlay.css<\/code> file in there. This is where you specify the style for the button you are adding to the toolbar. <\/p>\n
#sendtoie-toolbar-button\r\n{\r\n  list-style-image: url(\"chrome:\/\/sendtoie\/skin\/toolbar-button.png\");\r\n  -moz-image-region: rect(0px 24px 24px 0px);\r\n}\r\n#sendtoie-toolbar-button:hover\r\n{\r\n  -moz-image-region: rect(24px 24px 48px  0px);\r\n}\r\n[iconsize=\"small\"] #sendtoie-toolbar-button\r\n{\r\n  -moz-image-region: rect( 0px 40px 16px 24px);\r\n}\r\n[iconsize=\"small\"] #sendtoie-toolbar-button:hover\r\n{\r\n  -moz-image-region: rect(24px 40px 40px 24px);\r\n}<\/pre>\n
Step 7 – skin\/toolbar-button.png<\/strong><\/p>\n
Now for images. First, the icon that goes on the toolbar button goes in the ‘skin<\/code>‘ directory. <\/p>\n
You need at least four icons – one large icon, one large icon for when the mouse is hovering over it, one small icon, and one small icon for when the mouse is hovering over it.<\/p>\n
You use one image file for all the images needed – the stylesheet in Step 6 identifies the coordinates of a section of the file to use for each image.<\/p>\n
This is one of the images I created for a toolbar button in my syncing extension<\/a>. (Sadly, drawing this is the bit that probably took me the longest of the whole hack!<\/em>)<\/p>\n
<\/a><\/p>\n
Step 8 – content\/sendtoie.gif<\/strong><\/p>\n
The last quick step – you need an icon for the extension. This is the icon that will be shown the Firefox Add-ons dialog. I used this one, and put it in the ‘content<\/code>‘ directory.<\/p>\n
<\/a><\/p>\n
Step 9 – debug \ud83d\ude42 <\/strong><\/p>\n
Something probably went wrong, so you now get into a cycle of tweaking something, and restarting Firefox and retesting. You need to restart the browser to pick up any changes you make.<\/p>\n
Once you are happy with it all, it’s time to package up your extension for sharing.<\/p>\n
Delete the text file you added to the Firefox extensions directory in Step 1, and restart Firefox – you want a clean browser ready to test installing your real extension next.<\/p>\n
Step 10 – preparing an xpi<\/strong><\/p>\n
Firefox extensions are distributed as .xpi files. This is just a zip file, renamed to have a xpi extension. <\/p>\n
Zip up your working directory and give it a name that ends in .xpi. You can make this available as an installer for your extension for other Firefox users. <\/p>\n
All done. \ud83d\ude42<\/p>\n","protected":false},"excerpt":{"rendered":"
Last week, I shared my hack for syncing my browsing between my computer and mobile. It’s built around a Firefox extension, so I thought I’d share my notes on how I got it to work. This post is a complete sample for creating a Firefox extension to add a button to the browser toolbar. When […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[152,337,338],"class_list":["post-511","post","type-post","status-publish","format-standard","hentry","category-code","tag-firefox","tag-firefox-extension","tag-xul"],"_links":{"self":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/posts\/511","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=511"}],"version-history":[{"count":0,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=\/wp\/v2\/posts\/511\/revisions"}],"wp:attachment":[{"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=511"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=511"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dalelane.co.uk\/blog\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=511"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}