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:

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:

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.
• 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.
• 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.
• 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.

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.