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

parameter	type	description
`historyDD`	{ [index:string] : any }	History dataLayer variables that should be merged with new dataLayer.
`historyDDM`	{e : Array<any>; l: Array<any>; trigger(...args):void; listen(...args):void}	History dataLayer trigger and listeners that should be merged (and executed) with new dataLayer.

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

parameter	type	description
`path`	string	The dot notated path of the object/property that you want to store.
`value`	*	The value that you want to store.
`persist`	{boolean}	Whether to persist this key or not. Defaults to false.
`ttl`	integer	Number of minutes to persist the value. Defaults to 30 minutes.

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

parameter	type	description
`path`	string	The dot notated path of the object/property that you want to retrieve. Or no path if you want to retreive entire dataLayer.
`defaultValue`	*	An optional defaultValue that you want to use if no object/property is available at the provided path.
`createNonExisting`	{boolean}	Determines if the object/property should be added to DigitalData, using the defaultValue, if it does not exist.

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

parameter	type	description
`path`	string	The dot notated path of the object/property that you want to retrieve. Or no path if you want to retreive entire dataLayer.

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

parameter	type	description
`path`	string	The dot notated path of the object/property that you want to retrieve. Or no path if you want to retreive entire dataLayer.

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

parameter	type	description
`path`	string	The dot notated path of the object/property that you want to store.
`value`	*	The value that you want to store.

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

parameter	type	description
`path`	string	The dot notated path of the object/property that you want to listen to.
`onlyInvokeOnChanges`	boolean	Boolean to indicate that the handler should only be invoked when changes occur.
`handler`	function	TThe handler that has to be invoked.
`id`	string	Descriptive name.

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

parameter	type	description
`path`	string	The dot notated path of the object/property that you want to erase.

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

parameter	type	description
`eventName`	string	Name of the event (dot notated, wildcards apply).
`payload`	object	The payload of the event. Payload contains data or dd key. Defaults to an empty object.

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

parameter	type	description
`name`	string\|string[]	Name of event(s) to listen to (dot notated, wildcards apply).
`invokeHandlerOnHistoricalEvents`	boolean	Boolean that indicates if the handler should also be invoked for historical events. Default is true.
`handler`	function	The handler that has to be invoked.
`id`	string	The unique identifier given to this handler. This is used for error handling to aid in debugging.

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

parameter	type	description
`path`	string	Name of an event to remove the listener for (dot notated, wildcards apply).
`handler`	function	The handler that was to be invoked.
`id`	string	Unique key linked to a handler.

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

parameter	type	description
`eventName`	string	The name of the event
`arr`	{name: string}[]	An events array.

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

parameter	type	description
`name`	string	The name of the cookie to set.
`value`	string	The value of the cookie to set.
`days`	integer	The number of days until the cookie expires.
`path`	string	The path of the cookie. Defaults to "/"
`domain`	string	The domain of the cookie. Defaults to the base of the current domain, including subdomains (leading dot), eg: .example.com

Example

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

getCookie `(cookieName: string): string`

Gets a cookie with a given name.

Parameters

parameter	type	description
`name`	string	The name of the cookie.

Example

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

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

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

Parameters

parameter	type	description
`name`	string	The name of the cookie.
`path`	string	The path of the cookie.

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

parameter	type	description
`path`	string	Dot-notated path into DDM Core's datalayer.
`ttl`	number	Expiration in minutes. Default is 30.

Examples

dataLayer.persist('user', 60);

unpersist `(path: string): void`

Unpersists a given path and removes all change listeners.

Parameters

parameter	type	description
`path`	string	Dot-notated path into DDM Core's datalayer to unpersist.

Examples

dataLayer.unpersist('user');

getUrlParam `(param: string): string`

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

Parameters

parameter	type	description
`paramName`	string	The name of the parameter to search for.

Examples

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

getRefParam `(param: string): string`

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

Parameters

parameter	type	description
`paramName`	string	The name of the parameter to search for.

Examples

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

isObject `(obj: any): boolean`

Checks whether a given object is in fact an Object.

Parameters

parameter	type	description
`obj`	any	The object to test

Examples

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

isArray `(arr: any): boolean`

Checks whether a given object is in fact an Array.

Parameters

parameter	type	description
`arr`	any	The object to test

Examples

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

isInteger `(int: any): boolean`

Checks whether a given object is an Integer.

Parameters

parameter	type	description
`int`	any	The object to test

Examples

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

isString `(str: any): boolean`

Checks whether a given object is an string.

Parameters

parameter	type	description
`str`	any	The object to test

Examples

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

cloneObject `(obj: object): object`

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

Parameters

parameter	type	description
`obj`	object	The object to clone

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

parameter	type	description
`destination`	object	The destination object where to merge into.
`source`	object	The source object that needs to be merged into the destination object.

Examples

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

@d-cat/ddm-core

Dependents (1)

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads