Please feel free to add to these pages! The documentation is a wiki, and anyone can sign up. Note that all modifications will be moderated by the development team.

Introduction to JSAPI

Every plugin class has one or more JSAPI object which provides the interface to Javascript. The primary JSAPI object is commonly referred to as the Root JSAPI object. We call something a JSAPI object if it derives from the FB::JSAPI class. Most JSAPI objects derive from the FB::JSAPIAuto helper class.

• FB::JSAPI - JavaScript API base class
• FB::JSAPIAuto - JavaScript API Automatic helper class

The Root JSAPI object is returned by your plugin class and is the primary interface that is accessible to Javascript. Your plugin can provide additional JSAPI objects that can be returned by Methods or Properties on your Root JSAPI object.

JSAPI objects are named by convention with the suffix "API". The fbgen tool creates the root JSAPI object named the same as your plugin object with the API suffix appended. e.g. for the plugin object "MyPlugin", the JSAPI object is commonly named "MyPluginAPI".

Example

If your object tag looks like this:

<object id="plugin" type="application/x-fbtestplugin" width="300" height="300">
    <param name="onload" value="pluginLoaded" />
</object>

Your plugin resides then in the object tag with id="plugin". Once the plugin is loaded, you can access it using javascript through that element like so:

function doSomething() {
    var plugin = document.getElementById("plugin");
    alert(plugin.valid);
}

Methods, Properties, Attributes, and Events

JSAPI exposes four basic types of interfaces to JavaScript. Each of these types must be registered in the constructor of your JSAPI object (except Attributes, which are new in 1.4, which we will talk about below.) For more information and instructions on using each of these interface types, click on the name.

• Methods - Methods are what you would expect; they accept zero or more arguments and return some value. Methods that do not explicitly return a value will return undefined, just like a JavaScript function.

  plugin.doSomethingCool(3, 4, "Some string", window.myFunction);

• Properties - Properties are accessed like a member variable, but they have a getter and optionally a setter in your JSAPI class. Properties with only a getter are read-only and will throw an exception if you try to assign to them.

  // This will call getValid in the JSAPI class. This property is defined by default on all JSAPIAuto objects var val = plugin.valid // This will call setSomeValue in the JSAPI class, assuming that we registered the property to have that method be the setter for SomeValue plugin.SomeValue = "my awesome string value";

• Attributes - Attributes are new in FireBreath 1.4 and basically act as regular class member variables with no special function being called to set or get them. Attributes can be created from JavaScript arbitrarily or can be set from within your JSAPI class – optionally as read-only.

  plugin.someWeirdAttributeThatHasNeverBeenSeenBefore = 34423.5; alert(plugin.someWeirdAttributeThatHasNeverBeenSeenBefore); // Unless explicitly disallowed, this will work and will alert 34423.5 var val = plugin.SOME_CONST_VAL; // If you register a const attribute in your plugin you can use it easily as a constant from javascript

• Events - Events work similarly to normal DOM events such as "onload", or "onmousemove". They originate from a JSAPI object and make callbacks into the page. Following standard conventions, events are registered using attachEvent in IE and addEventListener in all other browsers.

  plugin.attachEvent("onstuff", function(val) { alert("Stuff happened: " + val); }); // -or- plugin.addEventListener("stuff", function(val) { alert("Stuff happened: " + val); }, false);

Compatible Types

Once you have a basic understanding of how these interfaces work, you will also want to read up on the types that are supported by JSAPIAuto.