added comments to Keyword_lib

[Projekt: Entwicklung - Neon][TicketNr.: 1022526][Bereitstellung erste Version 5.1 Customizing für Gremium]

process/Keyword_lib/process.js

-import("system.logging");
-import("system.translate");
-
-/**
- * provides methods for interactions with keywords
- */
-function KeywordUtils(){
-    /**
-     * returns the default case for keyword-arrays (id and translated name)
-     * @param {String} keywordType specifies the type of the keyword and therefore the list elements; e.g. "COUNTRY"
-     * @return {Array} a 2D array in form of [["id1", "name1"], ["idN", "nameN"]]
-     * @example
-     * var kwdUtils, items;
-     * 
-     * kwdUtils = new KeywordUtils();
-     * items = kwdUtils.getStandardArray("ADDRESS.TYPE");
-     * result.object(items);
-     */
-    this.getStandardArray = function(keywordType){
-        return this.createKeyword(keywordType).toArray(["id", "name"]);
-    }
-    
-    /**
-     * returns a specific name (translated) - this is normally the view-value - of a given keyword;
-     * <br/>if the key could not be found an empty string "" is returned 
-     * @param {String} keywordType specifies the type of the keyword and therefore the list elements; e.g. "COUNTRY"
-     * @param {String} key id value of the keyword where the view-value shall be searched
-     * @return {String} representation of the translated name of the keyword-key
-     * @example
-     * var kwdUtils, histMedium;
-     * histMedium = vars.get("$field.MEDIUM");
-     * if (histMedium){
-     *     kwdUtils = new KeywordUtils();
-     *     result.string(vars.get("$field.SUBJECT") + " (" + kwdUtils.getViewValue("HISTORY.MEDIUM", histMedium) + ")");
-     * }
-     */
-    this.getViewValue = function(keywordType, key){
-        var k = this.createKeyword(keywordType);
-        return k.getPropForKey(key, "name") || "";
-    }
-    
-    /**
-     * creates an object with methods for interacting with an specific keyword
-     * @param {String} keywordType specifies the type of the keyword and therefore the list elements; e.g. "COUNTRY"
-     * @return {Object} object with the following methods:
-     * <br/>- toArray
-     * <br/>- getPropForKey
-     * <br/>- getPropsForKey
-     */
-    this.createKeyword = function(keywordType){
-        var valueContainer, _toArrayFn, _getPropForKeyFn, _getPropsForKeyFn;
-
-        switch (keywordType){
-            case "RELATION.STATUS":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("0", translate.text("Inactive"))
-                    ,createKeywordEntry("1", translate.text("Active"))
-                    ,createKeywordEntry("2", translate.text("In review"))
-                ]);
-                break;
-            case "COUNTRY":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("DE", translate.text("Germany"))
-                    ,createKeywordEntry("AT", translate.text("Austria"))
-                    ,createKeywordEntry("CH", translate.text("Switzerland"))
-                    ,createKeywordEntry("GB", translate.text("United Kingdom"))
-                    ,createKeywordEntry("NO", translate.text("Norway"))
-                ]);
-                break;
-            case "LANGUAGE":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("de", translate.text("German"))
-                    ,createKeywordEntry("de-DE", translate.text("German (Germany)"))
-                    ,createKeywordEntry("de-AT", translate.text("German (Austria)"))
-                    ,createKeywordEntry("en", translate.text("English"))
-                    ,createKeywordEntry("en-GB", translate.text("English (United Kingdom)"))
-                    ,createKeywordEntry("no-NO", translate.text("Norwegian"))
-                ]);
-                break;
-            case "HISTORY.DIRECTION":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("i", translate.text("Incoming"))
-                    ,createKeywordEntry("o", translate.text("Outgoing"))
-                ]);
-                break;
-            case "HISTORY.MEDIUM":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("0", translate.text("Visit"))
-                    ,createKeywordEntry("1", translate.text("E-Mail"))
-                    ,createKeywordEntry("2", translate.text("Phone"))
-                    ,createKeywordEntry("3", translate.text("Internal"))
-                    ,createKeywordEntry("4", translate.text("Online-Meeting"))
-                ]);
-            case "COMM.MEDIUM":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("0", translate.text("Mobile"))
-                    ,createKeywordEntry("1", translate.text("E-Mail"))
-                    ,createKeywordEntry("2", translate.text("Phone"))
-                    ,createKeywordEntry("3", translate.text("Internet"))
-                ]);
-                break;
-            case "ADDRESS.TYPE":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("1", translate.text("Office address"))
-                    ,createKeywordEntry("2", translate.text("Home address"))
-                    ,createKeywordEntry("3", translate.text("Delivery address"))
-                    ,createKeywordEntry("4", translate.text("Post office box"))
-                ]);
-                break;
-            case "ORG.TYPE":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("0", translate.text("Customer"))
-                    ,createKeywordEntry("1", translate.text("Prospect"))
-                    ,createKeywordEntry("2", translate.text("Supplier"))
-                    ,createKeywordEntry("3", translate.text("Other"))
-                ]);
-                break;
-            case "PERS.GENDER":
-                valueContainer = createKeywordEntriesContainer([
-                     createKeywordEntry("f", translate.text("Female"))
-                    ,createKeywordEntry("m", translate.text("Male"))
-                    ,createKeywordEntry("o", translate.text("${GENDER_OTHER}"))
-                ]);
-                break;
-            default: 
-                throw new Error(translate.withArguments("[%0]the given keyword \"%1\" has no match with the possible keywordlist", [
-                    arguments.callee.name, keywordType
-                ]));
-                break;
-        }
-
-
-        _getPropForKeyFn = function(key, field) {
-            var keyObject = valueContainer[key];
-            if (keyObject == undefined)
-                return undefined;
-            return keyObject[field];
-        };
-        
-        _getPropsForKeyFn = function(key, fields) {
-            var keyObject, i, l, currentRow, currentField;
-            
-            keyObject = valueContainer[key];
-            if (keyObject == undefined)
-                return [];//TODO: throw error instead?
-            l = fields.length;
-            currentRow = [];
-            for (i = 0; i < l; i++){
-                currentField = fields[i];
-                //check if the passed fieldnames match the existing fieldnames (<=> properties in the object)
-                //to prevent errors and unexpected behaviour
-                if (keyObject[currentField])
-                    currentRow.push(keyObject[currentField]);
-                else
-                    currentRow.push("");
-            }
-            return currentRow;
-        };
-        
-        _toArrayFn = function(fields){
-            var res, id, currentRow;
-
-            res = [];
-            if (!fields)
-                fields = ["id", "name"];
-            l = fields.length;
-            for (id in valueContainer){
-                currentRow = _getPropsForKeyFn(id, fields);
-                res.push(currentRow);
-            }
-            return res;
-        };
-
-        return {
-            /**
-             * toArray
-             */
-             toArray: _toArrayFn
-            ,getPropForKey: _getPropForKeyFn
-            ,getPropsForKey: _getPropsForKeyFn
-        };
-    };
-    
-    
-    function createKeywordEntry(id, name, description){
-        //TODO: verify if mandatory-checks are really that usefull or can at least be made easier
-        if (!id)
-            throw new Error(translate.withArguments("the param \"%0\" in \"%1\" is mandatory and has to be set", [
-                "id", arguments.callee.name
-            ]));
-        if (!name)
-            throw new Error(translate.withArguments("the param \"%0\" in \"%1\" is mandatory and has to be set", [
-                "name", arguments.callee.name
-            ]));
-
-        return {
-             id: id
-            ,name: name
-            ,description: description || ""
-        };
-    }
-
-    function createKeywordEntriesContainer(keywordEntries){
-        var res, i, l, id;
-
-        res = {};
-        for (i = 0, l = keywordEntries.length; i < l; i++){
-            id = keywordEntries[i].id;
-            if (res[id] != undefined){
-                throw new Error("the given id is not unique since it already exists");
-            }
-            res[id] = keywordEntries[i];
-        }
-        return res;
-    }
+import("system.logging");
+import("system.translate");
+
+/**
+ * provides methods for interactions with keywords
+ */
+function KeywordUtils(){
+    /**
+     * returns the default case for keyword-arrays (id and translated name)
+     * @param {String} keywordType specifies the type of the keyword and therefore the list elements; e.g. "COUNTRY"
+     * @return {Array} a 2D array in form of [["id1", "name1"], ["idN", "nameN"]]
+     * @example
+     * var kwdUtils, items;
+     * 
+     * kwdUtils = new KeywordUtils();
+     * items = kwdUtils.getStandardArray("ADDRESS.TYPE");
+     * result.object(items);
+     */
+    this.getStandardArray = function(keywordType){
+        return this.createKeyword(keywordType).toArray(["id", "name"]);
+    }
+    
+    /**
+     * returns a specific name (translated) - this is normally the view-value - of a given keyword;
+     * <br/>if the key could not be found an empty string "" is returned 
+     * @param {String} keywordType specifies the type of the keyword and therefore the list elements; e.g. "COUNTRY"
+     * @param {String} key id value of the keyword where the view-value shall be searched
+     * @return {String} representation of the translated name of the keyword-key
+     * @example
+     * var kwdUtils, histMedium;
+     * histMedium = vars.get("$field.MEDIUM");
+     * if (histMedium){
+     *     kwdUtils = new KeywordUtils();
+     *     result.string(vars.get("$field.SUBJECT") + " (" + kwdUtils.getViewValue("HISTORY.MEDIUM", histMedium) + ")");
+     * }
+     */
+    this.getViewValue = function(keywordType, key){
+        var k = this.createKeyword(keywordType);
+        return k.getPropForKey(key, "name") || "";
+    }
+    
+    /**
+     * creates an object with methods for interacting with an specific keyword
+     * @param {String} keywordType specifies the type of the keyword and therefore the list elements; e.g. "COUNTRY"
+     * @return {Object} object with the following methods:
+     * <br/>- toArray
+     * <br/>- getPropForKey
+     * <br/>- getPropsForKey
+     */
+    this.createKeyword = function(keywordType){
+        var valueContainer, _toArrayFn, _getPropForKeyFn, _getPropsForKeyFn;
+
+        switch (keywordType){
+            case "RELATION.STATUS":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("0", translate.text("Inactive"))
+                    ,createKeywordEntry("1", translate.text("Active"))
+                    ,createKeywordEntry("2", translate.text("In review"))
+                ]);
+                break;
+            case "COUNTRY":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("DE", translate.text("Germany"))
+                    ,createKeywordEntry("AT", translate.text("Austria"))
+                    ,createKeywordEntry("CH", translate.text("Switzerland"))
+                    ,createKeywordEntry("GB", translate.text("United Kingdom"))
+                    ,createKeywordEntry("NO", translate.text("Norway"))
+                ]);
+                break;
+            case "LANGUAGE":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("de", translate.text("German"))
+                    ,createKeywordEntry("de-DE", translate.text("German (Germany)"))
+                    ,createKeywordEntry("de-AT", translate.text("German (Austria)"))
+                    ,createKeywordEntry("en", translate.text("English"))
+                    ,createKeywordEntry("en-GB", translate.text("English (United Kingdom)"))
+                    ,createKeywordEntry("no-NO", translate.text("Norwegian"))
+                ]);
+                break;
+            case "HISTORY.DIRECTION":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("i", translate.text("Incoming"))
+                    ,createKeywordEntry("o", translate.text("Outgoing"))
+                ]);
+                break;
+            case "HISTORY.MEDIUM":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("0", translate.text("Visit"))
+                    ,createKeywordEntry("1", translate.text("E-Mail"))
+                    ,createKeywordEntry("2", translate.text("Phone"))
+                    ,createKeywordEntry("3", translate.text("Internal"))
+                    ,createKeywordEntry("4", translate.text("Online-Meeting"))
+                ]);
+            case "COMM.MEDIUM":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("0", translate.text("Mobile"))
+                    ,createKeywordEntry("1", translate.text("E-Mail"))
+                    ,createKeywordEntry("2", translate.text("Phone"))
+                    ,createKeywordEntry("3", translate.text("Internet"))
+                ]);
+                break;
+            case "ADDRESS.TYPE":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("1", translate.text("Office address"))
+                    ,createKeywordEntry("2", translate.text("Home address"))
+                    ,createKeywordEntry("3", translate.text("Delivery address"))
+                    ,createKeywordEntry("4", translate.text("Post office box"))
+                ]);
+                break;
+            case "ORG.TYPE":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("0", translate.text("Customer"))
+                    ,createKeywordEntry("1", translate.text("Prospect"))
+                    ,createKeywordEntry("2", translate.text("Supplier"))
+                    ,createKeywordEntry("3", translate.text("Other"))
+                ]);
+                break;
+            case "PERS.GENDER":
+                valueContainer = createKeywordEntriesContainer([
+                     createKeywordEntry("f", translate.text("Female"))
+                    ,createKeywordEntry("m", translate.text("Male"))
+                    ,createKeywordEntry("o", translate.text("${GENDER_OTHER}"))
+                ]);
+                break;
+            default: 
+                throw new Error(translate.withArguments("[%0]the given keyword \"%1\" has no match with the possible keywordlist", [
+                    arguments.callee.name, keywordType
+                ]));
+                break;
+        }
+
+
+        _getPropForKeyFn = function(key, field) {
+            var keyObject = valueContainer[key];
+            if (keyObject == undefined)
+                return undefined;
+            return keyObject[field];
+        };
+        
+        _getPropsForKeyFn = function(key, fields) {
+            var keyObject, i, l, currentRow, currentField;
+            
+            keyObject = valueContainer[key];
+            if (keyObject == undefined)
+                return [];//TODO: throw error instead?
+            l = fields.length;
+            currentRow = [];
+            for (i = 0; i < l; i++){
+                currentField = fields[i];
+                //check if the passed fieldnames match the existing fieldnames (<=> properties in the object)
+                //to prevent errors and unexpected behaviour
+                if (keyObject[currentField])
+                    currentRow.push(keyObject[currentField]);
+                else
+                    currentRow.push("");
+            }
+            return currentRow;
+        };
+        
+        _toArrayFn = function(fields){
+            var res, id, currentRow;
+
+            res = [];
+            if (!fields)
+                fields = ["id", "name"];
+            l = fields.length;
+            for (id in valueContainer){
+                currentRow = _getPropsForKeyFn(id, fields);
+                res.push(currentRow);
+            }
+            return res;
+        };
+
+        return {
+            /**
+             * toArray
+             */
+             toArray: _toArrayFn
+            ,getPropForKey: _getPropForKeyFn
+            ,getPropsForKey: _getPropsForKeyFn
+        };
+    };
+    
+    /**
+     * internal  function for creating an object that represents a keyword entry
+     * @param {String} id represents the key of an entry; a KeywordEntriesContainer can contain the same key only once
+     * @param {String} name represents the translated name of an entry; this is in most cases the view-value
+     * @param {String} [description=""] description text for describing the keyword
+     * @return {Object} object that represents a single keyword entry; normally severel entries are cumulated in a "keywordEntriesContainer"
+     */
+    function createKeywordEntry(id, name, description){
+        //TODO: verify if mandatory-checks are really that usefull or can at least be made easier
+        if (!id)
+            throw new Error(translate.withArguments("the param \"%0\" in \"%1\" is mandatory and has to be set", [
+                "id", arguments.callee.name
+            ]));
+        if (!name)
+            throw new Error(translate.withArguments("the param \"%0\" in \"%1\" is mandatory and has to be set", [
+                "name", arguments.callee.name
+            ]));
+
+        return {
+             id: id
+            ,name: name
+            ,description: description || ""
+        };
+    }
+
+    /**
+     * internal  function for creating an object that represents a container of several keywordEntries
+     * @param {Array} keywordEntries an Array of keywordEntry-objects (as they are created by "createKeywordEntry"
+     * @return {Object} object that contains several keywordEntries
+     */
+    function createKeywordEntriesContainer(keywordEntries){
+        var res, i, l, id;
+
+        res = {};
+        for (i = 0, l = keywordEntries.length; i < l; i++){
+            id = keywordEntries[i].id;
+            if (res[id] != undefined){
+                throw new Error("the given id is not unique since it already exists");
+            }
+            res[id] = keywordEntries[i];
+        }
+        return res;
+    }
 }
\ No newline at end of file