1,007
edits
Labs/Test Pilot/ExperimentAPI: Difference between revisions
Jump to navigation
Jump to search
→dataStoreInfo
| Line 87: | Line 87: | ||
dataStoreInfo provides parameters for the initialization of a client-side SQLite database table which will be used to store the events that your experiment records. It's basically a schema description, that is fed to an object-relational mapper built into the extension. | dataStoreInfo provides parameters for the initialization of a client-side SQLite database table which will be used to store the events that your experiment records. It's basically a schema description, that is fed to an object-relational mapper built into the extension. | ||
Your Observer objects (see below) will get passed a Store object, and whenever they want to record an event, they'll pass an event object into | Your Observer objects (see below) will get passed a Store object, and whenever they want to record an event, they'll pass an event object into Store.storeEvent();. The info you provide in dataStoreInfo determines how the properties of this event object get mapped to the columns in the database. | ||
dataStoreInfo must have the following properties (all required): | |||
* fileName: The name of the file where the SQLite database should be kept (inside the user's profile directory). It should be as descriptive as possible and end with ".sqlite". | * fileName: The name of the file where the SQLite database should be kept (inside the user's profile directory). It should be as descriptive as possible and end with ".sqlite". | ||
* tableName: The name of the database table to create inside this file. It should be descriptive and must not have spaces. | * tableName: The name of the database table to create inside this file. It should be descriptive and must not have spaces. | ||
* columns: An array of objects, each describing a single database column. The properties that each column object must specify are as follows: | * columns: An array of objects, each describing a single database column. Each column corresponds to one property on the event objects that you plan to pass in to storeEvent(). The properties that each column object must specify are as follows: | ||
** property: | ** property: What property of the event object will be mapped to this column. For example, if you plan to pass in event objects that have a .timestamp property, then you will want a column object with property: "timestamp". | ||
** type | ** type: A code specifying the data storage type of the column. Not all data types are supported by the client yet. (TODO: explain this better) | ||
** displayName: | ** displayName: The human-readable name that will be used to label this column whenever we display database contents. Can have spaces. Should be Title Cased. | ||
** displayValue (optional): | ** displayValue (optional): If not provided, then the raw value that is stored will be what is displayed whenever we display database contents. If it is provided, it tells the client how to display the contents of this column. It must be either an array of strings, or a function that returns a string. If it's a function, the raw value will be passed into the function and the return value will be what's displayed. If it's an array, the raw value will be used as an index into the array, and the string at that index will be what's displayed (useful for enumerated type codes). | ||
** default (not yet implemented): | ** default (not yet implemented): What value to use if the eventObject passed in does not have a property matching this column. | ||
=== | === Example of declaration === | ||
const TABS_EXPERIMENT_FILE = "testpilot_tabs_experiment_results.sqlite"; | |||
/* In this schema, each row represents a single UI event. */ | |||
const TABS_TABLE_NAME = "testpilot_tabs_experiment"; | |||
exports.dataStoreInfo = { | |||
fileName: TABS_EXPERIMENT_FILE, | |||
tableName: TABS_TABLE_NAME, | |||
columns: TABS_EXPERIMENT_COLUMNS | |||
}; | |||
{property: "event_code", type: TYPE_INT_32, displayName: "Event", | |||
displayValue: ["", "Open", "Close", "Drag", "Drop", "Switch", "Load", "Startup", | |||
"Shutdown", "Window Open", "Window Close"]}, | |||
{property: "tab_position", type: TYPE_INT_32, displayName: "Tab Pos."}, | |||
{property: "tab_window", type: TYPE_INT_32, displayName: "Window ID"}, | |||
{property: "ui_method", type: TYPE_INT_32, displayName: "UI Method", | |||
displayValue: ["", "Click", "Keyboard", "Menu", "Link", "URL Entry", "Search", | |||
"Bookmark", "History"]}, | |||
{property: "tab_site_hash", type: TYPE_INT_32, displayName: "Tab Group ID"}, | |||
{property: "num_tabs", type: TYPE_INT_32, displayName: "Num. Tabs"}, | |||
{property: "timestamp", type: TYPE_DOUBLE, displayName: "Time", | |||
displayValue: function(value) {return new Date(value).toLocaleString();}}]; | |||
=== Example of storing event objects === | |||
== webContent == | == webContent == | ||
== Observer == | == Observer == | ||