[Projekt: Entwicklung - Neon][TicketNr.: 1027750][JDito - libray Standard ist...

[Projekt: Entwicklung - Neon][TicketNr.: 1027750][JDito - libray Standard ist komplett definiert und wird in allen libs verwendet]

others/guide/how to write a library.adoc

-How to write a JDito library
-============================
-:toc2: left
-:numbered:
-
-
-== defining different types of functions ==
-
-=== by using static methods ===
-This will be mostly utility functions and so on, where there is no need to instanciate an object. You'll need this probably the most time.
-
-
-Definition:
-[source,javascript]
-----
-/**
- * provides static methods for validation of communication data
- * do not create an instance of this
- * @static
- * @class
- */
-function CommValidationUtil(){<1>
-}
-
-/**
- * returns a blueprint for validation extensions; these extensions are needed for validating comm data and can be passed to other functions
- * @return {object} a object with properties that have a specific default value; normally you want to overwrite that value
- */
-CommValidationUtil.getExtensionsBlueprint = function(){<2>
-    return {
-        countryCode: null
-    };
-}
-----
-<1> the function-object that keeps everything together - this function should never be actually called (no direct call, no indirect call)
-<2> an actual function that can be called
-
-And how to use it:
-[source,javascript]
-----
-import("Comm_lib");
-
-var additionals = CommValidationUtil.getExtensionsBlueprint();
-----
-
-=== by creating an object with functions ===
-
-You may want to hold data and create objects where methods share that data. 
-
-Definition:
-[source,javascript]
-----
-/**
- * object for easier handling of conditions; <1>
- * With this object you do not have to check if the string is empty or not;
- * you don't need to append a "1=1" condition or similar;
- * this objects gains most benefit if you have a lot of conditions that are added (or not) depending on tons of JDito-conditions
- * @class 
- * @param {String} [alias=the current alias] the database alias where the condition shall be executed later (important for column types of preparedStatements) <2>
- * @example //TODO: add missing example <3>
- */
-function SqlCondition(alias){<4>
-   //setting null is only needed to provide autocomplete for the ADITO-designer
-    this.preparedValues = null;
-    this._init();//the properties are initalized in an extra function because init is nearly the same as resetting (clearing) the SqlConditions
-    this.alias = alias;
-}
-/**
- * append with SQL-and; no paranthesize of existing conditions is done
- * @param {String} cond the condition string which shall be appended
- * @return {Object} current SqlCondition-object
- */
-SqlCondition.prototype.and = function(cond){<5>
-    if (!cond)
-        return this;
-    if (this._sqlStorage)
-        this._sqlStorage += " and ";
-    this._sqlStorage += cond;
-    return this;
-}
-----
-
-<1> JS-Doc comment: http://usejsdoc.org/
-<2> use the correct form for optional/required parameters: http://usejsdoc.org/tags-param.html
-<3> examples are usefull on more complex functions
-<4> constructor function; init propiertes (do not set functions ("methods") here!)
-<5> add functions ("methods") to the prototype, they are available through the prototype chain
-
-And how to use it (normally you'd want to use preparedStatements but for the sake of an easy example it's a bit shorter here)
-[source,javascript]
-----
-import("system.vars");
-import("system.result");
-import("Sql_lib");
-import("Comm_lib");
-
-var cond, mediumIds, idVal;
-
-cond = new SqlCondition();
-
-mediumIds = CommExtensions.getContextualMediumIds();
-if (mediumIds.length > 0)
-    cond.and("COMM.MEDIUM_ID in (" + mediumIds.join(", ") + ")");
-
-idVal = vars.get("$local.idvalue");
-if (uids.length > 0)
-    cond.and("COMM.COMMID = '" + idVal + "' ");
-
-result.string(cond.toString("COMM.OPTIONAL = 't'"));
-----
\ No newline at end of file