how to write JDito code.adoc

How to write JDito code

Table of Contents

• 1. basics
• 2. code structure
  • 2.1. vars and others (var, let)
  • 2.2. brackets
  • 2.3. loops
• 3. defining different types of functions n libraries
  • 3.1. by using static methods
  • 3.2. by creating an object with functions
  • 3.3. private functions
• 4. JS-Doc

1. basics

• Keep everything english. Every title, caption, messages, comments, etc. should be english. Add german translation to the languages if necessary.

• in JavaScript-Strings use " instead of ' - even if its only 1 character. ' is for SQL (within JS-Strings)

• Parameters should start with p.

2. code structure

2.1. vars and others (var, let)

• avoid let as much as possible because you cannot debug these variables

2.2. brackets

• { are placed on a new line

Example:

for (i = 0, i < dataLen; i++)
{
    //code here
}

myArray.forEach(function(pItem)
{
    // Do something
});

2.3. loops

nested loops should be defined with replicated indexer variables. Therefore it’s easy to see in which level of the counter you are. Even better would be a good and describing name.

Example:

for (i = 0, i < dataLen; i++)
{
    for (ii = 0, ii < dataLen[i].length; ii++)
    {
        //code...
    }
}

for (row = 0, row < dataLen; row++)
{
    for (col = 0, col < dataLen[row].length; col++)
    {
        //code...
    }
}

3. defining different types of functions n libraries

3.1. 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. -→ Static object with static functions.

Definition:

/**
 * 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:

import("Comm_lib");

var additionals = CommValidationUtil.getExtensionsBlueprint();

3.2. by creating an object with functions

You may want to hold data and create objects where methods share that data.

Definition:

/**
 * 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(pAlias) (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(pCond) (5)
{
    if (!pCond)
        return this;
    if (this._sqlStorage)
        this._sqlStorage += " and ";
    this._sqlStorage += pCond;
    return this;
}

3.3. private functions

Private functions would be possible but make everything much more complicate. So just start your functions / methods name with a _ if you need private methods.

-→ do not use functions which start with a _ outside of the class!

Add @ignore to the comment of the private functions.

4. JS-Doc

1	JS-Doc comment: http://usejsdoc.org/
2	jsdoc-blocks have to start with /** because the tool to generate docs out of jsdoc only works with /**
3	use the correct form for optional/required parameters: http://usejsdoc.org/tags-param.html Optional parameter: [alias=the current alias] Required parameter: alias Classes: @class

/**
 * Description...
 * ...
 *
 * @param {String} [pAlias=the current alias] the database alias where the condition shall be executed later (important for column types of preparedStatements)
 * @example Here is an example
 * @class
 */
function SqlCondition(pAlias)
{
...
}

1	examples are useful on more complex functions
2	constructor function; init properties (do not set functions ("methods") here!)
3	add functions ("methods") to the prototype, they are available through the prototype chain
4	the comments have to start with /** not /* otherwise JSDoc cannot generate a documentation

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) See also HowToSqlConditionLib.adoc for a full documentation.

import("system.vars");
import("system.result");
import("Sql_lib");
import("Comm_lib");

var cond = new SqlCondition();

var mediumIds = CommExtensions.getContextualMediumIds();
if (mediumIds.length > 0)
    cond.and("COMM.MEDIUM_ID in (" + mediumIds.join(", ") + ")");

var idVal = vars.get("$local.idvalue");
if (uids.length > 0)
    cond.and("COMM.COMMID = '" + idVal + "' ");

result.string(cond.toString("COMM.OPTIONAL = 't'"));