From 1bbbe05a8607db41f35153c7420a7c7be48587b6 Mon Sep 17 00:00:00 2001
From: Stefan Breunig <stefan@mathphys.fsk.uni-heidelberg.de>
Date: Sun, 10 Feb 2013 23:07:33 +0100
Subject: [PATCH] add hooks framework and add hook for portal added (fixes #87)

---
 code/hooks.js     | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 code/map_data.js  |  2 ++
 plugins/README.md |  6 ++++++
 3 files changed, 55 insertions(+)
 create mode 100644 code/hooks.js

diff --git a/code/hooks.js b/code/hooks.js
new file mode 100644
index 00000000..f5b90d0b
--- /dev/null
+++ b/code/hooks.js
@@ -0,0 +1,47 @@
+// PLUGIN HOOKS ////////////////////////////////////////////////////////
+// Plugins may listen to any number of events by specifying the name of
+// the event to listen to and handing a function that should be exe-
+// cuted when an event occurs. Callbacks will receive additional data
+// the event created as their first parameter. The value is always a
+// hash that contains more details.
+//
+// For example, this line will listen for portals to be added and print
+// the data generated by the event to the console:
+// window.addHook('portalAdded', function(data) { console.log(data) });
+//
+// Boot hook: booting is handled differently because IITC may not yet
+//            be available. Have a look at the plugins in plugins/. All
+//            code before “// PLUGIN START” and after “// PLUGIN END” os
+//            required to successfully boot the plugin.
+//
+// Here’s more specific information about each event:
+// portalAdded: called when a portal has been received and is about to
+//              be added to its layer group. Note that this does NOT
+//              mean it is already visible or will be, shortly after.
+//              If a portal is added to a hidden layer it may never be
+//              shown at all. Injection point is in
+//              code/map_data.js#renderPortal near the end. Will hand
+//              the Leaflet CircleMarker for the portal in "portal" var.
+
+window._hooks = {}
+window.VALID_HOOKS = ['portalAdded'];
+
+window.runHooks = function(event, data) {
+  if(VALID_HOOKS.indexOf(event) === -1) throw('Unknown event type: ' + event);
+
+  if(!_hooks[event]) return;
+  $.each(_hooks[event], function(ind, callback) {
+    callback(data);
+  });
+}
+
+
+window.addHook = function(event, callback) {
+  if(VALID_HOOKS.indexOf(event) === -1) throw('Unknown event type: ' + event);
+  if(typeof callback !== 'function') throw('Callback must be a function.');
+
+  if(!_hooks[event])
+    _hooks[event] = [callback];
+  else
+    _hooks[event].push(callback);
+}
diff --git a/code/map_data.js b/code/map_data.js
index 32cf3cb8..3bc7a169 100644
--- a/code/map_data.js
+++ b/code/map_data.js
@@ -276,6 +276,8 @@ window.renderPortal = function(ent) {
 
   window.renderResonators(ent);
 
+  window.runHooks('portalAdded', {portal: p});
+
   // portalLevel contains a float, need to round down
   p.addTo(portalsLayers[parseInt(portalLevel)]);
 }
diff --git a/plugins/README.md b/plugins/README.md
index 1b872227..310077f6 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -20,3 +20,9 @@ Plugins may be developed in the same way as the total conversion script. Plugins
 You can use the guess player level script as an example to get you started. Just update the names and the part between `// PLUGIN START` and  `// PLUGIN END` and you should be able to develop your plugin. The other code ensures your plugin is executed after the main script.
 
 If you happen the write general purpose functions for your plugin, consider adding them to the main script instead. For example, if you write a `getResoCountFromPortal(details)` function it may be very well added to `code/portal_info.js`.
+
+
+Available Hooks
+---------------
+
+Available hooks are documented in the code. Please refer to the [boilerplate explanation in `hooks.js`](https://raw.github.com/breunigs/ingress-intel-total-conversion/gh-pages/code/hooks.js) to see which are available and how to listen for them. If you need additional hooks, open bug reports (preferably with patches attached).