Cut a basic js documentation

js/documenation.md

+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### Table of Contents
+
+-   [ebiGaIndicateLoaded](#ebigaindicateloaded)
+-   [setTimeout](#settimeout)
+-   [last](#last)
+-   [lastGaEventTime](#lastgaeventtime)
+-   [analyticsTrackInteraction](#analyticstrackinteraction)
+-   [Analytics tracking](#analytics-tracking)
+-   [ebiGaInit](#ebigainit)
+-   [Note](#note)
+-   [addBlankTargetToExternalLinkEBI](#addblanktargettoexternallinkebi)
+-   [addExternalToBlankWindowLinksEBI](#addexternaltoblankwindowlinksebi)
+-   [activateEMBLdropdown](#activateembldropdown)
+-   [Activate EMBL dropdown menu](#activate-embl-dropdown-menu)
+-   [smoothScrollAnchorLinksEBI](#smoothscrollanchorlinksebi)
+-   [invokeResponsiveMenuEBI](#invokeresponsivemenuebi)
+-   [jQuery](#jquery)
+-   [bodyData](#bodydata)
+-   [Allow invokation of Foundation and foundationExtendEBI with data attributes](#allow-invokation-of-foundation-and-foundationextendebi-with-data-attributes)
+-   [foundationInvoke](#foundationinvoke)
+-   [foundationExtendEBI](#foundationextendebi)
+-   [addExternal](#addexternal)
+
+## ebiGaIndicateLoaded
+
+[js/foundationExtendEBI.js:12-34](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L12-L34 "Source code on GitHub")
+
+We poll the document until we find GA has loaded, or we've tried a few times.
+
+**Parameters**
+
+-   `numberOfEbiGaChecks` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**  (optional, default `counter`)
+-   `numberOfEbiGaChecksLimit` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**  (optional, default `2`)
+
+## setTimeout
+
+[js/foundationExtendEBI.js:19-26](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L19-L26 "Source code on GitHub")
+
+If successful we append `.google-analytics-loaded` to the `body` tag.
+
+## last
+
+[js/foundationExtendEBI.js:42-46](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L42-L46 "Source code on GitHub")
+
+Utility method to get the last in an array
+
+**Examples**
+
+```javascript
+linkName = jQuery(actedOnItem).attr('src').split('/').last();
+```
+
+Returns **var** the last item in the array
+
+## lastGaEventTime
+
+[js/foundationExtendEBI.js:52-52](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L52-L52 "Source code on GitHub")
+
+Track the last time an event was sent (don't double send)
+
+**Parameters**
+
+-   `lastGaEventTime` **[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)** 
+
+## analyticsTrackInteraction
+
+[js/foundationExtendEBI.js:71-102](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L71-L102 "Source code on GitHub")
+
+## Analytics tracking
+
+This code tracks the user's clicks in various parts of the EBI site and logs them as GA events.<br/>
+Links in non-generic regions can be tracked by adding '.track-with-analytics-events' to a parent div. Careful with the scoping.
+
+Dev note:
+add class verbose-analytics to your body for a readout to console on clicks, a la: <br/>
+`jQuery('body').addClass('verbose-analytics');`
+
+**Parameters**
+
+-   `actedOnItem` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)** 
+-   `parentContainer` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `Eventgroup`)
+-   `customEventName` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `Eventaction`)
+
+**Examples**
+
+```javascript
+jQuery("body.google-analytics-loaded .analytics-content-footer").on('mousedown', 'a, button', function(e) {
+  analyticsTrackInteraction(e.target,'Content footer');
+});
+```
+
+## ebiGaInit
+
+[js/foundationExtendEBI.js:111-194](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L111-L194 "Source code on GitHub")
+
+If GA is found, we initialise the tracking of various default areas
+
+## Note
+
+This could be done more efficently with a general capture of links,
+but we're running against the page's unload -- so speed over elegance.
+
+## addBlankTargetToExternalLinkEBI
+
+[js/foundationExtendEBI.js:200-207](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L200-L207 "Source code on GitHub")
+
+Programatically open external links in new tabs
+
+**Parameters**
+
+-   `parent` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)**  (optional, default `scope`)
+
+## addExternalToBlankWindowLinksEBI
+
+[js/foundationExtendEBI.js:213-218](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L213-L218 "Source code on GitHub")
+
+Programatically add '.external' to external links
+
+**Parameters**
+
+-   `parent` **[element](https://developer.mozilla.org/en-US/docs/Web/API/Element)**  (optional, default `scope`)
+
+## activateEMBLdropdown
+
+[js/foundationExtendEBI.js:231-260](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L231-L260 "Source code on GitHub")
+
+## Activate EMBL dropdown menu
+
+Note: the menu content has already been added in `script.js` <br/>
+If you pass options as 'reInit', it will destory any existing menu and add a new one.
+
+**Parameters**
+
+-   `options` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `reInit`)
+
+## smoothScrollAnchorLinksEBI
+
+[js/foundationExtendEBI.js:265-288](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L265-L288 "Source code on GitHub")
+
+Smooth scroll anchor links for jQuery users
+
+## invokeResponsiveMenuEBI
+
+[js/foundationExtendEBI.js:293-401](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L293-L401 "Source code on GitHub")
+
+Make the local nav menu responsive to the browser window width
+
+## jQuery
+
+[js/foundationExtendEBI.js:406-496](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L406-L496 "Source code on GitHub")
+
+Default invokation of foundationExtendEBI
+
+## bodyData
+
+[js/foundationExtendEBI.js:468-468](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L468-L468 "Source code on GitHub")
+
+## Allow invokation of Foundation and foundationExtendEBI with data attributes
+
+This saves the need of placing the below on your page:<br/>
+`<script type="text/JavaScript">$(document).foundation();</script>`<br/>
+`<script type="text/JavaScript">$(document).foundationExtendEBI();</script>`<br/>
+Background: <https://github.com/ebiwd/EBI-Framework/issues/77>
+
+## foundationInvoke
+
+[js/foundationExtendEBI.js:473-477](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L473-L477 "Source code on GitHub")
+
+**Examples**
+
+```javascript
+<body data-foundationInvoke="document>
+```
+
+## foundationExtendEBI
+
+[js/foundationExtendEBI.js:482-486](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L482-L486 "Source code on GitHub")
+
+**Examples**
+
+```javascript
+<body data-foundationExtendEBI="document">
+```
+
+## addExternal
+
+[js/foundationExtendEBI.js:491-494](https://github.com/ebiwd/EBI-Framework/blob/fbedcb2aff06266d91cbfa8ea482fe58f7bc79a2/js/foundationExtendEBI.js#L491-L494 "Source code on GitHub")
+
+**Examples**
+
+```javascript
+<body data-addExternal="true">
+```

js/foundationExtendEBI.js

-/* Copyright (c) EMBL-EBI 2017
-   Authors:
-   Ken Hawkins (khawkins@ebi.ac.uk)
-*/
-
-// Analytics tracking
-// This code tracks the user's clicks in various parts of the EBI site and logs them as GA events.
-// Links in non-generic regions can be tracked by adding '.track-with-analytics-events' to a parent div. Careful with the scoping.
-//
-// Dev note:
-// add class verbose-analytics to your body for a readout to console on clicks, ala:
-// jQuery('body').addClass('verbose-analytics');
-// -------------
-var numberOfEbiGaChecks = 0;
-var numberOfEbiGaChecksLimit = 2;
-var lastGaEventTime = Date.now(); // track the last time an event was send (don't double send)
-function ebiGaCheck() {
-  numberOfEbiGaChecks++;
-  try {
-    if (ga && ga.loaded) {
-      jQuery('body').addClass('google-analytics-loaded'); // Confirm GA is loaded, add a class if found
-      ebiGaInit();
-    } else {
+// Copyright (c) EMBL-EBI 2017
+// Authors:
+// - Ken Hawkins (khawkins@ebi.ac.uk)
+// Documentation generated with: https://github.com/documentationjs/documentation#documentation
+
+
+/**
+ * We poll the document until we find GA has loaded, or we've tried a few times.
+ * @param {number} [numberOfEbiGaChecks=counter]
+ * @param {number} [numberOfEbiGaChecksLimit=2]
+ */
+function ebiGaIndicateLoaded(numberOfEbiGaChecks, numberOfEbiGaChecksLimit) {
+  function ebiGaCheck() {
+    numberOfEbiGaChecks++;
+    try {
+      /**
+       * If successful we append `.google-analytics-loaded` to the `body` tag.
+       */
+      if (ga && ga.loaded) {
+        jQuery('body').addClass('google-analytics-loaded'); // Confirm GA is loaded, add a class if found
+        ebiGaInit();
+      } else {
+        if (numberOfEbiGaChecks <= numberOfEbiGaChecksLimit) {
+          setTimeout(ebiGaCheck, 900); // give a second check if GA was slow to load
+        }
+      }
+    } catch (err) {
       if (numberOfEbiGaChecks <= numberOfEbiGaChecksLimit) {
         setTimeout(ebiGaCheck, 900); // give a second check if GA was slow to load
       }
     }
-  } catch (err) {
-    if (numberOfEbiGaChecks <= numberOfEbiGaChecksLimit) {
-      setTimeout(ebiGaCheck, 900); // give a second check if GA was slow to load
-    }
   }
+  ebiGaCheck(); // invoke analytics check
 }
-ebiGaCheck(); // invoke analytics check
+ebiGaIndicateLoaded(0,2);
 
-// Utility method
+/**
+ * Utility method to get the last in an array
+ * @returns {var} the last item in the array
+ * @example linkName = jQuery(actedOnItem).attr('src').split('/').last();
+ */
 if (!Array.prototype.last){
   Array.prototype.last = function(){
     return this[this.length - 1];
   };
 };
 
+/**
+ * Track the last time an event was sent (don't double send)
+ * @param {Date} lastGaEventTime
+ */
+var lastGaEventTime = Date.now();
+
+/**
+ * Analytics tracking
+ * ---
+ * This code tracks the user's clicks in various parts of the EBI site and logs them as GA events.<br/>
+ * Links in non-generic regions can be tracked by adding '.track-with-analytics-events' to a parent div. Careful with the scoping.
+ *
+ * Dev note:
+ * add class verbose-analytics to your body for a readout to console on clicks, a la: <br/>
+ * `jQuery('body').addClass('verbose-analytics');`
+ * @param {element} actedOnItem
+ * @param {string} [parentContainer=Event group]
+ * @param {string} [customEventName=Event action]
+ * @example
+ * jQuery("body.google-analytics-loaded .analytics-content-footer").on('mousedown', 'a, button', function(e) {
+ *   analyticsTrackInteraction(e.target,'Content footer');
+ * });
+ */
 function analyticsTrackInteraction(actedOnItem, parentContainer, customEventName) {
   var customEventName = customEventName || []; // you can pass some custom text as a 3rd param
 
@@ -58,7 +86,7 @@ function analyticsTrackInteraction(actedOnItem, parentContainer, customEventName
   }
 
   // send to GA
-  // Only if more than 100ms has past since last click.
+  // Only if more than 100ms has past since last click.<br/>
   // Due to our structure, we fire multiple events, so we only send to GA the most specific event resolution
   if ((Date.now() - lastGaEventTime) > 150) {
     ga && ga('send', 'event', 'UI', 'UI Element / ' + parentContainer, linkName);
@@ -73,28 +101,14 @@ function analyticsTrackInteraction(actedOnItem, parentContainer, customEventName
   }
 } // END analyticsTrackInteraction
 
-// Programatically open external links in new tabs, and add '.external'
-function addBlankTargetToExternalLinkEBI(parent) {
-  (function($) {
-    var parent = parent || '#content';
-    $(parent + ' a').filter(function() {
-       return this.hostname && this.hostname !== location.hostname;
-    }).attr('target','_blank');
-  }(jQuery));
-}
-function addExternalToBlankWindowLinksEBI(parent) {
-  (function($) {
-    var parent = parent || '#content';
-    $(parent + ' a[target="_blank"]').addClass('external');
-  }(jQuery));
-}
-
-// initialise the tracking of various areas
+/**
+ * If GA is found, we initialise the tracking of various default areas
+ * Note
+ * ----
+ * This could be done more efficently with a general capture of links,
+ * but we're running against the page's unload -- so speed over elegance.
+ */
 function ebiGaInit() {
-  // Only track these areas
-  // This could be done more efficently with a general capture of links,
-  // but we're running against the page's unload -- so speed over elegance.
-
   // Order these by specificity -- only the first invoked will be sent to GA
   jQuery("body.google-analytics-loaded .track-with-analytics-events a").on('mousedown', function(e) {
     analyticsTrackInteraction(e.target,'Manually tracked area');
@@ -179,13 +193,41 @@ function ebiGaInit() {
   }
 } // END ebiGaInit
 
+/**
+ * Programatically open external links in new tabs
+ * @param {element} [parent=scope]
+ */
+function addBlankTargetToExternalLinkEBI(parent) {
+  (function($) {
+    var parent = parent || '#content';
+    $(parent + ' a').filter(function() {
+       return this.hostname && this.hostname !== location.hostname;
+    }).attr('target','_blank');
+  }(jQuery));
+}
+
+/**
+ * Programatically add '.external' to external links
+ * @param {element} [parent=scope]
+ */
+function addExternalToBlankWindowLinksEBI(parent) {
+  (function($) {
+    var parent = parent || '#content';
+    $(parent + ' a[target="_blank"]').addClass('external');
+  }(jQuery));
+}
+
+
 // Foundation specific extensions of functionality
 // -------------
 
-// Activate EMBL dropdown menu
-// -------------
-// Note: the menu content has already been added in script.js
-// if you pass options as 'reInit', it will destory any existing menu and add a new one
+/**
+ * Activate EMBL dropdown menu
+ * ---
+ * Note: the menu content has already been added in `script.js` <br/>
+ * If you pass options as 'reInit', it will destory any existing menu and add a new one.
+ * @param {string} [options=reInit]
+ */
 function activateEMBLdropdown(options) {
   (function($) {
     var options = options || '',
@@ -217,8 +259,9 @@ function activateEMBLdropdown(options) {
   }(jQuery));
 } // END activateEMBLdropdown
 
-// Smooth scroll anchor links for jQuery users
-// -------------
+/**
+ * Smooth scroll anchor links for jQuery users
+ */
 function smoothScrollAnchorLinksEBI() {
   (function($) {
     $('a[href*=\\#]:not([href=\\#])').on('click', function() {
@@ -244,8 +287,9 @@ function smoothScrollAnchorLinksEBI() {
   }(jQuery));
 } // END smoothScrollAnchorLinksEBI
 
-// Respond the local nav to browser window width
-// -----------
+/**
+ * Make the local nav menu responsive to the browser window width
+ */
 function invokeResponsiveMenuEBI() {
   (function($) {
     // Create a dynamic height for the menu bar when stuck
@@ -356,7 +400,9 @@ function invokeResponsiveMenuEBI() {
   }(jQuery));
 } // END invokeResponsiveMenuEBI
 
-// Default invokation of foundationExtendEBI
+/**
+ * Default invokation of foundationExtendEBI
+ */
 (function($) {
   // Clearable text inputs
   // via: http://stackoverflow.com/questions/6258521/clear-icon-inside-input-text
@@ -411,27 +457,37 @@ function invokeResponsiveMenuEBI() {
 
   }
 
-  /* Allow invokation of of foundation and foundationExtendEBI with data attributes
-
-    <body data-foundationInvoke="document" data-foundationExtendEBI="document">
-
-    This saves the need of placing the below on your page:
-    <script type="text/JavaScript">$(document).foundation();</script>
-    <script type="text/JavaScript">$(document).foundationExtendEBI();</script>
-
-    Background: https://github.com/ebiwd/EBI-Framework/issues/77
-  */
+  /**
+   * Allow invokation of Foundation and foundationExtendEBI with data attributes
+   * ---
+   * This saves the need of placing the below on your page:<br/>
+   * `<script type="text/JavaScript">$(document).foundation();</script>`<br/>
+   * `<script type="text/JavaScript">$(document).foundationExtendEBI();</script>`<br/>
+   * Background: https://github.com/ebiwd/EBI-Framework/issues/77
+   */
   var bodyData = $('body').data();
+  /**
+   * @example
+   * <body data-foundationInvoke="document>
+   */
   if (bodyData.foundationInvoke) {
     bodyData.foundationInvoke = bodyData.foundationInvoke || 'document';
     if (bodyData.foundationInvoke === 'true') bodyData.foundationInvoke = 'document';
     $(bodyData.foundationInvoke).foundation();
   }
+  /**
+   * @example
+   * <body data-foundationExtendEBI="document">
+   */
   if (bodyData.foundationExtendEBI) {
     bodyData.foundationExtendEBI = bodyData.foundationExtendEBI || 'document';
     if (bodyData.foundationExtendEBI === 'true') bodyData.foundationExtendEBI = 'document';
     $(bodyData.foundationExtendEBI).foundationExtendEBI();
   }
+  /**
+   * @example
+   * <body data-addExternal="true">
+   */
   if (bodyData.addExternal) {
     addBlankTargetToExternalLinkEBI();
     addExternalToBlankWindowLinksEBI();