#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)