Yes, I wrote FireBreath. A lot of others have contributed.

A different approach to learning NPAPI

Now that I have a good example already up and running, it seems pointless to keep trying to describe things with words and code snippets when I can simply walk you through what I have done — what is in use and works well. To that end, and in hopes that it will foster more capable NPAPI developers to help with FireBreath development (we still don’t support printing, for example), I have created a series of 5 minute screencasts providing a brief overview of FireBreath’s NPAPI framework.

I don’t expect that this is as comprehensive as it should be; I’m hoping that comments will help me see what future segments I should create.  I have posted these screencasts on youtube and will link to them from here. You can also find a more complete series that includes this one on the FireBreath website.

One cardinal rule of browser plugins is that you should never block the thread when processing a method or property call from Javascript.  In FireBreath, that means that any method or property on your JSAPI must never block, but should return in a timely manner.

The reason for this is that Javascript is effectively not a multi-threaded language. The way that Javascript handles setTimeout and setInterval varies, but from the perspective of your plugin, all JSAPI calls come in on the same thread — the UI thread. If you block on a JSAPI call the whole web browser will lock up until you finish.

In the programming circles that I hang out in, this is considered a Bad Thing.

However, there are often cases when you may need to perform some operation that is inherently blocking — such as searching the filesystem, processing a large file, or making a network request. There are doubtless several ways you could deal with this, but perhaps the easiest is to run the blocking operation on a new thread, and then call back into Javascript when you’re done.

If you think about it, this is why AJAX calls are all asynchronous.

FB::JSObjectPtr to the rescue!

One of the types supported by FireBreath is FB::JSObject. This represents any type of Javascript object that is passed in — so basically anything other than a primitive datatype. This includes arrays, raw objects (key : value stores), and functions as well as other things like DOM objects.

FB:JSObject has a method InvokeAsync that works the same way as Invoke would on a normal JSAPI object except that the call is asynchronous, so it doesn’t have a return value and thus doesn’t wait for the call to complete before returning. If we want, we can even pass back a reference to the current API object in the callback. To call a function (instead of a method on an object), we pass an empty string in for the method name when we call Invoke or InvokeAsync.

// Say we have a FB::JSObjectPtr callback
callback->InvokeAsync("", FB::variant_list_of(shared_from_this()));

Creating a thread

FireBreath relies on the boost thread library; this means that it is quite simple to create a new thread, particularly to run something minor. Keep in mind that my purpose isn’t to talk about proper techniques for multithreaded programming, so you’ll have to worry about things like making sure that your threads have all ended before shutting down and so forth on your own.

With boost thread, basically you just create a function that will be run on the other thread and use boost::bind to provide that method object (with a shared_from_this to the object instance to keep it from going away while the thread is running) to the thread constructor. Edit 1/19/2010: Someone rightly pointed out that using shared_from_this may not be (in fact usually is not) optimal. If you want to stop the thread when the JSAPI object goes away, you should pass “this” instead of shared_from_this. The code below has been updated to reflect that.

    boost::thread t(boost::bind(&MyPluginAPI::doSomethingTimeConsuming_thread,
         this, num, callback));

Putting it together

bool MyPluginAPI::doSomethingTimeConsuming( int num, FB::JSObjectPtr &callback )
{
    boost::thread t(boost::bind(&MyPluginAPI::doSomethingTimeConsuming_thread,
         this, num, callback));
    return true; // the thread is started
}
 
void MyPluginAPI::doSomethingTimeConsuming_thread( int num, FB::JSObjectPtr &callback )
{
    // Do something that takes a long time here
    int result = num * 10;
    callback->InvokeAsync("", FB::variant_list_of(shared_from_this())(result));
}

As you can see, when doSomethingTimeConsuming is called it accepts a callback. It creates a new thread and gives it the callback function.

Synchronous calls

It should also be noted that calls to Invoke on a FB::JSObject will also be threadsafe — they can be called from any thread. Keep in mind that a mutex and signal are being used behind to scenes to block until after the call is made to Javascript on the main thread, so there will be a performance hit for this.

It is an interesting thing to me that so many people seem to have a hard time understanding how the FireBreath windowing abstraction works, since to me it seems fairly clear. Of course, I wrote it, so that’s probably the reason =] There are a few things you should understand before you start trying to do your drawing on Windows:

PluginWindow

Every platform has a PluginWindow.  In fact, some platforms (most notably Mac) have several different types of PluginWindow depending on which drawing model and event model you use.  The PluginWindow is the source of all system events for the plugin.

In the default plugin skeleton generated by fbgen there are several Events mapped:

BEGIN_PLUGIN_EVENT_MAP()
    EVENTTYPE_CASE(FB::AttachedEvent, onWindowAttached, FB::PluginWindow)
    EVENTTYPE_CASE(FB::DetachedEvent, onWindowDetached, FB::PluginWindow)
END_PLUGIN_EVENT_MAP()

Then the matching handlers are:

virtual bool onWindowAttached(FB::AttachedEvent *evt, FB::PluginWindow *wnd);
virtual bool onWindowDetached(FB::DetachedEvent *evt, FB::PluginWindow *wnd);

FB::AttachedEvent will be fired each time a window is attached to the plugin.  FB::DetachedEvent will be fired each time a window is detached from the plugin.  NOTE: Though in practice each of these usually get fired only once per plugin instance, there is no guarantee in the browser contract that it won’t take away the window it gave you and give you a different one.

PluginWindowWin

The main plugin object is, by default, a platform agnostic object.  There are several ways that you can do your windows specific drawing:

1. Make your plugin object windows specific
   

   This is certainly the easiest way, though the least friendly to cross-platform development; you could just change the type of the event source specified in EVENTTYPE_CASE to FB::PluginWindowWin (as well as the type in the handlers) and you will have your object cast in the way you need it.

   Note that FB::PluginWindowWin is in

   #include "Win/PluginWindowWin.h"

2. Create a platform specific subclass of your plugin object
   

   This is actually fairly easy. Simply create an object (Such as MyPluginWin) in the Win/ directory that extends your main (MyPlugin) object and move Factory.cpp into your Win/ directory.  If you support other platforms, you’ll need to create a subclass and factory for each platform you want to support.  Then modify each Factory.cpp so that createPlugin returns the platform-specific plugin object.  Then you can make platform-specific event code to get your PluginWindowWin object.

3. Use #ifdef FB_WIN to have platform specific code in your plugin object
   

   Don’t do this.  It’s messy and ugly.  Still, you can if you want. To get a PluginWindowWin* from your PluginWindow* object, you can do:

   FB::PluginWindowWin *pwnd = wnd->get_as<FB::PluginWindowWin*>();

4. Create a platform specific object and pass the window and other information to it to draw
   

   Use the same method mentioned previously to convert the PluginWindow to a PluginWindowWin. This is the method that the BasicMediaPlayer example (found in examples/) uses.

Once you have your PluginWindowWin object, you can get the information you need to do the actual drawing with a few functions:

1. getHWND() – returns the HWND assigned to the browser plugin
2. getBrowserHWND() – returns the HWND of the top-level browser window
3. InvalidateWindow() – instructs the browser to invalidate the window and give you a RefreshEvent (fired when a WM_PAINT is received)

When to draw

Once you have the HWND, the next thing you need to know is when you can draw.  There are a few guidelines:

• Whenever a RefreshEvent is received, you must redraw. If you are using a secondary thread to draw, make sure you have some way of passing the message to that thread or you will get flickering.
• You can create your own rendering / drawing loop and draw whenever you want. In order to do this, you must create thread to handle the drawing; remember that in the instance of a DetachedEvent you should be able to tell this to stop drawing! If you choose to use something like OpenGL or D3D, you should (sometimes must) do all initialization and drawing on the same secondary thread.
• Remember that these are windowed plugins, which means that the plugin will “float” above everything else on the page.

Handling custom windows messages (your own WINPROC)

If you need to handle the windows messages directly rather than using the FireBreath abstractions, there are two ways to do this.

1. Extend PluginWindowWin and override the virtual function CustomWinProc
   

   This is the most direct way; CustomWinProc will get called for all unhandled messages.  If you don’t do anything but return false in HandleEvent, all messages will be unhandled. To override which object is created for the PluginWindow, implement the createPluginWindowWin method on your Factory to return your custom window class (which must extend PluginWindowWin)

2. Handle WindowsEvent
   

   This is the way that we recommend. This can be done by simply adding an EVENTTYPE_CASE line. All of the arguments given in an event loop are available as members of the WindowsEvent object. This makes it possible to pass the object through to the correct place without having a platform-specialized class, if desired.

FireBreath is flexible

One of the main design goals of FireBreath is to allow a user to extend it however they want to make it work how they are most accustomed; that is why there are so many options. Some restrictions are imposed externally by the nature of browser plugins. In all things, we recommend doing the simplest thing and only override existing classes if you need to — those are the solutions most likely to break with future versions.

As always, if you have questions or need help, feel free to drop into the IRC room!

Recently I have been asked repeatedly about how to properly use Source Control systems with FireBreath.  Everyone has their own idea of how this should work, and that’s fine — in fact, most of my suggestions you may decide to ignore.  However, I want to put forth what I consider to be the “4 Best Practices” for keeping your FireBreath plugin in source control.

1. Use Source Control

I prefer to use Git, myself, with bzr or mercurial as close seconds.  Whatever source control system you prefer, though, I really highly recommend using something.  This isn’t advice specific to FireBreath, of course; it’s just good sense.

2. Move your projects/ directory outside of the FireBreath root

Directory Structure

This was one of the most requested features for a long time, and in 1.2.0 we finally added it. After you use fbgen.py to create your plugin project, move the projects/ dir somewhere outside of the root.  I use the following structure:

• code/
• code/firebreath/ – check out Firebreath here, or extract archive from the downloads area
• code/fbprojects/ – place your projects/ directory here, or wherever you want — it’s up to you
• code/fbprojects/MyPluginProject/ – this is what fbgen created, originally in firebreath/projects/MyPluginProject/

Generating the project files

From the code/ folder, you can then generate your project for XCode on Mac like so:

./firebreath/prepmac.sh fbprojects fbbuild

or if you are on Windows:

firebreath\prep2010.cmd fbprojects fbbuild

Linux users can use prepmake.sh or one of the others.

Please note: The Prep scripts are not intended to be run just once.  They should be run on each computer you build on, and they should be run anytime you add new files to your project or change plugin configuration options.  This is how CMake works, and FireBreath plugins rely on CMake to build. You can ignore this advice, but you will regret doing so.

3. Don’t put your build directory in version control

The build directory should not be in version control.  As many have noted, the paths are all absolute and not relative, and even if you were to fix this it would just make it harder to update FireBreath or change your plugin configuration.

The project files (.vcproj, .xcodeproj, makefiles, etc) are not intended to ever be edited by you.  Resist the urge to do so; I know this is a change for many, but it will simplify your lives.  The only files you should ideally change for project configuration are the cmake files in your project directory.

4. Don’t put FireBreath in the same source control tree

Many people want to keep their own copy of FireBreath internally.  This is, of course, just fine — it’s licensed under the New BSD license, so you can do about whatever you want. I strongly recommend that if you decide to do this, keep in in a git clone/fork. That way you can easily submit patches back to the FireBreath project if you make any changes, which means many others will be testing your fixes, and you can also more easily get patches from the FireBreath project into your local copy.

If you decide not to do this, still at least keep FireBreath and your projects seperate, because then you can easily update FireBreath when needed.

Wrapping up

I hope that clears up some things on this tricky topic. If you have any suggestions on how things can be improved, please feel free to let us know!  Of course, if your suggestion is “Don’t use cmake”, please make sure you have taken the time to understand why we are using it and have solutions for all the many problems that it solves =] That particular dead horse has been beaten nearly to oblivion.

Enjoy!

I have decided to start writing some tutorial type information for solving specific problems using FireBreath.  I don’t know how often I will post on this topic, but my goal is to do a series of short “tips and tricks” posts whenever I think of something that may not be obvious to someone starting out with the framework.

This post will discuss some best practices for using JSAPI objects. Feel free to request future articles in the comments.

boost::shared_ptr

The FB::JSAPIPtr type in FireBreath is just a convenience alias — mostly because I’m lazy — for boost::shared_ptr<FB::JSAPI>.  This is very important to understand, because if you try to use a normal pointer to your JSAPI derived objects without using shared_ptr, you’re likely to have your object disappear out from under you.

How it works

Basically when you create a boost::shared_ptr object, it allocates a small structure for holding two reference counts.  The first and most important is the use_count.  The second is the weak_count, and we’ll discuss that later.  The important thing to know is that every time you assign your shared_ptr to another, it increments the use_count.  Whenever a shared_ptr gets destroyed / goes out of scope, it decrements it.  Once that count hits 0, the object inside the shared_ptr goes away.

This is critical in FireBreath for JSAPI objects because we don’t know when the Browser will let go of our objects, and we can’t be deleting them while the browser still has a reference.

Creating objects

The best way to create a new object is to put it directly into a JSAPIPtr (or other shared_ptr).  You can (and should) also use boost::make_shared to be explicit. For example:

FB::JSAPIPtr myAPI(boost::make_shared<FBTestPluginAPI>());

This creates a new FBTestPluginAPI object and stuffs it into the myAPI JSAPIPtr.  Now, usually you’ll be passing something into the constructor, so it’ll look more like this:

FB::JSAPIPtr myAPI(boost::make_shared<FBTestPluginAPI>(FB::ptr_cast<FBTestPlugin>(shared_ptr()), m_host));

Of course, you may want a shared_ptr that allows you better access to your object.  If so, you can also do this:

boost::shared_ptr<FBTestPluginAPI> myAPI(boost::make_shared<FBTestPluginAPI>(FB::ptr_cast<FBTestPlugin>(shared_ptr()), m_host));

You can return this in a function that returns FB::JSAPIPtr and it will cast up-cast it implicitly just like a normal pointer.

There are a few unexpected things here:

• shared_ptr() - return a boost::shared_ptr<PluginEventSink> object, which is the ultimate base class for all Plugin objects (PluginCore derives from it).
• FB::ptr_cast<FBTestPlugin>(shared_ptr()) – FB::ptr_cast does a dynamic cast of a shared_ptr. This is basically an alias for boost::dynamic_ptr_cast, which is more of a pain to type.
• m_host – this is the BrowserHost object, which is useful to have around.  Think of it as a dependency injection container that gives you access to the browser functions and tools.

An important thing to realize here is that we aren’t storing the shared_ptr to the plugin object inside the JSAPI class. Instead, we’ll use a boost::weak_ptr.  A weak_ptr uses the other reference count, and the reference counting structure is not destroyed until both the use_count and weak_count hit 0.  To use the plugin from a weak_ptr, you use the .lock() method on the weak_ptr to get the shared_ptr for that class, which prevents it from being destroyed while you’re holding it. However, when you’re not using the plugin, it can be destroyed when the time comes.

This is important because the Plugin object usually has a reference to the API object, and we really don’t want circular references =]

Best practices state that you should always check to see if .lock() returns a NULL pointer indicating that the plugin has gone away.  We recommend a getPlugin() method on your API object like this:

boost::shared_ptr<FBTestPlugin> FBTestPluginAPI::getPlugin()
{
    boost::shared_ptr<FBTestPlugin> plugin = m_pluginWeak.lock();
    if (!plugin)
        throw FB::script_error("The plugin object has been destroyed");
    return plugin;
}

When you need to use it, simply call getPlugin() and make sure you let go of the resulting shared_ptr when you’re done.

Storing JSAPI objects

If you want to store an array of JSAPI objects, that’s just fine… but make sure you store them in an array of boost::shared_ptrs or boost::weak_ptrs depending on whether you want storing them to keep them around as long as your list is around.

Casting JSAPI objects

If you have a FB::JSAPIPtr and you want to cast it to your plugin API type, you can use either boost::dynamic_pointer_cast or FB::ptr_cast. For example:

boost::shared_ptr<FBTestPluginAPI> api( FB::ptr_cast<FBTestPluginAPI>(m_api) );

That’s it!

That’s it! The #1 thing to remember is to NEVER EVER EVER store or pass around a JSAPI object as a raw pointer.  That’ll get you in trouble =]

Beginning an open source project is probably one of the more cliché things to do in the industry. How many open source projects are out there that have almost no support, haven’t been updated in years, or are just plain useless?

This is the story of how I created FireBreath — and how it has remained a “high activity” project for a full year on Google Code. If you are short on time, I recommend skipping to the end of this article and reading the “Things I have learned” part.

The need for the project

A year ago I had an idea for a project that I felt would be benefited most — both in terms of project development and for anyone who would use it — by making the project open source. I wanted to create a framework for creating browser plugins. The problem? I just didn’t have the time to do it on my own time.

My big break came when a company out of California contacted me about building them a cross platform browser plugin framework. Now, let me explain a bit about my schedule: I was working full time for Move Networks, taking 10 credit hours at Utah Valley University, and my firstborn son was about 6 months old.

After some consideration, I agreed to do the project; my one stipulation was that they had to agree to allow me to release the code as open source. That week, I created the Google Code project for FireBreath (a name I selected randomly from a bunch I brainstormed) and uploaded the initial code — which was still mostly code generated by Visual Studio.

I also posted my Call for Plugin Developers here on colonelpanic and posted links to it on the NPAPI newsgroup.

The growth of the project

Getting started

I created the Google Code project September 16, 2009 — a year ago. Obviously, the project was ambitious; to provide a framework that not only allowed you to write plugins that would work in both Firefox and Internet Explorer, but to make it easy to simultaneously write them for Windows, Mac, and Linux — and to make it easier to write a plugin using FireBreath than straight NPAPI or ActiveX. I don’t care who you are or how brilliant you are, no one person by themselves can make a truly great project.

First Contributors

Several people expressed some interest, but then quickly disappeared (and in some cases simply stopped responding to emails.) Georg Fritzsche contacted me with some ideas about using C++ meta-programming to simplify the JSAPI interface. I’ll be honest — when I first read his explanation of what he wanted to do, my first thought was “This is crazy, and there is no way it can get simpler than it is.” However, it was one of the first direct offers of help that I’d seen, so I told him to share some more details with me on the mailing list and I’d look at what he had.

Nearly two weeks later, I had basically forgotten Georg and his suggestions that he could improve my Javascript interface when suddenly he posted a set of patches to the list. What was more, when I took a close look I realized that his ideas fit perfectly with the approach I was taking, and furthermore that I hadn’t the slightest idea how it worked. Georg’s understanding of meta-programming is still so far beyond mine that I ask him for help frequently whenever I mess with it. His “crazy” contributions now make up the JSAPIAuto class that nearly all Javascript API objects in FireBreath are built on.

From that point onward, Georg quickly made himself invaluable to the project; he wasn’t getting paid for his work (though he deserves it), so he didn’t spend as much time as I did, but it wasn’t too long before I just made him an owner of the project and started checking with him when I made changes. FireBreath would not be what it is without his early contributions, as well as those he has continued to make since then.

First releases

In December 2009 I posted FireBreath is Ready for Testing and posted a link on the NPAPI newsgroup. We now felt that FireBreath was far enough along that you could build a Windows plugin with it — although still no support for Linux or Mac. We started to see some real interest in the project outside the company I was working for: I had a couple people contact me asking for subcontracting help with FireBreath, and several individuals joined the project and asked about getting Linux and Mac support going.

Once there were some developers expressing interest, I gave them what information I could, and then in a fit of insanity took a few hours one night and got the initial support for Linux implemented. A few weeks later I did the same for Mac, after having a company contact both Georg and myself about possibly having us do a Mac plugin for them, although that never panned out.

Another piece, contributed initially by Ben Loveridge and Jarom Loveridge (brothers), is the “fbgen” tool — a tool that creates a skeleton plugin project for use with FireBreath. I believe this contributed significantly to the initial uptake of FireBreath.

Period of lower development

As all contracts inevitably do, the contract I was under for 10 hours a week of development on the browser plugin framework came to an end at the end of January 2010. I could no longer justify spending much time on FireBreath, but I knew it still wasn’t done. FireBreath lacked support for streams (HTTP downloads), good Mac and Linux windowing and system event integration, and threading support, to name just a few deficiencies.

However, the seeds had been planted: this really was a project that had the potential to save people a lot of time. Slowly at first, but then a little bit more as people found the project, developers started using FireBreath and contributing fixes for things that were missing. Georg and I continued to monitor the mailing list and answer questions, though neither of us had much time. But, little by little, users started to contribute fixes and enhancements for the missing functionality.

The project is picking up

One of the funnest things to do with this project has been to watch the Google Analytics reports for the project. In January of 2010 there were about 900 hits to the FireBreath website; last month there were about 2500. Granted, this isn’t a lot compared to large websites, but for a small open source project it isn’t bad.

One month that was particularly fun was when ajaxian.com put up a (very) short blog post about us. There were 4000 hits that day. That month had 10,000. We are also now up to about 100 members on the mailing list.

The latest and most encouraging development is that a little company in California called Facebook (heard of them?) has hired me as a contractor and is sponsoring some development with FireBreath. I can’t comment yet on what they may do with it, but the upshot is that I’m back to spending some real time on the project, and there are several nice features (like Unicode support) that 1.2 has that were contributed by Facebook.

Today we released FireBreath 1.2. It contains more features than any other browser plugin creation tool that I know of, fully supports Unicode characters both in processing and in method/property names, simplifies many tasks that would otherwise be extraordinarily painful, and allows you to create a basically cross-platform browser plugin in 10 minutes (if you have Python and Cheetah installed — although we are actively looking into removing the Cheetah dependency).

Lessons Learned

There are a lot of lessons to be learned from the experience of starting an open source project. Though its user-base may be small, I consider FireBreath to be a successful small project.

In no particular order, here are some things that I have learned:

• Once the initial feature set is in, it is more important to help newcomers than it is to code new features
  • Coding new features is more fun, but if you have time for just one — help people use your project
• Don’t be too obnoxious, but don’t be shy about telling people about your project.
  • Post short, tasteful mentions of your project on forums, preferably while you are helping someone
• Don’t ever write off someone’s idea without hearing it first
  • I can’t even remember how many times I have heard an idea that I initially thought “Huh, that wouldn’t work well,” but on further inspection turned out to be a great improvement. Almost invariably, these are the types of improvements that make the project glow.
• There is always something about your project that newcomers don’t appreciate or understand — be patient with them
  • The most criticized part of FireBreath’s design is that the project system relies on CMake. Windows developers in particular hate this. However, there are reasons; my standard response is “If you have a better idea that solves <problems solved by CMake>, please share.” I have never had any takers.
• Take the time to help others who are working in the same area
  • Competition is great, but if you’re really good at what you do, you don’t need to worry about helping others solve trivial problems. One of the top referrers for FireBreath is stackoverflow, where Georg and I have both answered many questions (often with links to FireBreath)
• Use a distributed version control system like Mercurial, Git, or Bzr if you can
  • Yes, I know that everyone knows how to use subversion; but when you have people who want to keep their own clone of your code and then be able to easily contribute back, distributed versioning tools are invaluable. (Oh, and that’s exactly what you want people to do.)
• Create an IRC chatroom
  • I was hesitant, but it has been a great way to interact with the users of the project
• Use the most permissive license type that makes sense
  • We started out using EPL, but found that many didn’t want to use our codebase because of licensing; we eventually switched to BSD, and people contribute back simply because they know their code will work better if their changes are vetted and tested by more people. In a framework, this makes sense; for an application, it may not.

Special Thanks To

While Georg has made some particularly valuable contributions to the project — contributing more code than anyone besides me — there are many others who have donated code snippets and time. Here is an incomplete list of people that I could find doing some simple searches in no particular order:

• Anson MacKeracher (amackera) – Built out Georg’s Mac drawing code to a fully usable state; if it’s Mac-specific and Anson didn’t write it, he still knows how it works.
• nitrogenycs – Streams support, and many other small bugfixes.
• Kalev Lember – Numerous small fixes, one of the main testers and tweakers for linux.
• Antti Andreimann (anttix)- Helped to build the initial XEmbed support for linux, and wrote EvaluateJavascript.
• schmoo – Provided the initial patch to support Visual Studio 2010 as well as other minor fixes.
• Schnapple – Miscellaneous bugfixes.
• Ben and Jarom Loveridge – One started and one finished the fbgen tool. Jarom is working to remove the Cheetah dependency.
• Kevin Menard (nirvdrum) - Testing, ideas, and support.

And, of course, thanks to everyone who uses FireBreath; you make this project successful!

The comments on this blog are full of questions particularly about browser plugins, and even more specifically about NPAPI plugins.  Now, I don’t mind helping people out at all; that’s how we all learn.  However, in an effort to help everyone help each other, I wanted to bring the IRC chat room for FireBreath to everyone’s attention.

IRC Chatroom

To date, there are about 4 of us who are usually in the chatroom, and we discuss more than just FireBreath.  FireBreath is a project that combines experience with NPAPI, ActiveX/COM, and cross platform development in a fairly unique way.  We benefit from interaction with anyone working on any of these technologies.  What I’m trying to say is, feel free to bring your plugin questions of *any* type to that room.  We won’t do your work for you and we don’t promise to have an answer to every question, but we have a pretty decent understanding of the subject between us.

Where it is

The server is irc.freenode.net.  The channel is #firebreath.

See you there.

One of the least understood concepts in the Browser Plugin world is — browser plugins.  What they are, and even more: what they are not.  Probably at least once a week I answer a question somewhere on a forum or on the comments on this blog and say “You can’t do that with a plugin; you need an extension”.

Many people confuse plugins and extensions in the browser world. They sound like they should be the same thing, but in fact they are very different.

What you can do with a plugin

A plugin is, quite simply, a third party library that “plugs in” to the browser that can be embedded inside a web page using an <embed> tag or a <object> tag.  Many of them then draw pretty pictures or animations, though that’s not required.  Many allow you to talk to them through javascript, though that’s not required.  In short, a plugin affects only a specific page in which it is placed.

Examples of common plugins include:

• Macromedia Flash
• Microsoft Silverlight
• Apple Quicktime
• Adobe Reader (at least this includes a plugin in addition to the rest of the application)

Some plugins respond to a mime type and can run in place of the page, such as Adobe Reader, which allows you to view PDF files in your web browser.  Again, however, it affects only that page, and no others.  In Firefox, Chrome, Opera, and Safari, these plugins are usually called “NPAPI plugins”, since they are written using the NPAPI.  In Safari, you could also use a Webkit Plugin.  In Internet Explorer you would do this with an ActiveX Control.

What a plugin cannot do

Plugins have to either handle a mime type or be embedded into a web page.  They don’t get put there automatically. They don’t create toolbars.  They don’t affect browser menus.  They don’t know about tabs, or even about other pages in the same browser process.  They don’t make coffee, tea, or hot chocolate, though they could be written to control an external appliance to do so if you really wanted.  They don’t automatically process the content of every web page loaded.

“But wait!” I hear you all cry.  “We have seen these magical things done! (well, except the hot chocolate machine)”

“Yes,” I reply.  “Those are extensions.”

Extensions

Extensions, or “add-ons”, can often do these magical things.  They can add onto the browser UI, process pages that the browser loads.  They do all sorts of things.  However, they are not the same thing as plugins; they affect the web browser itself, not really the page.  They may affect a page as well, of course.  In fact, you can even put a plugin inside an extension, at least in Firefox.  However, if you write an extension for Firefox, you’ll probably have to write it again for Chrome, Safari, and IE… one for each.  Perhaps there is a framework out there for writing portable extensions, though.  It’s not really my area of expertise, so I don’t know.

Examples of extensions / add-ons:

• DownThemAll for Firefox
• Firebug for Firefox
• Google Voice extension for Chrome
• Let there be Comic Sans for Safari

And many, many, many more.  Extensions can be written in different languages depending on the browser.  In Firefox you can write them in C++ or javascript, and on Internet Explorer you write them as special ActiveX controls called Browser Helper Objects, or BHOs.

An extension could contain a plugin, but a plugin can’t contain an extension

One very common way to install a plugin in Firefox is to use a .xpi file.  This is an extension.  It may have a NPAPI plugin inside of it, but it is still an extension.  It will not work on other web browsers, even though your NPAPI plugin may work perfectly fine on Chrome and Safari if installed in another way.

Conversely, a plugin by nature does not include an extension.

FireBreath

Nearly a year ago now I began a project called FireBreath, which is a cross-platform browser plugin architecture.  FireBreath is, frankly, awesome. You can literally get a plugin up and going in under 10 minutes if you already have everything installed.  That means you can spend your time doing other more important things, like actually developing your functionality, rather than spending all your time figuring out how to deal with the plugin APIs.

That said, FireBreath is a cross-platform browser PLUGIN framework.  It does not create extensions.  It will never be able to create extensions.  If you need an extension, you need something else.

When not to use a plugin

Finally, and this is a topic that people seem to think is a little strange coming from me, there are many cases when it is not a good idea to use a browser plugin.  In fact, a good rule of thumb is that if you can do what you need to do without one, don’t use one.

Why?

• There are no really good ways to install browser plugins that will work 100% of the time
  • XPI install only works on one profile in firefox
  • CAB install only works in Internet Explorer and is sometimes a little unreliable
  • ClickOnce works only in Windows and only if .Net is installed
  • Java installers only work reliably and consistently on Mac OS
  • MSI or EXE installers while being the best method IMHO require a little more work on the part of the user, and the average user is… less savvy than you are, shall we say.
• Plugins have to take into account a large range of hardware types
  • If you use graphics libraries such as OpenGL or DirectX keep in mind that every graphics card works a little differently with these technologies.  You will run into weird cases where your plugin doesn’t work on someone’s computer.  If your luck is like mine, that computer will belong to an executive at a fortune 500 company (yes, that happened to me.  no, it wasn’t fun)
• Plugins don’t work until they have been installed
  • This is a major limiting factor to uptake of your site.  Many users don’t want to install yet another plugin on their machine, and many get lost in the incredibly complicated task of downloading and running the installer.

Moving on

If all of those things haven’t convinced you that what you want isn’t actually a browser plugin — great!  That’s why I’m still posting about this stuff.  Despite all the reasons not to use a plugin, there are also a lot of cases where it’s a good idea. Browesr plugin development can be a lot of fun!  Good luck!

Firefox 3.6 has removed support for XPCOM plugins.

This means that if you use XPCOM for your javascript interface (i.e. you have an IDL file on your npapi plugin, you us nsScriptablePeer, etc) your plugin will no longer be able to communicate with javascript in Firefox 3.6.

Thus I repeat advice that I have given in the past: Never, never, *never*, *ever* use XPCOM for your javascript interface in your plugin.

There might conceivably be reasons to use other aspects of XPCOM in a plugin, that might even work in other browsers. At present, I don’t know of them. Please enlighten me if there are (cookies?).

Oh, yeah, and FireBreath now has linux and mac support (experimental) as well as windows support (stable). Come join the fun. http://firebreath.googlecode.com

Thank you. :-P

I’ll be up-front about something here; I don’t particularly like ActiveX.  I understand a lot of the reasons for creating it, and I won’t go so far as to claim that it shouldn’t exist or anything like that; in fact, it does very well for certain types of things.  The main thing I don’t like about it is the complexity; it’s not something that you just pick up and start using one day.  You have to do a lot of research to understand what is happening, and though I’ve been working on ActiveX Controls hosted in Internet Explorer for over a year now, there is still a lot I don’t understand about what is really happening under the covers.

Because of this, I am a big fan of NPAPI.  I think it’s a great technology.  It’s simple.  It’s straightforward.  It provides an interface for one purpose, and that is to allow 3rd party developers to write browser plugins.  It’s great.  But, there is a problem: in my world, you can’t just say “I like Firefox better than IE, so I’m not going to support IE.”  Why?  I will make no claims here about security, usability, viability, or even disability of any browsers.  I will simply refer to one statistic: according to the w3schools browser statistics, Internet Explorer accounted for over 25% of the total web traffic every month last year.

So we find the classic challenge of all browser plugin developers: Internet Explorer only supports ActiveX controls, other browsers support NPAPI, and a plugin written for one isn’t neccesarily going to be easy to just port to the other.  Thus was born FireBreath, in an attempt to solve this issue.  Today, however, I want to address only one piece of the solution that we use in FireBreath:  How to create a scripting interface that will be “write once, run anywhere” on web browsers.

Common Scripting Interface

When I first began working on plugins, I worked on a project that had 3 seperate defintions of the javascript interface to the plugin.  One was for Mac, one for Internet Explorer on Windows, and one for Firefox on Windows.  The IE version was defined in an ActiveX .idl file and implemented in an ActiveX object.  The Firefox/win one was defined in an “XPCOM” .idl file and implemented in a nsScriptablePeer object (copied from a sample plugin from the mozilla source), and the Mac one was defined using NPRuntime and wrapped the XPCOM class.

This was, in short, a nightmare.

The problem I was initially trying to solve is that we had some APIs that had to be used differently on Mac and Windows, and they differed in less noticeable ways between Firefox and IE on Windows.  Don’t get me wrong — it all worked just fine.  However, from a maintenance point of view, this was certainly not optimal.  I could give a lot of meaningless history here, but eventually I came up with an idea that I dubbed (at that company) the Common Scripting Interface — a class that contained all the aspects that a good javascript object would need, but was not specific to any one browser.

Down with the IDL

Okay, this is where I’m going to start raising a lot of eyebrows.  I respectfully submit that using an IDL, as it is defined by Internet Explorer, is generally a bad idea on a control intended to be used from Javascript.  Why?  Simply put, Javascript is a dynamic language; when you pass parameters around, they are not type constrained.  Most javascript functions don’t care if you give them an integer, a string, a bool, or something else; they just use the parameters they are given.  Of course it’s a bit more complicated than that, but Javascript inherently is dynamic.  Thus, it can be important to have the ability to use a dynamic interface on a plugin that interfaces with it.

I hasten to remind you at this point that making an interface dynamic just for the sake of it being dynamic is a bad idea.  However, there are many use cases where you may have members (particularly properties that expose other javascript objects) that may only be named and become accessible at runtime; it’s too late to add something to the IDL.  I believe this is part of the reason that we have settled on NPRuntime on Gecko-based browsers, and Microsoft created an IDispatchEx interface to better support it on ActiveX.  Thus, we have all the tools we need to create a dynamic interface, and I have loosely patterned it after the NPAPI/NPRuntime interface, which I consider to be a fairly good interface for browser plugins.

What is JSAPI?

If you have looked at all at the FireBreath project that I have been working on for the last several months, you may have looked at or seen reference to the JSAPI class.  JSAPI stands for Javascript API.  JSAPI is intended to be a Javascript compatible object written in C++.  It relies heavily on the FB::variant class, which essentially is a class that you can put any datatype in.  If there is enough interest, I can blog more about that type later, but suffice it to say it’s very similar to boost::any but with data conversion tools built in.  A JSAPI object (an object that extends FB::JSAPI) provides all functionality that a Javascript object should, whether it is used or not.

What does a Javascript object do?

Let’s take a big step backwards now.  Forget anything you know about Browser Plugins or ActiveX Controls.  Forget anything you even know about C++, Java, C#, Logo, or any other language, even, except Javascript, HTML, DHTML, and CSS.  Those are the tools of the browser.  When we design the interface for a Browser Plugin, we shouldn’t be thinking like a C++ developer.  We should be looking at it the way we would if we were writing an object in Javascript; we should provide the interfaces that we would expect to find, and use the tools and syntax that we would expect to find in Javascript.

So, let’s look at what a Javascript object can do:

• Javascript objects can have methods that accept parameters and return a value

  • var coolData = plugin.doSomething(1, 1, 2, 3, 5, "right now");

• Javascript objects can expose properties that a caller can get or set:

  • var oldName = plugin.name;

  • plugin.name = "Some cool name";

• Javascript objects can provide events, to which a caller can attach an event handler in the syntax of their browser:

  • plugin.addEventHandler("click", function() { alert("The user clicked on me! Ouch!"); }, false);

  • plugin.attachEvent("onclick", function() { alert("The user clicked on me! Ouch!"); });

When you write it out like this, it doesn’t seem like much; remember, though, that a property of a javascript object could return any primitive datatype, an array, or even another javascript object, itself containing methods, properties, and events.

The JSAPI Interface

One additional thing to remember about a Javascript Object (now taking into account what we know about C++ as well) is that we don’t control the lifecycle of a javascript object.  What that means is that your plugin may go away before Javascript is done with the object that you gave it.  So, if that object uses any references to your plugin, (And what plugin javascript object wouldn’t? It’s the interface to the page, right?) you need to have a way to deal with not only cleaning up your object even after the plugin goes away, but making sure that the javascript object somehow finds out that the object it depends on is gone and invalidates itself in some way.  One way to do that is by using Shared pointers and Weak pointers, but that’s a topic for another day.

Like the NPObject and IDispatch types that provide its interface with the browser, JSAPI is reference counted, so that it will get destroyed whenever the browser.  Here are the method prototypes from JSAPI.h to satisfy the requirements mentioned above.  You can also look at the full source of JSAPI.h if you want.

Methods

// ...
    virtual bool HasMethod(std::string methodName) = 0;
    virtual variant Invoke(std::string methodName, std::vector<variant>& args) = 0;
// ...

Not much is required; one call to find out if the method exists, one to invoke the method.  Notice that the arguments is passed in a STL vector of type variant; you can pass any datatypes in here, but that will be limited by the Browser-level wrapper that converts the arguments from the browser datatype (VARIANT on IE, NPVariant on firefox) to the JSAPI variant datatype.  I’ll discuss this in more detail in a later post.

Properties

// ...
    virtual bool HasProperty(std::string propertyName) = 0;
    virtual bool HasProperty(int idx) = 0;
 
    virtual variant GetProperty(std::string propertyName) = 0;
    virtual variant GetProperty(int idx) = 0;
    virtual void SetProperty(std::string propertyName, const variant value) = 0;
    virtual void SetProperty(int idx, const variant value) = 0;
// ...

You’ll notice one strange thing right off the bat here; there are two of each method.  One takes a std::string for the first parameter, one takes an int.  Any thoughts on why?

Imagine the following code:

for (var i = 0; i < plugin.files.length; i++) {
    alert(plugin.files[i]);
}

This is a pretty standard piece of javascript code, right?  Array access notation is pretty common in Javascript.  Javascript, however, treats everything as an object of one kind or another. An array to javascript is really just an object with numeric properties.  Similarly, we need to be able to support numeric properties for array style access.  That is why we have extra property methods for a property identified by an “int”.

Events

// ...
    virtual void registerEventMethod(std::string name, BrowserObjectAPI *event);
    virtual void unregisterEventMethod(std::string name, BrowserObjectAPI *event);
    virtual void registerEventInterface(BrowserObjectAPI *event);
    virtual void unregisterEventInterface(BrowserObjectAPI *event);
    virtual BrowserObjectAPI *getDefaultEventMethod(std::string name);
    virtual void setDefaultEventMethod(std::string name, BrowserObjectAPI *event);
 
protected:
    // Used to fire an event to the listeners attached to this JSAPI
    virtual void FireEvent(std::string eventName, std::vector<variant>&);
// ...

Events are by far the most difficult piece of this whole class; we have to make allowances for multiple methods of registering events and multiple browsers’ methods for keeping track of the handlers. The BrowserObjectAPI type that you see used here is also a JSAPI object, but one that wraps a browser object (an NPObject or a IDispatch object, depending on the browser).

There are three different ways an event can be registered (at this point in time):

1. Through a “user-defined” event registering method implemented by our browser scripting object wrapper (this is used by all objects on firefox and all but the root object on IE).
   • The BrowserObjectAPI object will essentially be a method that we can invoke by calling InvokeAsync with empty string (“”) as the method name
2. Through the Connection Point interface on an ActiveX Control (obviously used on the root object in IE)
   • The BrowserObjectAPI object will be an object on which we can invoke a method of the same name as the event it is attached to
3. Through a property of the same name as the event (old-style javascript events, as in “document.onload = ….”
   1. The BrowserObjectAPI object will essentially be a method that we can invoke by calling InvokeAsync with empty string (“”) as the method name

These three types are the reason that we have three different register/unregister methods on the browser for events.  When FireEvent is called by the JSAPI child object (that you write), it iterates through all possible event handlers and invokes them asynchronously.  (Events have to be invoked on the main UI thread of the plugin, so the InvokeAsync call on BrowserObjectAPI automatically makes sure that is where it gets called; hence it’s async).

Next time

We have discussed and looked at the basic needs of the JSAPI object.  Part two will discuss the COMJavascriptObject class and the JSAPI_IDispatch helper class that constitute the interface between ActiveX and our JSAPI interfaces.  Part three will cover the NPJavascriptObject that provides the interface between NPRuntime and JSAPI.  Feel free to read ahead in the source =]

In the mean time, if you like where this is going and want to play with FireBreath and see JSAPI in action for yourself, there are some really easy getting started instructions on the FireBreath project page.