Added o3djs.util.getElementsByTagAndId and

o3djs.util.getO3DContainerElements which 
encasplulates the way we were finding elements
to make O3D tags in.

I also put an example of how to make your own
failure callback in the docs.

This also brought up a known issue in the doc
generator so that fix is included here.

Review URL: http://codereview.chromium.org/173178

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@23976 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 127 insertions, 52 deletions

diff --git a/o3d/samples/o3djs/util.js b/o3d/samples/o3djs/util.js
index 6df3e93..7a956d4 100644
--- a/o3d/samples/o3djs/util.js
+++ b/o3d/samples/o3djs/util.js
@@ -63,6 +63,18 @@ o3djs.util.PLUGIN_NAME = 'O3D Plugin';
 o3djs.util.REQUIRED_VERSION = '0.1.40.0';
 
 /**
+ * The width an O3D must be to put a failure message inside
+ * @type {number}
+ */
+o3djs.util.MINIMUM_WIDTH_FOR_MESSAGE = 200;
+
+/**
+ * The height an O3D must be to put a failure message inside
+ * @type {number}
+ */
+o3djs.util.MINIMUM_HEIGHT_FOR_MESSAGE = 200;
+
+/**
  * A URL at which to download the client.
  * @type {string}
  */
@@ -326,6 +338,36 @@ o3djs.util.requiredVersionAvailable = function(requiredVersion) {
 };
 
 /**
+ * Gets all the elements of a certain tag that have a certain id.
+ * @param {string} tag The tag to look for. (eg. 'div').
+ * @param {string} id The id to look for. This can be a regular expression.
+ * @return {!Array.<!Element>} An array of the elements found.
+ */
+o3djs.util.getElementsByTagAndId = function(tag, id) {
+  var elements = [];
+  var allElements = document.getElementsByTagName(tag);
+  for (var ee = 0; ee < allElements.length; ++ee) {
+    var element = allElements[ee];
+    if (element.id && element.id.match(id)) {
+      elements.push(element);
+    }
+  }
+  return elements;
+};
+
+/**
+ * Gets all the Elements that contain or would contain O3D plugin objects.
+ * @param {string} opt_id The id to look for. This can be a regular
+ *     expression. The default is "^o3d".
+ * @param {string} opt_tag The type of tag to look for. The default is "div".
+ */
+o3djs.util.getO3DContainerElements = function(opt_id, opt_tag) {
+  var tag = opt_tag || 'div';
+  var id = opt_id || '^o3d';
+  return o3djs.util.getElementsByTagAndId(tag, id);
+}
+
+/**
  * Offers the user the option to download the plugin.
  *
  * Finds all divs with the id "^o3d" and inserts a message and link
@@ -337,10 +379,8 @@ o3djs.util.requiredVersionAvailable = function(requiredVersion) {
  * @param {string} opt_tag The type of tag to look for. The default is "div".
  */
 o3djs.util.offerPlugin = function(opt_id, opt_tag) {
-  var tag = opt_tag || 'div';
-  var id = opt_id || '^o3d';
   var havePlugin = o3djs.util.requiredVersionAvailable('');
-  var elements = document.getElementsByTagName(tag);
+  var elements = o3djs.util.getO3DContainerElements(opt_id, opt_tag);
   var addedMessage = false;
   // TODO: This needs to be localized OR we could insert a html like
   // <script src="http://google.com/o3d_plugin_dl"></script>
@@ -359,14 +399,12 @@ o3djs.util.offerPlugin = function(opt_id, opt_tag) {
       '</div>'
   for (var ee = 0; ee < elements.length; ++ee) {
     var element = elements[ee];
-    if (element.id && element.id.match(id)) {
-      if (element.clientWidth >= 200 &&
-          element.clientHeight >= 200 &&
-          element.style.display.toLowerCase() != 'none' &&
-          element.style.visibility.toLowerCase() != 'hidden') {
-        addedMessage = true;
-        element.innerHTML = message;
-      }
+    if (element.clientWidth >= o3djs.util.MINIMUM_WIDTH_FOR_MESSAGE &&
+        element.clientHeight >= o3djs.util.MINIMUM_HEIGHT_FOR_MESSAGE &&
+        element.style.display.toLowerCase() != 'none' &&
+        element.style.visibility.toLowerCase() != 'hidden') {
+      addedMessage = true;
+      element.innerHTML = message;
     }
   }
   if (!addedMessage) {
@@ -392,9 +430,7 @@ o3djs.util.offerPlugin = function(opt_id, opt_tag) {
  * @param {string} opt_tag The type of tag to look for. The default is "div".
  */
 o3djs.util.informNoGraphics = function(initStatus, error, opt_id, opt_tag) {
-  var tag = opt_tag || 'div';
-  var id = opt_id || '^o3d';
-  var elements = document.getElementsByTagName(tag);
+  var elements = o3djs.util.getO3DContainerElements(opt_id, opt_tag);
   var addedMessage = false;
   var subMessage;
   var message;
@@ -453,14 +489,12 @@ o3djs.util.informNoGraphics = function(initStatus, error, opt_id, opt_tag) {
   }
   for (var ee = 0; ee < elements.length; ++ee) {
     var element = elements[ee];
-    if (element.id && element.id.match(id)) {
-      if (element.clientWidth >= 200 &&
-          element.clientHeight >= 200 &&
-          element.style.display.toLowerCase() != 'none' &&
-          element.style.visibility.toLowerCase() != 'hidden') {
-        addedMessage = true;
-        element.innerHTML = message;
-      }
+    if (element.clientWidth >= o3djs.util.MINIMUM_WIDTH_FOR_MESSAGE &&
+        element.clientHeight >= o3djs.util.MINIMUM_HEIGHT_FOR_MESSAGE &&
+        element.style.display.toLowerCase() != 'none' &&
+        element.style.visibility.toLowerCase() != 'hidden') {
+      addedMessage = true;
+      element.innerHTML = message;
     }
   }
   if (!addedMessage) {
@@ -708,9 +742,9 @@ o3djs.util.getScriptTagText_ = function() {
 };
 
 /**
- * Creates a client element.  In other words it creates an <OBJECT> tag for
- * o3d. Note that the browser may not have initialized the plugin before
- * returning.
+ * Creates a client element.  In other words it creates an <OBJECT> tag for o3d.
+ * <b>Note that the browser may not have initialized the plugin before
+ * returning.</b>
  * @param {!Element} element The DOM element under which the client element
  *    will be appended.
  * @param {string} opt_features A comma separated list of the
@@ -782,6 +816,47 @@ o3djs.util.createClient = function(element, opt_features, opt_requestVersion) {
  * This allows you to specify different features per area. Otherwise you can
  * request features as an argument to this function.
  *
+ * Normally this function handles failure for you but if you want to handle
+ * failure in your own way you can supply a failure callback. Here is an example
+ * of using this function with your own failure callback.
+ *
+ * <pre>
+ * &lt;script type="text/javascript" id="o3dscript"&gt;
+ * o3djs.require('o3djs.util');
+ *
+ * window.onload = init;
+ *
+ * function init() {
+ *  o3djs.util.makeClients(onSuccess, '', undefined, onFailure);
+ * }
+ *
+ * function onFailure(initStatus, error, id, tag) {
+ *   // Get a list of the elements that would have had an O3D plugin object
+ *   // inserted if it had succeed.
+ *   var elements = o3djs.util.getO3DContainerElements(id, tag);
+ *
+ *   switch (initStatus) {
+ *     case o3djs.util.rendererInitStatus.NO_PLUGIN:
+ *       // Tell the user there is no plugin
+ *       ...
+ *       break;
+ *     case o3djs.util.rendererInitStatus.OUT_OF_RESOURCES:
+ *     case o3djs.util.rendererInitStatus.GPU_NOT_UP_TO_SPEC:,
+ *     case o3djs.util.rendererInitStatus.INITIALIZATION_ERROR:
+ *     default:
+ *       // Tell the user there are other issues
+ *       ...
+ *       break;
+ *   }
+ * }
+ *
+ * function onSuccess(o3dElementsArray) {
+ *   // Run your app.
+ *   ...
+ * }
+ * &lt;/script&gt;
+ * </pre>
+ *
  * @param {!function(Array.<!Element>): void} callback Function to call when
  *     client objects have been created.
  * @param {string} opt_features A comma separated list of the
@@ -801,14 +876,17 @@ o3djs.util.createClient = function(element, opt_features, opt_requestVersion) {
  *     "2.4" = require major version 2, minor version 4. If no string is
  *     passed in the version of the needed by this version of the javascript
  *     libraries will be created.
- * @param {!function(!o3d.Renderer.InitStatus, string, string, string): void}
- *     opt_failureCallback Function to call if the plugin does not exist, if the
- *     required version is not installed, or if for some other reason the plugin
- *     can not start. If this function is not specified or is null the default
- *     behavior of leading the user to the download page will be provided.
+ * @param {!function(!o3d.Renderer.InitStatus, string, (string|undefined),
+ *     (string|undefined)): void} opt_failureCallback Function to call if the
+ *     plugin does not exist, if the required version is not installed, or if
+ *     for some other reason the plugin can not start. If this function is not
+ *     specified or is null the default behavior of leading the user to the
+ *     download page will be provided. See o3djs.util.informPluginFailure for an
+ *     example of this type of callback.
  * @param {string} opt_id The id to look for. This can be a regular
  *     expression. The default is "^o3d".
  * @param {string} opt_tag The type of tag to look for. The default is "div".
+ * @see o3djs.util.informPluginFailure
  */
 o3djs.util.makeClients = function(callback,
                                   opt_features,
@@ -816,38 +894,35 @@ o3djs.util.makeClients = function(callback,
                                   opt_failureCallback,
                                   opt_id,
                                   opt_tag) {
-  var tag = opt_tag || 'div';
-  var id = opt_id || '^o3d';
   opt_failureCallback = opt_failureCallback || o3djs.util.informPluginFailure;
   opt_requiredVersion = opt_requiredVersion || o3djs.util.REQUIRED_VERSION;
   if (!o3djs.util.requiredVersionAvailable(opt_requiredVersion)) {
-    opt_failureCallback(o3djs.util.rendererInitStatus.NO_PLUGIN, '', id, tag);
+    opt_failureCallback(o3djs.util.rendererInitStatus.NO_PLUGIN, '',
+                        opt_id, opt_tag);
   } else {
     var clientElements = [];
-    var elements = document.getElementsByTagName(tag);
+    var elements = o3djs.util.getO3DContainerElements(opt_id, opt_tag);
     var mainClientElement = null;
     for (var ee = 0; ee < elements.length; ++ee) {
       var element = elements[ee];
-      if (element.id && element.id.match(id)) {
-        var features = opt_features;
-        if (!features) {
-          var o3d_features = element.getAttribute('o3d_features');
-          if (o3d_features) {
-            features = o3d_features;
-          } else {
-            features = '';
-          }
+      var features = opt_features;
+      if (!features) {
+        var o3d_features = element.getAttribute('o3d_features');
+        if (o3d_features) {
+          features = o3d_features;
+        } else {
+          features = '';
         }
+      }
 
-        var objElem = o3djs.util.createClient(element, features);
-        clientElements.push(objElem);
+      var objElem = o3djs.util.createClient(element, features);
+      clientElements.push(objElem);
 
-        // If the callback is to be invoked in an embedded JavaScript engine,
-        // one element must be identified with the id 'o3d'. This callback
-        // will be invoked in the element identified as such.
-        if (element.id === 'o3d') {
-          mainClientElement = objElem;
-        }
+      // If the callback is to be invoked in an embedded JavaScript engine,
+      // one element must be identified with the id 'o3d'. This callback
+      // will be invoked in the element identified as such.
+      if (element.id === 'o3d') {
+        mainClientElement = objElem;
       }
     }
 
@@ -901,7 +976,7 @@ o3djs.util.makeClients = function(callback,
             var clientElement = clientElements[cc];
             clientElement.parentNode.removeChild(clientElement);
           }
-          opt_failureCallback(initStatus, error, id, tag);
+          opt_failureCallback(initStatus, error, opt_id, opt_tag);
         } else {
           o3djs.base.snapshotProvidedNamespaces();