Merge branch 'master' of https://github.com/googleinterns/measurement-library into pageviewSpecificDocs

Author: Alex7Li

README.md

@@ -15,9 +15,6 @@ Measurement library will provide an open source alternative for sites/apps to se
 - [Usage](#usage)
     - [Event Command](#event-command)
     - [Set Command](#set-command)
-- [Local Setup](#local-setup)
-    - [Creating the build](#creating-the-build)
-    - [Running Tests Interactively](#running-tests-interactively)
 
 # Overview
 Measurement Library is a utility to help developers send data collected from their website to
@@ -63,8 +60,9 @@ but reports possible errors to the console.
 ```
 
 # Usage
-After setting up the script tags, you can begin to use the library. All commands
-are processed by passing arguments to the  `measure()` function. 
+After setting up the script tag using the `config` command, you can begin to use the library. All commands
+are processed by passing arguments to the `measure()` function. 
+
 
 ## Event command
 When you run the command `measure('event', eventName, eventOptions)`, all registered
@@ -74,57 +72,6 @@ to their API.
 ## Set command
 To save parameters beyond the current page, you can call the command `measure('set', key, value)`.
 The registered event processor will determine if the value should be saved, how long the value should
-be saved for, and save it. To overwrite this behavior, you can specify a third time-to-live parameter:
-`measure('set', key, value, secondsToLive)`. In particular, if `secondsToLive` is 0, no data will be saved
-to long term storage.
-
-The set command can also be used to set parameters related to a implementation of
-an event processor or storage interface. For example, to modify the default parameters
-of the cookies storage, run a `set` command in the script tag before calling
-`config`. 
-
-```js
-// Set the default cookie parameters
-measure('set', 'cookies', {prefix: 'my_', expires: 11});
-// Use the default cookie parameters: prefix 'my_' and expires 11.
-measure('config', 'eventProcessorName', {}, 'cookies', {});
-// Override a default cookie parameter: expires is 22 for this storage.
-measure('config', 'eventProcessorName', {}, 'cookies', {expires: 22});
-```
-# Local Setup
-## Creating The Build
-You will need to have either [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
-or [yarn](https://classic.yarnpkg.com/en/docs/install/#debian-stable) installed.
-
-First, install dependencies with yarn or npm
-```shell script
-yarn install
-# or
-npm install
-```
-
-Next, run the tests using yarn or npm:
-
-```shell script
-yarn test
-# or
-npm run test
-```
-
-## Running Tests Interactively
-You can also run the tests "interactively" via Karma directly.
-
-```shell script
-yarn unit
-# or
-npm run unit
-```
-
-To run the integration tests instead of the unit tests,
-
-```shell script
-yarn integration
-# or
-npm run integration
-```
-
+be saved for, and save it in the corresponding [storage](https://googleinterns.github.io/measurement-library/#StorageInterfaces).
+To overwrite this behavior, you can specify a third time-to-live parameter:
+`measure('set', key, value, secondsToLive)`. In particular, if `secondsToLive` is 0, no data will be saved to long term storage.

docs/LocalSetup.md

@@ -0,0 +1,37 @@
+# Local Setup
+## Creating The Build
+You will need to have either [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+or [yarn](https://classic.yarnpkg.com/en/docs/install/#debian-stable) installed.
+
+First, install dependencies with yarn or npm
+```shell script
+yarn install
+# or
+npm install
+```
+
+Next, run the tests using yarn or npm:
+
+```shell script
+yarn test
+# or
+npm run test
+```
+
+## Running Tests Interactively
+You can also run the tests "interactively" via Karma directly.
+
+```shell script
+yarn unit
+# or
+npm run unit
+```
+
+To run the integration tests instead of the unit tests,
+
+```shell script
+yarn integration
+# or
+npm run integration
+```
+

docs/PersistentParameters.md

@@ -0,0 +1,56 @@
+# Persistent Parameters
+## Sharing Constructor Arguments
+If you have many storage interfaces on the page that should have the same settings,
+you can call the `set` command before calling the `config` command to share parameters automatically,
+passing in the name of the storage interface as the first argument to `set`. 
+
+```js
+// Set the default cookie parameters
+measure('set', 'cookies', {prefix: 'my_', expires: 11});
+// Use the default cookie parameters: prefix 'my_' and expires 11.
+measure('config', 'googleAnalytics', {}, 'cookies', {});
+// Override a default cookie parameter: expires is 22 for this storage.
+measure('config', 'googleAnalytics', {}, 'cookies', {expires: 22});
+```
+
+Since custom storage interfaces do not have a name, to enable the behavior of shared arguments for a custom object,
+you must implement the static getName() method, returning the string that should be passed as the first argument
+to set.
+
+The example above used a storage interface, but it works exactly the same for an event processor. However,
+with event processors, you should think of the set command and constructor arguments as a way to share
+event options between processors, as detailed in the next section.
+
+## Sharing Event Options
+If you have many processors on a page that should share several event options, then calling
+`measure('set','processorType', persistingOptions)` will set parameters that persist from each
+call to `measure('event', eventName, eventOptions)`.
+To distinguish between multiple processors of the same type, parameters set in the `measure(config, ...)`
+command will override these values. Additionally, any parameters set in `eventOptions` will override the other 2.
+Note that the order that you call config or set in does not matter - either order produces the same
+result.
+
+```js
+// Set the default parameters.
+// Call the constructor with {}
+measure('config', 'googleAnalytics', {}, 'cookies', {});
+measure('set', 'googleAnalytics', {animal: 'dog', color: 'red'});
+// Call the constructor with {currency: 'USD', animal: 'cat', color: 'blue'}
+measure('config', 'googleAnalytics', {currency: 'USD', animal: 'cat', color: 'blue'}, 'cookies', {});
+// The first processor sees the eventOptions parameter as
+//     {animal: 'dog', color: 'green'}
+// The second processor sees the eventOptions parameter as
+//     {currency: 'USD', animal: 'cat', color: 'green'}
+measure('event', 'name', {color: 'green'});
+```
+So the set command will add arguments to both the constructor and every event, and the constructor
+will also add arguments to every event.
+
+### Edge cases
+When overwriting data, values are shallow-copied, so the first value is overwritten in the next example
+```js
+// The default parameters are {options: {a: 1}}
+measure('set', 'googleAnalytics', {options: {a: 1}});
+// The default parameters are {options: {b: 2}}, not {options: {a: 1, b: 2}}
+measure('set', 'googleAnalytics', {options: {b:'2'}});
+```

docs/README.md

@@ -67,54 +67,3 @@ be saved for, and save it. To overwrite this behavior, you can specify a third t
 `measure('set', key, value, secondsToLive)`. In particular, if `secondsToLive` is 0, no data will be saved
 to long term storage.
 
-The set command can also be used to set parameters related to a implementation of
-an event processor or storage interface. For example, to modify the default parameters
-of the cookies storage, run a `set` command in the script tag before calling
-`config`. 
-
-```js
-// Set the default cookie parameters
-measure('set', 'cookies', {prefix: 'my_', expires: 11});
-// Use the default cookie parameters: prefix 'my_' and expires 11.
-measure('config', 'eventProcessorName', {}, 'cookies', {});
-// Override a default cookie parameter: expires is 22 for this storage.
-measure('config', 'eventProcessorName', {}, 'cookies', {expires: 22});
-```
-
-# Local Setup
-## Creating The Build
-You will need to have either [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
-or [yarn](https://classic.yarnpkg.com/en/docs/install/#debian-stable) installed.
-
-First, install dependencies with yarn or npm
-```shell script
-yarn install
-# or
-npm install
-```
-
-Next, run the tests using yarn or npm:
-
-```shell script
-yarn test
-# or
-npm run test
-```
-
-## Running Tests Interactively
-You can also run the tests "interactively" via Karma directly.
-
-```shell script
-yarn unit
-# or
-npm run unit
-```
-
-To run the integration tests instead of the unit tests,
-
-```shell script
-yarn integration
-# or
-npm run integration
-```
-****

docs/_sidebar.md

@@ -1,5 +1,7 @@
 * [Home](/)
+* [PersistentParameters](PersistentParameters.md)
 * Recommended Parameters
     * [Pageview](Pageview.md)
 * [Event Processors](EventProcessors.md)
 * [Storage Interfaces](StorageInterfaces.md)
+* [Local Setup](LocalSetup.md)

src/config/configProcessors.js

@@ -85,6 +85,41 @@ function buildProcessor_(constructor, params) {
   }
 }
 
+/**
+ *  Perform a merge on the given list of objects. Any properties that both
+ *  the ith and jth (i less than j) objects both share will be overwritten
+ *  to have just the property of the jth object.
+ *
+ *  @param {...} args The objects to merge.
+ *  @return {!Object<string, *>}
+ */
+const merge = function(args) {
+  const result = {};
+  for (let i = 0; i < arguments.length; i++) {
+    const toMerge = arguments[i];
+    for (const prop in toMerge) {
+      if (toMerge.hasOwnProperty(prop)) {
+        result[prop] = toMerge[prop];
+      }
+    }
+  }
+  return result;
+};
+
+/**
+ *  Get extra parameters that are stored in the data layer for a given object.
+ *
+ *  @param {?DataLayerHelper} helper
+ *  @param {?Object} object The object that we would like to get parameters of.
+ *  @return {!Object<string, *>}
+ */
+const getExtraOptions = (helper, object) => {
+  if (helper && object && object.hasOwnProperty('getName')) {
+    return /** @type {!Object<string, *>} */ (helper.get(object.getName()));
+  }
+  return {};
+};
+
 /**
  * When called with an implementation of the eventProcessor and
  * storageInterface API, this function registers processors to react to the
@@ -153,6 +188,8 @@ function registerEventAndSet_(helper, processor, eventOptions, storage) {
   function processEvent(name, options = undefined) {
     const model = this;
     if (!options) options = {};
+    options = merge(getExtraOptions(helper, processor.constructor),
+      eventOptions, options);
     processor.processEvent(/** @type {!StorageInterface} */(storage),
       model, name, options);
   }

test/unit/config/buildProcessor_test.js

@@ -7,14 +7,14 @@ const GoogleAnalyticsEventProcessor = goog.require('measurementLibrary.eventProc
 describe('Calling the buildProcessor_ function of configProcessors', () => {
   it('returns an event processor when a valid string is passed', () => {
     expect(buildProcessor_('googleAnalytics', {})).toBeInstanceOf(
-        GoogleAnalyticsEventProcessor);
+      GoogleAnalyticsEventProcessor);
+  });
+
+  it('returns an event processor when a class is passed in ', () => {
+    expect(buildProcessor_(GoogleAnalyticsEventProcessor, {}))
+      .toBeInstanceOf(GoogleAnalyticsEventProcessor);
   });
 
-  it('returns an event processor when a class is passed in ',
-      () => {
-        expect(buildProcessor_(GoogleAnalyticsEventProcessor, {}))
-          .toBeInstanceOf(GoogleAnalyticsEventProcessor);
-      });
   it('eeturns false when an invalid string is passed in ', () => {
     expect(buildProcessor_('unimplemented', {})).toEqual(null);
   });