open-index/open-npm huggingface dataset:
npm package: @holler/thneed
Description: Event tracking middleman
Author: Jess Edwards
Latest version: 2.0.3

# Thneed

> A Thneed's a Fine-Something-That-All-People-Need!

## Usage guide
If you would like to track events already implemented by a developer, visit the [usage guide](USAGE.md).

## Developer guide
Thneed acts as a middleman between application code and analytics code. Analytics code subscribes to certain events, which are then triggered by application code.

### Triggering events
Trigger events like so:
```js
import thneed from '@holler/thneed';

const scope = 'bookTestDrive';
const data = {
    formName: 'bookTestDrive',
    formData: {
        variant: 48,
        date: '2016-12-25',
    },
};

thneed.trigger(thneed.events.formSubmitSuccess, scope, data);
```

#### Function signature
```js
thneed.trigger(eventName, scope, data, disableWarning);
```

`eventName` is a string representing the event name

`scope` must be a camelCase string representing the scope of the event taking place. This would usually be the name of the component triggering the event.

`data` must be an object containing any relevant data that could be useful to analytics. It could include:

- The form name
- The form data
- The id of the element clicked
- Or anything else

`disableWarning` is a boolean that should be provided if using events other than those provided by `thneed.events` (see below)

Make sure you document the scopes and data object keys you use.

#### Using other events
Note that Thneed exposes a selection of events under `thneed.events`. (You can see the default events at the top of [thneed.js](https://bitbucket.org/holler/thneed/src/master/src/thneed.js).) If you wish to use an unsupported event, you may use any string, e.g.

```js
thneed.trigger('gravityMalfunction', 'earth', {});
```

Note that this will trigger a warning in your console. To disable the warning, just add a fourth parameter `true`.

### Exposing Thneed to Analytics
When first imported into your project, Thneed will automatically attach itself to the `window` object. If there are multiple versions being used in the one project, importing Thneed will always return the first one attached to the `window`.

```js
import thneed from '@holler/thneed';
```