[DO NOT MERGE] Comments on the current implementation

.eslintrc.js

@@ -40,6 +40,7 @@ module.exports = {
     "mocha"
   ],
   root: true,
+  ignorePatterns: [ "compiled-ts/**/*.js" ],
   rules: {
     "node/no-deprecated-api": "error",
     "node/no-extraneous-require": "off",

.gitignore

@@ -105,3 +105,11 @@ dist
 
 # Generated study files
 web-ext-artifacts/
+
+# Compiled Typescript .js
+compiled-ts/
+
+.DS_Store
+
+# Testing output files
+tests/output/

README.md

@@ -1,80 +1,14 @@
-# Mozilla Rally study template.
-The purpose of this repository is to provide a starting point to build a Rally study. It contains:
+# Search Engine Usage Study
+A study to assess how individuals interact with their search engines.
 
-1. an example [`manifest.json`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file.
-2. an example background and content script in `src/`.
-3. a rollup config file that builds the files needed for the web extension using the source files in `src/` (the background & content scripts).
-4. an example integration test that launches a browser & installs the add-on.
-5. a `web-ext-config.js` file & an eslint configuration.
-
-## Getting started
-
-1. Fork this repository.
-2. Customize the [manifest.json](./manifest.json) file:
-  * change the `name`, `author`, and `description` properties;
-  * swap the value of `application.gecko.id` (e.g. `[email protected]`) with the one provided you by the Rally team;
-3. Customize the [package.json](./package.json) file. At a bare minimum, change the `name`,`description`, `version`, `author`, `repository`, `bugs`, and `homepage` properties;
-4. Provide the encryption data to the `Rally` class constructor in the [src/background.js](./src/background.js) file:
-
-```js
-rally.initialize(
-  // A sample key id used for encrypting data.
-  "sample-invalid-key-id",
-  // A sample *valid* JWK object for the encryption.
-  {
-    "kty":"EC",
-    "crv":"P-256",
-    "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
-    "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
-    "kid":"Public key used in JWS spec Appendix A.3 example"
-  },
-  // ... other required arguments ...
-);
-```
-
-4. From the forked repository directory, install all the NPM dependencies:
-
-```bash
-fork-dir> npm install .
-```
-
-5. Test the customized study in Firefox and commit your changes: doing this right after the initial fork provides a nice and clean cutting point with the original repository, which will simplify future updates (if needed).
-
-## Building upon this template
-This template uses [rollup.js](https://rollupjs.org/) as a module bundler and NPM for dependency management. The [manifest.json](./manifest.json) file already includes a sample background scripts.
-
-Dependencies can be added using the [`npm install`](https://docs.npmjs.com/cli/v6/commands/npm-install) command, using the appropriate `--save-dev` or `--save-prod` switch. This command will take care of automatically updating the [package.json](./package.json) file.
-
-New modules can be added in the `src/` directory. Modules need to expose the exported functions using the `module.exports` syntax. For example, a class can be exported as follows in a `MyClass.js` file:
-
-```js
-module.exports = class MyClass {
-  myFunc() {
-    console.log("Testing!");
-  }
-}
-```
-
-And then be imported in another file with `const MyClass = require("./MyClass.js");`.
-
-Plain functions can be exposed as follows in a `MyFuncs.js` file:
-
-```js
-module.exports = {
-  myTest() {
-    //... something!
-  },
-  otherFunc() {
-    // ... other function!
-  }
-};
-```
-
-And then be imported in another file with `const {myTest, otherFunc} = require("./MyFuncs.js");`.
+## Requirements
+* [Node.js](https://nodejs.org/en/), available via [Homebrew](https://brew.sh/) on macOS
+* [Mozilla web-ext](https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/)
 
 ## Supported NPM commands
-The template comes with a set of pre-defined NPM commands (to run as `npm run <command>`) to help study authors:
+The repo comes with a set of pre-defined NPM commands (to run as `npm run <command>`):
 
+* `compile-typescript`: Compiles the Typescript source code. The compiled code is saved in the `src/` directory.
 * `build`: assembles the final addon. The bundler generated code is saved in the `dist/` directory.
 * `dev`: assembles the addon in _developer mode_. In this mode data doesn't get submitted but, instead, is dumped to the [Browser Console](https://developer.mozilla.org/en-US/docs/Tools/Browser_Console). This mode allows for a smoother development process.
 * `lint`: run linting on the add-on code.
@@ -85,3 +19,5 @@ The template comes with a set of pre-defined NPM commands (to run as `npm run <c
 
 ## Manual testing in the browser
 To test, either load as a temporary add-on in Firefox (`about:debugging`) or Chrome ("developer mode" in `chrome://extensions`) or use `npm run start`.
+
+Debugging output is available in Tools → Web Developer → Browser Console. Make sure that the Show Content Messages option is checked. You might find it helpful to set a filter for debugging messages of interest.

experimental/api.js

@@ -0,0 +1,155 @@
+/**
+ * @file Implementation for experimental API.
+ * 
+ * It provides definitions for the functions and events
+ * defined in the schema.
+ * @module WebScience.Experiments.experimental
+ */
+
+const { Services } = ChromeUtils.import("resource://gre/modules/Services.jsm");
+
+/**
+ * @description Using experiments_api feature to define new APIs linked to 
+ * the extension. experimental is exposed under the global browser object and 
+ * is accessible from background scripts.
+ */
+this.experimental = class extends ExtensionAPI {
+    getAPI() {
+        return {
+            experimental: {
+                async createPopup(searchEngineOld, searchEngineNew, modalPrimaryRevert) {
+                    // Returns whether the search engine should be reverted.
+                    const flags =
+                        Services.prompt.BUTTON_TITLE_IS_STRING * Services.prompt.BUTTON_POS_0 +
+                        Services.prompt.BUTTON_TITLE_IS_STRING * Services.prompt.BUTTON_POS_1;
+
+                    if(modalPrimaryRevert) {
+                        const x = Services.prompt.confirmEx(
+                            null,
+                            `Change back to ${searchEngineOld} Search?`,
+                            `Your search engine has been changed to use ${searchEngineNew}.`,
+                            flags,
+                            "Change it back",
+                            "Keep it",
+                            null,
+                            null,
+                            {}
+                        );
+                        return x === 0;
+                    } else {
+                        const x = Services.prompt.confirmEx(
+                            null,
+                            `Change back to ${searchEngineOld} Search?`,
+                            `Your search engine has been changed to use ${searchEngineNew}.`,
+                            flags,
+                            "Keep it",
+                            "Change it back",
+                            null,
+                            null,
+                            {}
+                        );
+                        return x === 1;
+                    }
+                },
+                /**
+                 * Changes the user's default search engine
+                 * 
+                 * @function
+                 * @param {string} searchEngineName - name of search engine to make default
+                 */
+                async changeSearchEngine(searchEngineNameIn) {
+                    const searchEngineDetailsObject = {
+                        google: {
+                            iconURL: "https://www.google.com/favicon.ico",
+                            alias: "@google",
+                        },
+                        bing: {
+                            iconURL: "https://www.bing.com/favicon.ico",
+                            alias: "@bing",
+                        },
+                        yahoo: {
+                            iconURL: "https://www.yahoo.com/favicon.ico",
+                            alias: "@yahoo",
+                        },
+                        duckduckgo: {
+                            iconURL: "https://duckduckgo.com/favicon.ico",
+                            alias: "@duckduckgo",
+                        },
+                        ecosia: {
+                            iconURL: "https://cdn.ecosia.org/assets/images/ico/favicon.ico",
+                            alias: "@ecosia",
+                        },
+                        yandex: {
+                            iconURL: "https://yastatic.net/iconostasis/_/KKii9ECKxo3QZnchF7ayZhbzOT8.png",
+                            alias: "@yandex",
+                        },
+                        baidu: {
+                            iconURL: "https://www.baidu.com/favicon.ico",
+                            alias: "@baidu",
+                        },
+                        ask: {
+                            iconURL: "https://www.ask.com/logo.png",
+                            alias: "@ask",
+                        },
+                    }
+
+                    const searchEngineName = searchEngineNameIn.toLowerCase();
+
+                    // Wait for the search service to initialize and un-hide all the default engines
+                    await Services.search.init()
+                    Services.search.restoreDefaultEngines();
+
+                    let searchEngine = null
+
+                    // Retrieves the engine we are attempting to make default
+                    // from the list of installed engines
+                    const installedSearchEngines = await Services.search.getEngines()
+                    for(const installedSearchEngine of installedSearchEngines) {
+                        if(installedSearchEngine.name.toLowerCase().includes(searchEngineName)) {
+                            searchEngine = installedSearchEngine
+                            break
+                        }
+                    }
+
+                    // If the engine we are attempting to make default is not
+                    // already installed, swe add it through an OpenSearch xml file
+                    if(!searchEngine) {
+                        searchEngine = await Services.search.addOpenSearchEngine(`https://citpsearch.cs.princeton.edu/searchengine/openSearch/${searchEngineName}.xml`, searchEngineDetailsObject[ searchEngineName ].iconURL)
+                        searchEngine.alias = searchEngineDetailsObject[ searchEngineName ].alias
+                    }
+
+                    // Make sure the engine is not hidden, move it to the top of the list of options, and make it the default
+                    searchEngine.hidden = false
+                    Services.search.moveEngine(searchEngine, 0);
+                    Services.search.defaultEngine = searchEngine
+                },
+                /**
+                 * Get the user's current default search engine
+                 * @function
+                 */
+                async getSearchEngine() {
+                    await Services.search.init();
+                    const defaultEngine = await Services.search.getDefault()
+                    return defaultEngine ? defaultEngine.name : "";
+                },
+                /**
+                 * Get the user's current default search engine
+                 * @function
+                 * @param {string} newHomepage - url of the new homepage
+                 */
+                changeHomepage(newHomepage) {
+                    Services.prefs.setCharPref("browser.startup.homepage", newHomepage)
+                },
+                /**
+                 * Get the user's current default search engine
+                 * @function
+                 */
+                async getHomepage() {
+                    return Services.prefs.getCharPref("browser.startup.homepage")
+                },
+
+
+            }
+        }
+    }
+}

experimental/schema.json

@@ -0,0 +1,70 @@
+[
+  {
+    "namespace": "experimental",
+    "functions": [
+      {
+        "name": "createPopup",
+        "type": "function",
+        "description": "Create popup",
+        "async": true,
+        "parameters": [
+          {
+            "name": "searchEngineOld",
+            "type": "string",
+            "description": "The engine that the default search was changed from."
+          },
+          {
+            "name": "searchEngineNew",
+            "type": "string",
+            "description": "The engine that the default search was changed to."
+          },
+          {
+            "name": "modalPrimaryRevert",
+            "type": "boolean",
+            "description": "Whether the revert button is the primary button on the modal dialog."
+          }
+        ]
+      },
+      {
+        "name": "changeSearchEngine",
+        "type": "function",
+        "description": "Change the user's default search engine",
+        "async": true,
+        "parameters": [
+          {
+            "name": "searchEngineName",
+            "type": "string",
+            "description": "name of search engine to make default"
+          }
+        ]
+      },
+      {
+        "name": "getSearchEngine",
+        "type": "function",
+        "description": "Get the user's current search engine",
+        "async": true,
+        "parameters": []
+      },
+      {
+        "name": "changeHomepage",
+        "type": "function",
+        "description": "Change the user's homepage",
+        "async": false,
+        "parameters": [
+          {
+            "name": "newHomepage",
+            "type": "string",
+            "description": "url of the new homepage"
+          }
+        ]
+      },
+      {
+        "name": "getHomepage",
+        "type": "function",
+        "description": "Get the user's homepage",
+        "async": true,
+        "parameters": []
+      }
+    ]
+  }
+]