Addition of type-checking helper functions, various tweaks to comments, code style...

git-svn-id: http://code.elgg.org/elgg/trunk@7252 36083f99-b078-4883-b0ff-0f9b5a30f544

diff --git a/js/lib/elgglib.js b/js/lib/elgglib.js
index 5f1edf812748bf886767bdc05ee3d466c0e027ec..d71e827472951e6c85674fd035f1572c2cc39307 100644 (file)
--- a/js/lib/elgglib.js
+++ b/js/lib/elgglib.js
@@ -1,24 +1,132 @@
 /**\r
+ * @namespace Singleton object for holding the Elgg javascript library\r
+ */\r
+var elgg = elgg || {};\r
+\r
+/**\r
+ * Pointer to the global context\r
  * \r
+ * @see elgg.require\r
+ * @see elgg.provide\r
+ */\r
+elgg.global = this;\r
+\r
+/**\r
+ * Convenience reference to an empty function.\r
  * \r
+ * Save memory by not generating multiple empty functions.\r
  */\r
+elgg.nullFunction = function() {};\r
 \r
 /**\r
- * @namespace Namespace for elgg javascript functions\r
+ * \r
+ * @example\r
+ * AbstractClass.prototype.toBeImplemented = elgg.abstractMethod;\r
+ * \r
+ * Now this forces an inheriting class to implement the method or\r
+ * it will throw an error.\r
  */\r
-var elgg = elgg || {};\r
+elgg.abstractMethod = function(name) {\r
+       throw new Error("Oops... you forgot to implement " + name + "!");\r
+};\r
 \r
-elgg.assertTypeOf = function(type, param) {\r
-       if (typeof param !== type) {\r
-               throw new TypeError("Expecting param to be a(n) " + type + ".  Was a(n) " + typeof param + ".");\r
-       }\r
+/**\r
+ * Check if the value is an array.  \r
+ * \r
+ * No sense in reinventing the wheel!\r
+ * \r
+ * @return boolean\r
+ */\r
+elgg.isArray = jQuery.isArray;\r
+\r
+/**\r
+ * Check if the value is a function.  \r
+ * \r
+ * No sense in reinventing the wheel!\r
+ * \r
+ * @return boolean\r
+ */\r
+elgg.isFunction = jQuery.isFunction;\r
+\r
+/**\r
+ * Check if the value is a "plain" object (i.e., created by {} or new Object())\r
+ * \r
+ * No sense in reinventing the wheel!\r
+ * \r
+ * @return boolean\r
+ */\r
+elgg.isPlainObject = jQuery.isPlainObject;\r
+\r
+/**\r
+ * Check if the value is a string\r
+ * \r
+ * @param {*} val\r
+ * \r
+ * @return boolean\r
+ */\r
+elgg.isString = function(val) {\r
+       return typeof val === 'string';\r
 };\r
 \r
 /**\r
- * Pointer to the global context\r
- * {@see elgg.require} and {@see elgg.provide}\r
+ * Check if the value is an object\r
+ * \r
+ * @note This returns true for functions and arrays!  If you want to return true only\r
+ * for "plain" objects (created using {} or new Object()) use elgg.isPlainObject.\r
+ * \r
+ * @param {*} val\r
+ * \r
+ * @return boolean\r
  */\r
-elgg.global = this;\r
+elgg.isObject = function(val) {\r
+       return typeof val === 'object';\r
+};\r
+\r
+/**\r
+ * Check if the value is undefined\r
+ * \r
+ * @param {*} val\r
+ * \r
+ * @return boolean\r
+ */\r
+elgg.isUndefined = function(val) {\r
+       return val === undefined;\r
+};\r
+\r
+/**\r
+ * Check if the value is null\r
+ * \r
+ * @param {*} val\r
+ * \r
+ * @return boolean\r
+ */\r
+elgg.isNull = function(val) {\r
+       return val === null;\r
+};\r
+\r
+/**\r
+ * Check if the value is either null or undefined\r
+ * \r
+ * @param {*} val\r
+ * \r
+ * @return boolean\r
+ */\r
+elgg.isNullOrUndefined = function(val) {\r
+       return val == null;\r
+};\r
+\r
+/**\r
+ * Throw an exception of the type doesn't match\r
+ * \r
+ * @todo Might be more appropriate for debug mode only?\r
+ */\r
+elgg.assertTypeOf = function(type, val) {\r
+       if (typeof val !== type) {\r
+               throw new TypeError("Expecting param of " + \r
+                       arguments.caller + "to be a(n) " + type + "." + \r
+                       "  Was actually a(n) " + typeof val + ".");\r
+       }\r
+};\r
 \r
 /**\r
  * Throw an error if the required package isn't present\r
@@ -30,12 +138,12 @@ elgg.require = function(pkg) {
        \r
        var parts = pkg.split('.'),\r
                cur = elgg.global,\r
-               part;\r
+               part, i;\r
 \r
-       for (var i = 0; i < parts.length; i++) {\r
+       for (i = 0; i < parts.length; i += 1) {\r
                part = parts[i];\r
                cur = cur[part];\r
-               if(typeof cur == 'undefined') {\r
+               if (elgg.isUndefined(cur)) {\r
                        throw new Error("Missing package: " + pkg);\r
                }\r
        }\r
@@ -60,17 +168,18 @@ elgg.require = function(pkg) {
  * \r
  * @param {string} pkg The package name.\r
  */\r
-elgg.provide = function(pkg) {\r
+elgg.provide = function(pkg, opt_context) {\r
        elgg.assertTypeOf('string', pkg);\r
        \r
        var parts = pkg.split('.'),\r
-               cur = elgg.global,\r
-               part;\r
+               context = opt_context || elgg.global,\r
+               part, i;\r
        \r
-       for (var i = 0; i < parts.length; i++) {\r
+       \r
+       for (i = 0; i < parts.length; i += 1) {\r
                part = parts[i];\r
-               cur[part] = cur[part] || {};\r
-               cur = cur[part];\r
+               context[part] = context[part] || {};\r
+               context = context[part];\r
        }\r
 };\r
 \r
@@ -113,7 +222,8 @@ elgg.normalize_url = function(url) {
        url = url || '';\r
        elgg.assertTypeOf('string', url);\r
        \r
-       if(/(^(https?:)?\/\/)/.test(url)) {\r
+       // jslint complains if you use /regexp/ shorthand here... ?!?!\r
+       if ((new RegExp("^(https?:)?//")).test(url)) {\r
                return url;\r
        }\r
        \r
@@ -129,33 +239,36 @@ elgg.normalize_url = function(url) {
  * @private\r
  */\r
 elgg.system_messages = function(msgs, delay, type) {\r
-       if (msgs == undefined) {\r
+       if (elgg.isUndefined(msgs)) {\r
                return;\r
        }\r
        \r
+       var classes = [],\r
+               messages_html = [],\r
+               i;\r
+       \r
        //validate delay.  Must be a positive integer. \r
-       delay = parseInt(delay);\r
+       delay = parseInt(delay, 10);\r
        if (isNaN(delay) || delay <= 0) {\r
                delay = 6000;\r
        }\r
        \r
        classes = ['elgg_system_message', 'radius8'];\r
-       if (type == 'error') {\r
+       if (type === 'error') {\r
                classes.push('messages_error');\r
        }\r
 \r
        //Handle non-arrays\r
-       if (msgs.constructor.toString().indexOf("Array") == -1) {\r
+       if (!elgg.isArray(msgs)) {\r
                msgs = [msgs];\r
        }\r
        \r
-       var messages_html = [];\r
-       \r
-       for (var i in msgs) {\r
+       for (i in msgs) {\r
                messages_html.push('<div class="' + classes.join(' ') + '"><p>' + msgs[i] + '</p></div>');\r
        }\r
        \r
-       $(messages_html.join('')).appendTo('#elgg_system_messages').animate({opacity:'1.0'},delay).fadeOut('slow');\r
+       $(messages_html.join('')).appendTo('#elgg_system_messages')\r
+           .animate({opacity: '1.0'}, delay).fadeOut('slow');\r
 };\r
 \r
 /**\r