Documentation

diff --git a/src/META-INF/resources/pz2utils/listeners.js b/src/META-INF/resources/pz2utils/listeners.js
index 80e1bc5..84cd19b 100644 (file)
--- a/src/META-INF/resources/pz2utils/listeners.js
+++ b/src/META-INF/resources/pz2utils/listeners.js
@@ -1,6 +1,8 @@
   var renderTargetsReqVar;\r
   var renderOnRecordTargetsReqVar;\r
-    \r
+  \r
+  // Renders UI elements listed in 'renderWhileActiveclients', optionally doing \r
+  // another update round-trip to Pazpar2 when done.\r
   function renderTargets(doRefresh)\r
   {\r
        //console.log('rendering ' + renderWhileActiveclients);\r
@@ -19,6 +21,8 @@
     }\r
   }\r
   \r
+  // Renders UI elements listed in 'renderWhileActiveclientsRecord', optionally doing \r
+  // another record request when done.\r
   function renderOnRecordTargets(doRefresh)\r
   {\r
        console.log('rendering ' + renderWhileActiveclientsRecord);\r
@@ -37,7 +41,8 @@
     }\r
   }\r
 \r
-\r
+  // Listens for browser initiated changes to 'window.location.hash' and sends the hash\r
+  // changes to the back-end (to have the back-end pull up a previous Pazpar2 state)\r
   function windowlocationhashListener () {\r
          if (trackHistory) {\r
              //console.log("browser hash update detected");\r
@@ -53,6 +58,8 @@
          }       \r
   }\r
   \r
+  // Listens for ViewExpiredException message. Reloads the current page, stripped of\r
+  // it's jsessionid and hash content\r
   function viewExpirationListener (data) {\r
          if (data.status === "success" && data.responseXML) {  \r
                  var errorElements = data.responseXML.getElementsByTagName("error-name");\r
@@ -60,14 +67,15 @@
                          var errorname = errorElements.item(0).textContent || errorElements.item(0).text;\r
                          if (errorname === "class javax.faces.application.ViewExpiredException") {\r
                                  var newloc = window.location.protocol + "//" + window.location.host + window.location.pathname.replace(/;jsessionid.*/,'');\r
-                                 alert('Sorry, but this session has expired, will load a new one for you.');\r
+                                 alert('Sorry, this session has expired. A new one will be loaded.');\r
                                  window.location.replace(newloc);\r
                          }                       \r
                  }\r
          }\r
-\r
+         \r
   }\r
 \r
+  // Composite listener, invoking all field update listeners\r
   function fieldUpdateListener (data) {\r
          if (data.status === "success") {\r
                var updates = data.responseXML.getElementsByTagName("update");\r
@@ -92,6 +100,8 @@
 \r
   var fieldListeners = new Pz2listeners();\r
 \r
+  // Listens for back-end initiated changes to the state key and updates\r
+  // window.location.hash with changes, to record them in browsing history\r
   var StateListener = function () {\r
        this.invoke = function (field) {\r
       var stateKeyDoc = StringtoXML(field.textContent || field.text);\r
@@ -103,10 +113,10 @@
       } else {\r
         //console.log("Browsers hash already has the value of the state hash. Not updating browser hash."); \r
       }\r
-\r
        };\r
   };\r
   \r
+  // Listens for updates to general 'activeclients' field, then invokes renderTargets\r
   var ActiveclientsListener = function () {\r
     this.invoke = function (field) {\r
       var updateDoc = StringtoXML(field.textContent || field.text);\r
@@ -121,6 +131,7 @@
        };\r
   };\r
   \r
+  // Listens for updates to record 'activeclients' field, then invokes renderOnRecordTargets\r
   var ActiveclientsRecordListener = function () {\r
            this.invoke = function (field) {\r
              var updateDoc = StringtoXML(field.textContent || field.text);\r
@@ -137,6 +148,8 @@
          };\r
 \r
     \r
+  // Inserts field update listeners, state listeners, view expired listener\r
+  // into Ajax response handling         \r
   jsf.ajax.addOnEvent(fieldUpdateListener);\r
   jsf.ajax.addOnEvent(viewExpirationListener);\r
   \r
@@ -153,6 +166,7 @@
            return doc;\r
   }\r
 \r
+  // Sets up field update listeners\r
   var setUpListeners = function () {\r
     //console.log("Starts tracking activeclientsField");\r
     fieldListeners.addListener("pz2watch:activeclientsField", new ActiveclientsListener());\r