From e56ff68a61ea5e5b025d9d1140f2348505cb0a48 Mon Sep 17 00:00:00 2001
From: Nathan Gray <nathangray.bsc@gmail.com>
Date: Wed, 2 Dec 2015 18:42:55 +0000
Subject: [PATCH] - Make sure we always use index's nextmatch - Add some
 documentation about the this.et2 variable

---
 infolog/js/app.js             |  7 ++++---
 phpgwapi/js/jsapi/app_base.js | 30 +++++++++++++++++++++++++++++-
 2 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/infolog/js/app.js b/infolog/js/app.js
index 4680200d9b..3e6b3c820c 100644
--- a/infolog/js/app.js
+++ b/infolog/js/app.js
@@ -153,9 +153,10 @@ app.classes.infolog = AppJS.extend(
 		// call parent
 		var state = this._super.apply(this, arguments);
 		var nm = {};
-		// Prevents to get access to freed et2 object
-		// TODO: needs more investigation to see why this.et2 sometimes gets free
-		if(this.et2 && Object.keys(this.et2).length >1)
+
+		// Get index etemplate
+		var et2 = etemplate2.getById('infolog-index');
+		if(et2)
 		{
 			var content = this.et2.getArrayMgr('content');
 			nm = content? content.data.nm: {};
diff --git a/phpgwapi/js/jsapi/app_base.js b/phpgwapi/js/jsapi/app_base.js
index 7ee4f06d74..3127e5adb6 100644
--- a/phpgwapi/js/jsapi/app_base.js
+++ b/phpgwapi/js/jsapi/app_base.js
@@ -73,7 +73,35 @@ var AppJS = Class.extend(
 	appname: '',
 
 	/**
-	 * Internal reference to etemplate2 widget tree
+	 * Internal reference to the most recently loaded etemplate2 widget tree
+	 *
+	 * NOTE: This variable can change which etemplate it points to as the user
+	 * works.  For example, loading the home or admin apps can cause
+	 * et2_ready() to be called again with a different template.  this.et2 will
+	 * then point to a different template.  If the user then closes that tab,
+	 * this.et2 will point to a destroyed object, and trying to use it will fail.
+	 *
+	 * If you need a reference to a certain template you can either store a local
+	 * reference or access it through etemplate2.
+	 * 
+	 * @example <caption>Store a local reference</caption>
+	 *	// in et2_ready()
+	 *	if(name == 'index') this.index_et2 = et2.widgetContainer;
+	 *
+	 *	// Remember to clean up in destroy()
+	 *	delete this.index_et2;
+	 *
+	 *	// Instead of this.et2, using a local reference
+	 *	this.index_et2 ...
+	 *
+	 *
+	 * @example <caption>Access via etemplate2 object</caption>
+	 * // Instead of this.et2, using it's unique ID
+	 * var et2 = etemplate2.getById('myapp-index)
+	 * if(et2)
+	 * {
+	 *		et2.widgetContainer. ...
+	 * }
 	 *
 	 * @var {et2_container}
 	 */