Merge pull request #33 from nytm/for-3-0-0

For v3.0.0

Author: maxrbaldwin

README.md

@@ -9,19 +9,37 @@
 ## Installation
 
 ```
-npm install --save nytm/nyt-react-tracking#v2.2.1
+npm install --save nytm/nyt-react-tracking#v3.0.0
 ```
 
 (Or whatever is the [latest version](https://github.com/nytm/nyt-react-tracking/releases))
 
 ## Usage
 `@track()` expects two arguments, `trackingData` and `options`.
-- `trackingData` represents the data to be tracked
+- `trackingData` represents the data to be tracked (or a function returning that data)
 - `options` is an optional object that accepts three properties:
   - `dispatch`, which is a function to use instead of the default CustomEvent dispatch behavior. See the section on custom `dispatch()` later in this document.
   - `dispatchOnMount`, when set to `true`, dispatches the tracking data when the component mounts to the DOM. When provided as a function will be called on componentDidMount with all of the tracking context data as the only argument.
   - `process`, which is a function that can be defined once on some top-level component, used for selectively dispatching tracking events based on each component's tracking data. See more details later in this document.
 
+#### Tracking `props`
+
+The `@track()` decorator will expose a `tracking` prop on the component it wraps, that looks like:
+
+```js
+{
+  // tracking prop provided by @track()
+  tracking: PropTypes.shape({
+    // function to call to dispatch tracking events
+    trackEvent: PropTypes.func,
+
+    // function to call to grab contextual tracking data
+    getTrackingData: PropTypes.func,
+  })
+}
+```
+
+### Usage as a Decorator
 `nyt-react-tracking` is best used as a `@decorator()` using the [babel decorators plugin](https://github.com/loganfsmyth/babel-plugin-transform-decorators-legacy).
 
 The decorator can be used on React Classes and on methods within those classes.
@@ -50,15 +68,15 @@ export default class FooPage extends React.Component {
 
 ### Usage on Stateless Functional Components
 
-You can also track events by importing `track()` and wrapping your stateless functional component, which will provide `props.trackEvent()` that you can call in your component like so:
+You can also track events by importing `track()` and wrapping your stateless functional component, which will provide `props.tracking.trackEvent()` that you can call in your component like so:
 
 ```js
 import track from '@nyt/nyt-react-tracking';
 
 const FooPage = (props) => {
   return (
     <div onClick={() => {
-        props.trackEvent({ action: 'click' });
+        props.tracking.trackEvent({ action: 'click' });
 
         // ... other stuff
       }}
@@ -213,34 +231,25 @@ NOTE: That the above code utilizes some of the newer ES6 syntax. This is what it
 // ...
 ```
 
-### Using Data at Run Time
-Any data that is passed to the decorator can be accessed in the decorated component via its props. The component that is decorated will be returned with a prop called `tracking`. The prop `tracking` is an object that has a `getTrackingData` method attached to it. This method returns the results of the object or function that was passed into the decorator.
+#### Example `props.tracking.getTrackingData()` usage
+
+Any data that is passed to the decorator can be accessed in the decorated component via its props. The component that is decorated will be returned with a prop called `tracking`. The `tracking` prop is an object that has a `getTrackingData()` method on it. This method returns all of the contextual tracking data up until this point in the component hierarchy.
 
 ```js
 import React from 'react';
 import track from '@nyt/nyt-react-tracking';
 
 // Pass a function to the decorator
-@track((props) => {
+@track(() => {
   const randomId = Math.floor(Math.random() * 100);
 
   return {
     page_view_id: randomId
   }
 })
 export default class AdComponent extends React.Component {
-  // The tracking object with getTrackingData is returned from the decorator and applied to this component via props
-  constructor(props) {
-    super(props);
-  }
-
-  componentDidMount() {
-    // access get tracking data anywhere in the component
-    this.trackingData = this.props.getTrackingData();
-  }
-
   render() {
-    const { page_view_id } = this.trackingData;
+    const { page_view_id } = this.props.tracking.getTrackingData();
 
     return (
       <Ad pageViewId={page_view_id} />
@@ -250,8 +259,6 @@ export default class AdComponent extends React.Component {
 }
 ```
 
-####Example
-
 ### Tracking Data
 
 Note that there are no restrictions on the objects that are passed in to the decorator.

build/withTrackingComponentDecorator.js

@@ -63,9 +63,7 @@ function withTrackingComponentDecorator() {
       dispatch = _ref$dispatch === undefined ? _dispatchTrackingEvent2.default : _ref$dispatch,
       _ref$dispatchOnMount = _ref.dispatchOnMount,
       dispatchOnMount = _ref$dispatchOnMount === undefined ? false : _ref$dispatchOnMount,
-      process = _ref.process,
-      _ref$trackingDataProp = _ref.trackingDataProp,
-      trackingDataProp = _ref$trackingDataProp === undefined ? true : _ref$trackingDataProp;
+      process = _ref.process;
 
   return function (DecoratedComponent) {
     var _class, _temp;
@@ -86,10 +84,14 @@ function withTrackingComponentDecorator() {
           (0, _lodash2.default)({}, _this.trackingData, data));
         };
 
-        _this.getTrackingData = function () {
-          return (0, _extends3.default)({}, _this.trackingData);
+        _this.tracking = {
+          trackEvent: _this.trackEvent,
+          getTrackingData: function getTrackingData() {
+            return _this.trackingData;
+          }
         };
 
+
         if (context.tracking && context.tracking.process && process) {
           console.error('[nyt-react-tracking] options.process should be used once on top level component');
         }
@@ -110,7 +112,7 @@ function withTrackingComponentDecorator() {
         value: function getChildContext() {
           return {
             tracking: {
-              data: this.trackingData,
+              data: (0, _lodash2.default)({}, this.contextTrackingData, this.ownTrackingData),
               dispatch: this.getTrackingDispatcher(),
               process: this.context.tracking && this.context.tracking.process || process
             }
@@ -138,10 +140,7 @@ function withTrackingComponentDecorator() {
         key: 'render',
         value: function render() {
           return _react2.default.createElement(DecoratedComponent, (0, _extends3.default)({}, this.props, {
-            tracking: {
-              trackEvent: this.trackEvent,
-              getTrackingData: trackingDataProp ? this.getTrackingData : null
-            }
+            tracking: this.tracking
           }));
         }
       }]);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyt/nyt-react-tracking",
-  "version": "2.2.2",
+  "version": "3.0.0",
   "description": "Declarative tracking for React apps.",
   "author": "The New York Times",
   "contributors": [