|
|
| Line 255: |
Line 255: |
| * graphUtils: A reference to a live instance of the [http://code.google.com/p/flot/ flot] JS chart-plotting library, which you can use to draw graphs as you see fit. | | * graphUtils: A reference to a live instance of the [http://code.google.com/p/flot/ flot] JS chart-plotting library, which you can use to draw graphs as you see fit. |
|
| |
|
| === Observer === | | === handlers === |
|
| |
|
| (TODO WAAAY out of date)
| | The '''handlers''' object exported by your experiment has the very important responsibility of actually doing the data collection, and inserting the collected data into the store you defined in dataStoreInfo. |
|
| |
|
| The Observer of your experiment has the very important responsibility of actually doing the data collection, and passing the collected data along to the store you defined in dataStoreInfo.
| | There is only a single handlers object; it is a global singleton and not, for example, a per-window object. |
|
| |
|
| Observer must be a constructor function, a.k.a. a "class". It will be called like this:
| | '''handlers''' must define the following functions, named exactly as they appear here. Each function is called by the extension when the appropriate event occurs. Exactly what your handlers do in response to these events is up to you. |
|
| |
|
| new yourExperiment.Observer(window, store);
| | * onNewWindow(window) |
| | * onWindowClosed(window) |
| | * onAppStartup() |
| | * onAppShutdown() |
| | * onExperimentStartup(store) |
| | * onExperimentShutdown() |
| | * doExperimentCleanup() |
| | * onEnterPrivateBrowsing() |
| | * onExitPrivateBrowsing() |
|
| |
|
| One Observer is instantiated for each window that is opened in the user's browser. A reference to that window is passed in as the first argument to the constructor function.
| | The file '''study_base_classes.js''' defines a class called GenericGlobalObserver that defines appropriate responses to each of these events. It also defines a GenericWindowObserver helper class for installing per-window observers, which is a very common use case. I strongly recommend extending GenericGlobalObserver, overriding methods you want to customize, and then setting '''exports.handlers''' to a new instance of your subclass. This is explained in more detail in the [[/Labs/Test_Pilot/Experiment_Tutorial Experiment Tutorial]]. |
| | |
| The second argument to the constructor function is a reference to the single data store object. (No matter how many Observers are instantiated, they all get a reference to the same dataStore instance.) See the dataStoreInfo section above. Your Observer can call .storeEvent() on this store object to save events to the database.
| |
| | |
| The Observer has chrome privileges, so it has free reign to use XPCOM components and so on to do the needed observations.
| |
| | |
| Besides the constructor, your Observer must provide an uninstall() method, which is called (with no arguments) when the observer is no longer needed. Any cleanup that you need to do (such as unregistering listeners, etc.) must be done in the uninstall() method.
| |
| | |
| ==== Example Observer ====
| |
| | |
| Here's the skeleton of an Observer:
| |
| | |
| exports.Observer = function MyExperimentObserver(window, store) {
| |
| this._init(window, store);
| |
| };
| |
| exports.Observer.prototype = {
| |
| _init: function MyExperimentObserver__init(window, store) {
| |
| console.info("Initializing a new MyExperimentObserver.");
| |
| this._window = window;
| |
| this._dataStore = store;
| |
| // Install desired listeners, event handlers, etc. into the window here
| |
| // e.g. register this._onClick as an event handler...
| |
| },
| |
| uninstall: function MyExperimentObserver_uninstall() {
| |
| console.info("Uninstalling a MyExperimentObserver.");
| |
| // Unregister this._onClick and any other registered event listeners
| |
| // from this._window
| |
| },
| |
| _onClick: function MyExperimentObserver_onClick(clickEvent) {
| |
| var eventToRecord;
| |
| // Process clickEvent, calculate the properties of the event you want
| |
| // to record, then write it to the data store:
| |
| console.info("Recording a click event.");
| |
| this._dataStore.storeEvent(eventToRecord);
| |
| }
| |
| };
| |