tdp-event-manager-polymer

Version

Master: V2.0.3

Semver

This project aims to maintain the semver version numbering scheme.

Changelog

See changelog file

Overview

A very simple javascript event manager/emitter library, wrapped as a polymer web component. tdp-event-manager-polymer is intended to be used to provide public/consumable event hooks to facilitate inter-web component communucation.

tdp-event-manager-polymer runs as a "global" in that there is one running instance of the event manager and each tdp-event-manager-polymer HTML element simply exposes an API interface to that global instance. This means that you can insert as many tdp-event-manager-polymer HTML elements as you wish and each can access (register, remove, trigger, list) the all of the events.

Features

• Zero javascript dependencies (does not require e.g. jquery)
• Packaged as a bower component and an NPM package for ease of use
• Automatically and pretty thoroughly tested (though not (yet) multi-browser - via phantom-mocha)

Requirements

• Production requirements
  • None!
• Development/test requirements
  • mocha
  • should
  • phantomjs
  • mocha-phantomjs
  • coveralls
  • mocha-lcov-reporter
  • istanbul

Installation

You can install either via npm:

npm install tdp-event-manager-polymer --save

(note: with npm, you'll need to manually/independently install polymer)

or via bower:

bower install tdp-event-manager-polymer --save

(note that in both cases --save will add tdp-event-manager-polymer to your npm package.json or bower bower.json config file).

Usage

tdp-event-manager-polymer provides a polymer/web components custom element called tdp-event-manager which you can include in the normal polymer fashion:

In your my-custom-elememt polymer web component HTML file

 
<!-- Import Polymer -->
<link rel="import" href="/bower_components/polymer/polymer.html">
 
<!-- Import tdp-event-manager -->
<link rel="import" href="/bower_components/tdp-event-manager-polymer/elements/tdp-event-manager-polymer/tdp-event-manager-polymer.html">
 
<polymer-element name="my-custom-element">
    <template>
 
        <!-- Instantiate a tdp-event-manager element in this template  -->
        <!-- Note 1: The tdp-event-manager instance is referred to via this.$.eventManage -->
        <tdp-event-manager id="eventManager"></tdp-event-manager>    
        <!-- ...more template content...-->   
    </template>
 
    <script>
        Polymer(
        {
            ready:function()
            {
                // Register a new event called "someEvent"
                this.$.eventManager.api.registerEvent("someEvent", function(success)
                {
                    // List the events which have been registered - this should be a single item, "someEvent", which we added above
                    this.$.eventManager.api.listEvents(function(eventList)
                    {
                        console.log("Event list:");
                        console.dir(eventList);
                    }.bind(this));
                }.bind(this));
            }
        });
  </script> 
 
</polymer-element>

Public API functions

registerEvent(eventName, callback)

Overview

Registers a new event with the instance.

Arguments

eventName (String, mandatory)

A name by which the event is refered (e.g. when it is triggered, removed or when a new eventCallback is registered to it).

callback (Function, mandatory)

A callback function which will be executed once the event has been registered or when a failure in registration of the event occurs. A hard error will be thrown if callback is missing or is not of type function.

Returns

returnValue (Boolean || null)

true: event was registered successfully. false: event was not registered because an event with the same name is already registered. null: an error occurred registering the event (usually because arguments are incorrectly specified), the event was not registered.

registerEventCallback(eventName, eventCallbackName, eventCallbackFunction, callback)

Overview

Registers a callback (a function which is executed upon the relevant event being triggered) on an existing event.

Arguments

eventName (String, mandatory)

A name by which the event is refered (e.g. when it is triggered, removed or when a new eventCallback is registered to it).

eventCallbackName (String, mandatory)

A name by which the eventCallback is refered (e.g. when it is triggered or removed).

eventCallbackFunction (Function, mandatory)

A callback function which will be executed when the event is triggered. eventCallbackFunctions can optionally receive arguments which are passed to the triggerEvent function.

callback (Function, mandatory)

A callback function which will be executed once the eventCallback has been registered or when a failure in registration of the eventCallback occurs. A hard error will be thrown if callback is missing or is not of type function.

Returns

returnValue (Boolean || null)

true: eventCallback was registered successfully. false: an error occurred registering the eventCallback because the specified eventName does not exist. null: an error occurred registering the eventCallback (usually because arguments are incorrectly specified), the eventCallback was not registered.

triggerEvent(eventName, callbackArguments, callback)

Overview

Triggers the specified eventName which executes all registered eventCallbacks registered to/on that eventName.

Arguments

eventName (String, mandatory)

The eventName whose eventCallbacks will be executed.

callbackArguments (Mixed, mandatory)

An argument String, Array, Object, Boolean etc. to pass to each registered eventCallback which is executed. If not required, this should be set to null.

callback (Function, mandatory)

A callback function which will be executed once the event has been triggered or when a failure in triggering the event occurs. A hard error will be thrown if callback is missing or is not of type function.

Returns

returnValue (Boolean || null)

true: event was triggered successfully. false: an error occurred in attempting to trigger the event because eventName is not a registered event. null: an error occurred in attempting to trigger the specified eventName (usually because arguments are incorrectly specified), the event was not triggered.

removeEvent(eventName, callback)

Overview

Remove a previously registered event, eventName and all registered eventCallbacks for that event.

Arguments

eventName (String, mandatory)

The eventName which we want to remove.

callback (Function, mandatory)

A callback function which will be executed once the event has been removed or when a failure in triggering the event occurs. A hard error will be thrown if callback is missing or is not of type function.

Returns

returnValue (Boolean || null)

true: eventCallback was removed successfully. false: an error occurred in attempting to remove the eventCallback because eventName is not a registered event. null: an error occurred in attempting to remove the specified eventCallback (usually because arguments are incorrectly specified), the eventCallback was not removed.

removeEventCallback(eventName, eventCallbackName, callback)

Overview

Remove a previously registered eventCallback from the specified eventName.

Arguments

eventName (String, mandatory)

The eventName whose eventCallback we want to remove.

eventCallbackName (String, mandatory)

The eventCallback which is to be removed from eventName.

callback (Function, mandatory)

A callback function which will be executed once the eventCallback has been removed or when a failure in removing the eventCallback occurs. A hard error will be thrown if callback is missing or is not of type function.

Returns

returnValue (Boolean || null)

true: eventCallback was removed successfully. false: an error occurred in attempting to remove the eventCallback because eventName is not a registered event or eventCallback is not registered. null: an error occurred in attempting to remove the specified eventCallback (usually because arguments are incorrectly specified), the eventCallback was not removed.

listEvents(callback)

Overview

Lists all registered events.

Arguments

callback (Function, mandatory)

A callback function which will be executed once the list of events has been retrieved. A hard error will be thrown if callback is missing or is not of type function.

Returns

eventList (Array)

An array of registered eventNames, or an empty array if no events have yet been registered.

eventIsRegistered(eventName, callback)

Overview

Check if the specified eventName has previously been registered.

Arguments

eventName (String, mandatory)

The eventName to check for.

callback (Function, mandatory)

A callback function which will be executed once the list of events has been checked. A hard error will be thrown if callback is missing or is not of type function.

Returns

eventIsRegistered (Boolean || null)

true: eventName has previously been registered. false: eventName has not previously been registered. null: arguments incorrectly specified (e.g. wrong format)

listEventCallbacks(eventName, callback)

Overview

Lists all registered callbacks for the specified eventName.

Arguments

eventName (String, mandatory)

The eventName whose eventCallbacks in which to check.

callback (Function, mandatory)

A callback function which will be executed once the list of events has been retrieved. A hard error will be thrown if callback is missing or is not of type function.

Returns

eventCallbackList (Array)

An array of registered eventCallbacks, or an empty array if no eventCallbacks have yet been registered for the specified eventName.

eventCallbackIsRegistered(eventName, eventCallbackName, callback)

Overview

Check if the specified eventName has previously been registered.

Arguments

eventName (String, mandatory)

The eventName to check for.

eventCallbackName (String, mandatory)

The eventCallback to check for.

callback (Function, mandatory)

A callback function which will be executed once the list of events has been checked. A hard error will be thrown if callback is missing or is not of type function.

Returns

eventIsRegistered (Boolean || null)

true: eventCallbackName has previously been registered on eventName. false: eventCallbackName has not previously been registered on eventName. null: arguments incorrectly specified (e.g. wrong format)