canmove, Confirmed users
2,056
edits
Labs/JS Modules: Difference between revisions
Jump to navigation
Jump to search
documentation for version 0.2 of the Observers module
m (→StringBundle) |
(documentation for version 0.2 of the Observers module) |
||
| Line 60: | Line 60: | ||
== Observers == | == Observers == | ||
The [http://hg.mozdev.org/jsmodules/file/tip/Observers.js Observers module] provides an API for observing | The [http://hg.mozdev.org/jsmodules/file/tip/Observers.js Observers module] provides an API for sending and observing notifications using the [http://mxr.mozilla.org/mozilla/source/xpcom/ds/nsIObserverService.idl observer service]. It is designed to make it easy for JavaScript code to send notifications containing JavaScript values (including data structures such as Arrays and Objects) to JavaScript observers. | ||
=== Notifying Observers === | |||
Notify observers by calling <code>Observers.notify</code> with the topic, subject, and data of the notification: | |||
Observers.notify("topic", someSubject, "some data"); | |||
The subject and data parameters are both optional. The subject parameter can be any JS value. The data parameter must be a string, and it is deprecated, since strings can just as easily be passed through the subject parameter: | |||
Observers.notify("topic", "some data"); | |||
If you need to pass multiple values, pass them through the subject parameter via a JavaScript data structure that stores multiple values, like an Array or an Object: | |||
Observers.notify("topic", [17, 33, 10]); | |||
Observers.notify("topic", { foo: 1, bar: true, baz: "stuff" }); | |||
=== Registering a Function Observer === | |||
Register a function as an observer by calling <code>Observers.add</code> with the topic to observe and the function to observe it: | |||
function someFunction(subject, data) {...}; | |||
Observers.add("something", someFunction); | |||
When receiving a notification, the function will be called with the notification's subject and data parameters. The function will not be given the notification's topic parameter. | |||
=== Registering a Method Observer === | |||
Register a method as an observer by calling <code>Observers.add</code> with the topic to observe, the method to observe it, and the object to which the method belongs: | |||
let someObject = { | |||
onSomething: function(subject, data) {...}, | |||
}; | |||
Observers.add("something", someObject.onSomething, someObject); | |||
When receiving a notification, the method will be called with the notification's subject and data parameters. The method will not be given the notification's topic parameter. | |||
=== Registering an Object Observer === | |||
Register an object that implements the [http://mxr.mozilla.org/mozilla/source/xpcom/ds/nsIObserver.idl nsIObserver interface] as an observer by calling <code>Observers.add</code> with the topic to observe and the object to observe it: | |||
let someObject = { | |||
observe: function(subject, topic, data) {...} | |||
}; | |||
Observers.add("something", someObject); | |||
When receiving a notification, the object's observe method will be called with the notification's subject, topic, and data parameters, in that order, which is compatible with the type signature of the [http://mxr.mozilla.org/mozilla/source/xpcom/ds/nsIObserver.idl nsIObserver] interface. Note, however, that unlike the nsIObserver interface the value of the subject parameter will be a JavaScript value, not an XPCOM object, when the notifying code uses <code>Observers.notify</code> to send the notification. | |||
=== Unregistering Observers === | |||
Unregister observers by calling <code>Observers.remove</code> with the same parameters you passed to <code>Observers.add</code>: | |||
Observers.remove("topic", someFunction); | |||
Observers.remove("topic", someObject.onSomething, someObject); | |||
Observers.remove("topic", someObject); | |||
Note: the Observers module wraps observers in a wrapper that implements [http://mxr.mozilla.org/mozilla/source/xpcom/base/nsIWeakReference.idl?mark=71-94#71 nsISupportsWeakReference], so you don't necessarily have to remove your observers to avoid leaking memory. Nevertheless, it is good practice to do so anyway. | |||
=== Version 0.1 API === | |||
[http://hg.mozdev.org/jsmodules/file/524485431738/Observers.js Version 0.1 of the module] had the following incompatible API: | |||
You can register ordinary functions as observers: | You can register ordinary functions as observers: | ||
| Line 82: | Line 142: | ||
Note: you can use this module to observe notifications generated by any XPCOM component, and you can send notifications whose subject is an XPCOM component, but only JavaScript consumers of this API can send and receive notifications whose subject is an arbitrary JavaScript object. | Note: you can use this module to observe notifications generated by any XPCOM component, and you can send notifications whose subject is an XPCOM component, but only JavaScript consumers of this API can send and receive notifications whose subject is an arbitrary JavaScript object. | ||
=== Upgrading from 0.1 to 0.2 === | |||
To upgrade an application that uses version 0.1 of the module to version 0.2, do the following: | |||
# switch the order of the first two arguments in all your calls to <code>Observers.notify</code>; | |||
# remove the topic parameter from the type signature of any function observer; | |||
# if a function observer handles multiple topics, refactor it into multiple functions that each handle one topic, or convert it into an nsIObserver object with an observe method. | |||
=== Changelog === | |||
* 0.2 | |||
** changed interface of Observers.add and Observers.remove to take an optional thisObject parameter; | |||
** stopped passing topic parameter to observers that are functions; | |||
** switched order of topic and subject parameters to Observers.notify; | |||
** fixed bug that sometimes caused an observer to unregister another observer of the same topic; | |||
** fixed bug that subjects that are JS XPCOM components and have wrappedJSObjects are unwrapped. | |||
* 0.1 | |||
** Initial release. | |||
== Preferences == | == Preferences == | ||