@d-cat/ddm-core v2.4.1

Getting started with @d-cat/ddm-core

The DigitalData Manager (DDM) provides an API for centralized access to the DigitalData object in the DOM. In addition the DDM provides an event mechanism for data changes as well as general event handling and persistence. Please note that DDM fully supports Google Tag Manager. Each DDM event, automatically syncs with Google Tag Manager's dataLayer.

Install

npm i @d-cat/ddm-core

Usage

import DDM from '@d-cat/ddm-core';

const dataLayer = new DDM();

Parameters

Members

events {name: string, timestamp:number, data?: object}[]

The events array. This keeps track of all events that were triggered using the DDM trigger function. It is publically available using dataLayer.events, which is a direct reference to the events array.

getDDMState (): object

Returns DDM state. This method is mainly used for the DDM debugger (chrome extensions) and debugging options.

Example

const { props } = dataLayer.getDDMState();

set <T>(path: string, value: T, persist?: boolean, ttl?: int): T

Stores an object at a given dot notated path. Existing properties with the same name will be overwritten; except if an object already exists at the given path, the provided data will be merged with the existing object.

Parameters

Example

dataLayer.set('dot.notated.path', 'value');

get <T>(path?: string, defaultValue?: T, createNonExisting?: boolean): T

Retrieve data from DDM Core for a given dot-notated path, or the entire dataLayer when no path given. If no value/object is available at the path, you can optionally create the value/object at that path using a provided value. The later is merely for convenience. When no path is given, the entire dataLayer will be returned.

Parameters

Example

const { user } = dataLayer.get('user.id');

has (path: string): boolean

Determines whether the dataLayer has a value at the given path. Returns true if the value at the given path is not undefined. False otherwise.

Parameters

Example

if (dataLayer.has('user.id')) {
  console.log('yaay');
}

empty (path: string): boolean

Determines whether the object at the given path is null, an empty object/array, an empty string or does not exist at all. Take note that a string consisting of only whitespace is also regarded as empty and that integer values are never regarded as being empty.

Parameters

Example

if (dataLayer.empty('user.id')) {
  console.log('empty');
}

push <T>(path: string, value: T): T

Pushes a value into an array in the DigitalData object. If an array does not exist yet at the given path, or the object/property at the given path is not an array, an array will be created.

Parameters

Example

dataLayer.push('dot.notated.path.to.array', 'value-to-push-into-array');

change (path: string, onlyInvokeOnChanges: boolean, handler: () => void, id: string): { unlisten: () => void }

Adds a "change" listener to the dataLayer. Change listeners are being invoked whenever there is a change in the dataLayer where the path that the listener is interested in is involved. The handler is also invoked when the listener is registered and there is already data in the dataLayer for the path it wants to listen to. The path is dot notated and can use two types of wildcards. * and **.

Wildcard listeners using as the wildcard are invoked whenever there is a change on the same node-level as the node that was changed. For instance, a listener on user. would be invoked whenever a dataLayer variable would change. It will not be changed for changes in for instance user.address.zipcode. Wildcard listeners using as the wildcard are invoked whenever there is a change on the same node-level as the node that was changed, as well as deeper node levels. For instance, in the previous situation of user.address.zipcode, listeners for user. will also be invoked.

Parameters

Example

// Add a change listener on only the user.products key in the dataLayer
dataLayer.change('user.products', true, (data: any) => console.log(data), 'unique - key - string');

// Add a change listener on user.products and any of it's direct children.
dataLayer.change('user.products.*', true, (data: any) => console.log(data), 'unique - key - string');

// Add a change listener on user.products and any of it's children or grandchildren.
dataLayer.change('user.products.**', false, () => console.log('yaay'), 'unique - key - string');

// Add a change listener on user.id, but do not invoke the handler function if the dataLayer already holds a value for user.id. Only invoke the handler when the property user.id changes.
const changeListener = dataLayer.change('user.id', true, (data: any) => console.log('yaay'), 'unique - key - string');

// remove change listener
changeListener.unlisten();

erase (path: string): void

Erases an object from the dataLayer at the provided path. Consequently also unpersists possibly persisted objects at the provided path and any path underneath the provided path.

Parameters

Example

dataLayer.erase('dot.notated.path.to.object.that.must.be.erased');

trigger (path: string, payload?: object): void

This method can be called to trigger an event. It will look up listeners for the provided name (dot notated, wild cards apply) and invoke all listeners that were interested in the event. The listeners will recieve an event object, which consists of the provided payload.

Parameters

Examples

dataLayer.trigger('name-of-event');

Trigger an event and provide some event data. Handlers of listeners to this event retrieve the data.

dataLayer.trigger('name-of-event', {
  data: {
    key: 'value',
  },
});

Trigger an event and provide data that needs to be put in DDM Core. Note that the dd key is a wildcard.

dataLayer.trigger("name-of-event", {
     "dd": {
          "key", "value"
     }
});

listen (name: string[]|string, invokeHandlerOnHistoricalEvents: boolean, handler: () => void, id: string): void

Adds a event listener. These listeners are being called when the trigger() method is being called and the name of the listener matches the name that was provided to the trigger. This can be used as a general event mechanism. The name is in fact a dot notated path and the same wildcards as for change listeners apply.

By default, the handler function will be called for historical events as well.

It is possible to provide multiple eventnames as an array. All the events in the array must have been triggered before the handler is being called.

Parameters

Binding scopes

Binding scopes to the listen method is possible. The binded scope becomes available within the scope of the listener.

dataLayer.listen('bind.function', false, incrementVal.bind(this));

dataLayer.trigger(name);

However when unlistening to the event, some additional configuration has to be made.

const bindedHandler = () => console.log(`I'm binded.`);

// Note the id is NOT set: and thus the key is either .toString or name.
dataLayer.listen('boundFunction', false, bindedHandler.bind(this));

// Note the id is NOT set: and thus the key is either .toString or name.
dataLayer.unlisten('boundFunction', bindedHandler.bind(this));

dataLayer.trigger('boundFunction'); // nothing happens --> valid unlistening

const secondBindedHandler = () => console.log(`I'm binded: 2.`);

// Note the id is set: and thus also used as key
dataLayer.listen('boundFunction', false, bindedHandler.bind(this), id);

// Note the id is set: and thus also used as key
dataLayer.unlisten('boundFunction', secondBindedHandler.bind(this), id);

dataLayer.trigger('boundFunction'); // nothing happens --> valid unlistening

Examples

By default, the handler function will be called for historical events as well. You can disable it by passing a boolean.

dataLayer.listen('dd.loaded', false, (e: any) => console.log(e), 'descriptive name of this listener');

It is possible to provide multiple eventnames as an array. All the events in the array must have been triggered each time before the handler is being called once.

listen(['trigger.one', 'trigger.two'], false, (e: any) => console.log(e), 'descriptive name of this listener');

unlisten (path: string, handler?: (e?: object) => void, id?: string): void

Removes an named listener for a given name. This can not be used for listeners that have been registered using dataLayer.listen() with an anonymous function declaration. A reference to the function is required. See examples.

Parameters

Examples

// Create a non-anonymous handler function (Only non-anonymous functions can be unregistered using dataLayer.unlisten)
let myHandler = (e: data) => console.log(e);

// Register the handler function as a listener to events with the name "myEvent"
dataLayer.listen('myEvent', myHandler);

// Unregister the handler to stop listening for events with the name "myEvent"
dataLayer.unlisten('myEvent', myHandler);

isTriggered (eventName: string, arr?: Array<any> = dataLayer.events): boolean

This function determines if an event with a given name has been triggered before. Returns true if it was, false otherwise.

Parameters

Example

if (dataLayer.isTriggered('ddm.loaded')) {
  console.log('ddm.loaded fired');
}

setCookie (name: string, value: string, days?: number, path?: string, domain?: string): void

Sets a cookie with the given name and value. If a value is specified for days an expiry valye will be set for the cookie. The path of the cookie is defaulted to "/".

Parameters

Example

dataLayer.setCookie('randomCookie', 1, 100);

getCookie (cookieName: string): string

Gets a cookie with a given name.

Parameters

Example

const val = dataLayer.getCookie('randomCookie');

removeCookie (name: string, path?: string): void

Delete a cookie valid to the path of the current page.

Parameters

Example

dataLayer.removeCookie('randomCookie');

persist (path: string, ttl?: number): void

Registers a dot-notated path of DDM Core's datalayer as persistent. A TTL can be provided in minutes how long the value should be persisted. Defaults to 30 minutes. This method is also called during the initialization of DDM to register the default paths that are to be persisted.

Parameters

Examples

dataLayer.persist('user', 60);

unpersist (path: string): void

Unpersists a given path and removes all change listeners.

Parameters

Examples

dataLayer.unpersist('user');

getUrlParam (param: string): string

Returns the value of a parameter in the HTTP URL string of the current URL.

Parameters

Examples

const param = dataLayer.getUrlParam('user');

getRefParam (param: string): string

Returns the value of a parameter in the HTTP Referer URL string.

Parameters

Examples

const param = dataLayer.getRefParam('user');

isObject (obj: any): boolean

Checks whether a given object is in fact an Object.

Parameters

Examples

if (dataLayer.isObject({})) {
}

isArray (arr: any): boolean

Checks whether a given object is in fact an Array.

Parameters

Examples

if (dataLayer.isArray({})) {
}

isInteger (int: any): boolean

Checks whether a given object is an Integer.

Parameters

Examples

if (dataLayer.isInteger({})) {
}

isString (str: any): boolean

Checks whether a given object is an string.

Parameters

Examples

if (dataLayer.isString({})) {
}

cloneObject (obj: object): object

Method to clone an object using JSON (de)serialization.

Parameters

Examples

const newObj = dataLayer.cloneObject({});

mergeObjects (destination: object, source: object): object

Deep merge a source object into a destination object, modifying the destination object.

Parameters

Examples

const newObj = dataLayer.mergeObjects(
  {
    data: {
      a: 1,
    },
  },
  {
    data: {
      b: 1,
    },
  },
);