Page tree
Skip to end of metadata
Go to start of metadata

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.

  • No labels

1 Comment

  1. Unknown User (pnd1305)

    每个插件类都有一或多个JSAPI对象,提供JS交互接口。原始的JSAPI对象通常是作为根JSAPI对象,JSAPI对象源自FB::JSAPI类。多数JSAPI对象是从FB::JSAPIAuto帮助类继承而来。

    根JSAPI对象是从插件类返回值得到,是与JS交互的基本接口。其它的JSAPI是通过根JSAPI对象的方法或属性得到。

    JSAPI对象名称是插件名称+后缀api.由fbgen自动创建,例如插件类名称MyPlugin,JSAPI对象名称则为MyPluginAPI.

    JS可访问JSAPI对象的方法Method,内部属性Property,附加属性Attributes,事件EVents. Method,Property,Events需要事先在JSAPI对象注册声明之后才能被JS使用 ( Attributes是1.4新增的,后另作讨论)。

    Method-接受0到多个参数,有返回值,如未设置返回值,返回undefined,类似JS 的function

    Property--视同JSAPI的成员参数,在JSAPI对象内是需要有一个 getter获得的方法和一个可可选的setter设置方法来管理Property的。如果是只读的Property则不能设置Property的值了。

    Attributes–可由JS任意创建赋值,或由JSAPI对象创建的(只读的,而不能赋值)

    Events --如同一般的 DOM 事件 "onload", "onmousemove"的处理机制. Event在 JSAPI对象触发产生而引发callback函数回page .  events 是需要登记使用的,在IE用 attachEvent和在其它用 addEventListenerinscer