Refactored the general_functions.js file.

src/assets/js/general_functions.js

@@ -9,33 +9,36 @@
  * @since       v1.0.0
  * ---------------------------------------------------------------------------- */
 
+window.GeneralFunctions = window.GeneralFunctions || {};
+
 /**
- * This file contains the General Functions javascript namespace.
+ * General Functions Module
- * It contains functions that apply both on the front and back
- * end of the application.
  *
- * @namespace GeneralFunctions
+ * It contains functions that apply both on the front and back end of the application.
+ *
+ * @module GeneralFunctions
  */
-var GeneralFunctions = {
+(function(exports) {
+
+    'use strict';
+
     /**
      * General Functions Constants
      */
-    EXCEPTIONS_TITLE: EALang['unexpected_issues'],
+    exports.EXCEPTIONS_TITLE = EALang['unexpected_issues'];
-    EXCEPTIONS_MESSAGE: EALang['unexpected_issues_message'],
+    exports.EXCEPTIONS_MESSAGE = EALang['unexpected_issues_message'];
-    WARNINGS_TITLE: EALang['unexpected_warnings'],
+    exports.WARNINGS_TITLE = EALang['unexpected_warnings'];
-    WARNINGS_MESSAGE: EALang['unexpected_warnings_message'],
+    exports.WARNINGS_MESSAGE = EALang['unexpected_warnings_message'];
 
     /**
-     * This functions displays a message box in
+     * This functions displays a message box in the admin array. It is usefull when user
-     * the admin array. It is usefull when user
      * decisions or verifications are needed.
      *
      * @param {string} title The title of the message box.
      * @param {string} message The message of the dialog.
-     * @param {array} messageButtons Contains the dialog
+     * @param {array} messageButtons Contains the dialog buttons along with their functions.
-     * buttons along with their functions.
      */
-    displayMessageBox: function(title, message, messageButtons) {
+    exports.displayMessageBox = function(title, message, messageButtons) {
         // Check arguments integrity.
         if (title == undefined || title == '') {
             title = '<No Title Given>';
@@ -77,16 +80,14 @@ var GeneralFunctions = {
         $('#message_box').dialog('open');
         $('.ui-dialog .ui-dialog-buttonset button').addClass('btn btn-default');
         $('#message_box .ui-dialog-titlebar-close').hide();
-    },
+    };
 
     /**
-     * This method centers a DOM element vertically and horizontally
+     * This method centers a DOM element vertically and horizontally on the page.
-     * on the page.
      *
-     * @param {object} elementHandle The object that is going to be
+     * @param {object} elementHandle The object that is going to be centered.
-     * centered.
      */
-    centerElementOnPage: function(elementHandle) {
+    exports.centerElementOnPage = function(elementHandle) {
         // Center main frame vertical middle
         $(window).resize(function() {
             var elementLeft = ($(window).width() - elementHandle.outerWidth()) / 2;
@@ -100,7 +101,7 @@ var GeneralFunctions = {
             });
         });
         $(window).resize();
-    },
+    };
 
     /**
      * This function retrieves a parameter from a "GET" formed url.
@@ -109,24 +110,26 @@ var GeneralFunctions = {
      *
      * @param {string} url The selected url.
      * @param {string} name The parameter name.
-     * @returns {String} Returns the parameter value.
+
+     * @return {string} Returns the parameter value.
      */
-    getUrlParameter: function(url, parameterName) {
+    exports.getUrlParameter = function(url, parameterName) {
         parameterName = parameterName.replace(/[\[]/,'\\\[').replace(/[\]]/,'\\\]');
         var regexS = '[\\#&]' + parameterName + '=([^&#]*)',
             regex = new RegExp(regexS),
             results = regex.exec(url);
         return (results == null) ? '' : results[1];
-    },
+    };
 
     /**
-     * This function creates a RFC 3339 date string. This string is needed
+     * This function creates a RFC 3339 date string. This string is needed by the Google Calendar API
-     * by the Google Calendar API in order to pass dates as parameters.
+     in order to pass dates as parameters.
      *
-     * @param {date} dt The given date that will be transformed
+     * @param {date} dt The given date that will be transformed.
-     * @returns {String} Returns the transformed string.
+
+     * @return {String} Returns the transformed string.
      */
-    ISODateString: function(dt) {
+    exports.ISODateString = function(dt) {
         function pad(n) {
             return n<10 ? '0'+n : n;
         }
@@ -137,19 +140,21 @@ var GeneralFunctions = {
              + pad(dt.getUTCHours())+':'
              + pad(dt.getUTCMinutes())+':'
              + pad(dt.getUTCSeconds())+'Z';
-    },
+    };
 
     /**
      * This method creates and returns an exact copy of the provided object.
+
      * It is very usefull whenever changes need to be made to an object without
      * modyfing the original data.
      *
      * @link http://stackoverflow.com/questions/728360/most-elegant-way-to-clone-a-javascript-object
      *
      * @param {object} originalObject Object to be copied.
-     * @returns {object} Returns an exact copy of the provided element.
+
+     * @return {object} Returns an exact copy of the provided element.
      */
-    clone: function(originalObject) {
+    exports.clone = function(originalObject) {
         // Handle the 3 simple types, and null or undefined
         if (null == originalObject || 'object' != typeof originalObject)
             return originalObject;
@@ -181,7 +186,7 @@ var GeneralFunctions = {
         }
 
         throw new Error('Unable to copy obj! Its type isn\'t supported.');
-    },
+    };
 
     /**
      * This method validates an email address. If the address is not on the proper
@@ -190,22 +195,25 @@ var GeneralFunctions = {
      * @link http://badsyntax.co/post/javascript-email-validation-rfc822
      *
      * @param {string} email The email address to be checked.
-     * @returns {bool} Returns the validation result.
+
+     * @return {bool} Returns the validation result.
      */
-    validateEmail: function (email) {
+    exports.validateEmail = function (email) {
         var re = /^([^\x00-\x20\x22\x28\x29\x2c\x2e\x3a-\x3c\x3e\x40\x5b-\x5d\x7f-\xff]+|\x22([^\x0d\x22\x5c\x80-\xff]|\x5c[\x00-\x7f])*\x22)(\x2e([^\x00-\x20\x22\x28\x29\x2c\x2e\x3a-\x3c\x3e\x40\x5b-\x5d\x7f-\xff]+|\x22([^\x0d\x22\x5c\x80-\xff]|\x5c[\x00-\x7f])*\x22))*\x40([^\x00-\x20\x22\x28\x29\x2c\x2e\x3a-\x3c\x3e\x40\x5b-\x5d\x7f-\xff]+|\x5b([^\x0d\x5b-\x5d\x80-\xff]|\x5c[\x00-\x7f])*\x5d)(\x2e([^\x00-\x20\x22\x28\x29\x2c\x2e\x3a-\x3c\x3e\x40\x5b-\x5d\x7f-\xff]+|\x5b([^\x0d\x5b-\x5d\x80-\xff]|\x5c[\x00-\x7f])*\x5d))*$/;
         return re.test(email);
-    },
+    };
 
     /**
-     * This method returns the exception html display for javascript ajax calls.
+     * This method returns the exception HTML display for javascript ajax calls.
+
      * It uses the Bootstrap collapse module to show exception messages when the
      * user opens the "Details" collapse component.
      *
      * @param {array} exceptions Contains the exceptions to be displayed.
-     * @returns {string} Returns the html markup for the exceptions.
+     *
+     * @return {string} Returns the html markup for the exceptions.
      */
-    exceptionsToHtml: function(exceptions) {
+    exports.exceptionsToHtml = function(exceptions) {
         var html =
                 '<div class="accordion" id="error-accordion">' +
                     '<div class="accordion-group">' +
@@ -228,7 +236,7 @@ var GeneralFunctions = {
         html += '</div></div>';
 
         return html;
-    },
+    };
 
     /**
      * This method parse the json encoded strings that are fetched by ajax calls.
@@ -236,7 +244,7 @@ var GeneralFunctions = {
      * @param {array} exceptions Exception array returned by an ajax call.
      * @returns {array} Returns the parsed js objects.
      */
-    parseExceptions: function(exceptions) {
+    exports.parseExceptions = function(exceptions) {
         var parsedExceptions = new Array();
 
         $.each(exceptions, function(index, exception) {
@@ -244,7 +252,7 @@ var GeneralFunctions = {
         });
 
         return parsedExceptions;
-    },
+    };
 
     /**
      * Makes the first letter of the string upper case.
@@ -252,20 +260,21 @@ var GeneralFunctions = {
      * @param {string} str The string to be converted.
      * @returns {string} Returns the capitalized string.
      */
-    ucaseFirstLetter: function(str){
+    exports.ucaseFirstLetter = function(str){
         return str.charAt(0).toUpperCase() + str.slice(1);
-    },
+    };
 
     /**
      * All backend js code has the same way of dislaying exceptions that are raised on the
      * server during an ajax call.
      *
      * @param {object} response Contains the server response. If exceptions or warnings are
-     * found, user friendly messages are going to be displayed to the user.
+     * found, user friendly messages are going to be displayed to the user.4
-     * @returns {bool} Returns whether the the ajax callback should continue the execution or
+     *
+     * @return {bool} Returns whether the the ajax callback should continue the execution or
      * stop, due to critical server exceptions.
      */
-    handleAjaxExceptions: function(response) {
+    exports.handleAjaxExceptions = function(response) {
         if (response.exceptions) {
             response.exceptions = GeneralFunctions.parseExceptions(response.exceptions);
             GeneralFunctions.displayMessageBox(GeneralFunctions.EXCEPTIONS_TITLE, GeneralFunctions.EXCEPTIONS_MESSAGE);
@@ -280,7 +289,7 @@ var GeneralFunctions = {
         }
 
         return true;
-    },
+    };
 
     /**
      * Enables the language selection functionality. Must be called on every page has a
@@ -289,7 +298,7 @@ var GeneralFunctions = {
      *
      * @param {object} $element Selected element button for the language selection.
      */
-    enableLanguageSelection: function($element) {
+    exports.enableLanguageSelection = function($element) {
     	// Select Language
         var html = '<ul id="language-list">';
         $.each(availableLanguages, function() {
@@ -330,7 +339,7 @@ var GeneralFunctions = {
 
         	}, 'json').fail(GeneralFunctions.ajaxFailureHandler);
         });
-    },
+    };
 
     /**
      * Use this method for common error handling between
@@ -339,7 +348,7 @@ var GeneralFunctions = {
      * @param {string} textStatus
      * @param {object} errorThrown
      */
-    ajaxFailureHandler: function(jqxhr, textStatus, errorThrown) {
+    exports.ajaxFailureHandler = function(jqxhr, textStatus, errorThrown) {
         var exceptions = [
             {
                 message: 'AJAX Error: ' + errorThrown
@@ -348,7 +357,7 @@ var GeneralFunctions = {
         GeneralFunctions.displayMessageBox(GeneralFunctions.EXCEPTIONS_TITLE,
             GeneralFunctions.EXCEPTIONS_MESSAGE);
         $('#message_box').append(GeneralFunctions.exceptionsToHtml(exceptions));
-    },
+    };
 
     /**
      * Escape JS HTML string values for XSS prevention.
@@ -356,9 +365,9 @@ var GeneralFunctions = {
      * @param {string} str String to be escaped.
      * @returns {string} Returns the escaped string.
      */
-    escapeHtml: function(str) {
+    exports.escapeHtml = function(str) {
         return $('<div/>').text(str).html();
-    },
+    };
 
     /**
      * Format a given date according to the date format setting.
@@ -367,9 +376,10 @@ var GeneralFunctions = {
      * @param {string} dateFormatSetting The setting provided by PHP must be one of
      * the "DMY", "MDY" or "YMD".
      * @param {bool} addHours (optional) Whether to add hours to the result.
-     * @returns {string} Returns the formatted date string.
+
+     * @return {string} Returns the formatted date string.
      */
-    formatDate: function(date, dateFormatSetting, addHours) {
+    exports.formatDate = function(date, dateFormatSetting, addHours) {
         var format, result,
             hours = addHours ? ' HH:mm' : '';
 
@@ -388,5 +398,6 @@ var GeneralFunctions = {
         }
 
         return result;
-    }
     };
+
+})(window.GeneralFunctions);