Functions

Framework control functions defined in Description.json must be defined and implemented in Control.js/ts. The function must be named like the "name" of the function in Description.json.

Function without parameter values

A function without parameter values is defined in Description.json as follows:

"functions": [
   {
      "name": "customFunction",
      "displayName": "customFunction",
      "visible": true,
      "description": "This is a sample for a function that can be called.",
      "category": "Actions",
      "params": [],
      "type": null,
      "heritable": true,
      "searchTerms": []
   }
]

This results in the following code:

TypeScript:

/**
* @description This is the call of the api function 'customFunction'.
*/
public customFunction(): void {
   /**
   * customFunction is defined in the description.json and called from outside.
   * The api functions are shown in the graphical user interface of the engineering in Visual Studio
   */

   // implement function logic here
}

JavaScript:

/**
* @description This is the call of the api function 'customFunction'.
* @returns {void}
*/
customFunction() {
   /**
   * customFunction is defined in the description.json and called from outside.
   * The api functions are shown in the graphical user interface of the engineering in Visual Studio
   */

   // implement function logic here
}

Within the function, any execution logic of the function can be implemented.

Function with return value

The functions enables a return value to be returned the calling point in Engineering. The data type of the return value is defined in Description.json under "type".

"functions": [
   {
      "name": "customFunction2",
      "displayName": "customFunction2",
      "visible": true,
      "description": "This is a sample for a function that can be called by the engineering.",
      "category": "Actions",
      "params": [ ],
      "type": "tchmi:general#/definitions/Boolean",
      "heritable": false,
      "searchterms": []
   }
]

Within the function in Control.js/ts it is then possible to return a value of the corresponding type.

TypeScript:

/**
* @description This is the call of the api function 'customFunction2'.
*/
public customFunction2 (): boolean {
   /**
   * customFunction is defined in the description.json and called from outside.
   * The api functions are shown in the graphical user interface of the enginnering in the twincat
   */

   // implement function logic here
   return true;
}

JavaScript:

/**
* @description This is the call of the api function 'customFunction2'.
* @returns {Boolean}
*/
customFunction2 () {
   /**
   * customFunction is defined in the description.json and called from outside.
   * The api functions are shown in the graphical user interface of the enginnering in the twincat
   */

   // implement function logic here
   return true;
}

Function with parameter values

A function with parameter values is defined in Description.json as follows:

"functions": [
   {
      "name": "customFunction3",
      "displayName": "customFunction3",
      "visible": true,
      "description": "This is a sample for a function that can be called by the engineering.",
      "category": "Actions",
      "params": [
         {
            "name": "functionParameter1",
            "displayName": "functionParameter1",
            "description": "This is a sample for a function parameter.",
            "type": "tchmi:general#/definitions/Number",
            "visible": true
         },
         {
            "name": "functionParameter2",
            "displayName": "functionParameter2",
            "description": "This is a sample for a function parameter.",
            "type": "tchmi:general#/definitions/Boolean",
            "visible": true
         }
      ],
      "type": null,
      "heritable": false,
      "searchterms": []
   }
]

The function is implemented in Control.js/ts like a normal function. The parameter values are transferred with the function call. The parameters must be checked for validity before they are used, similar to the attribute setters.

TypeScript:

/**
* @description This is the call of the api function 'customFunction3'. 
*/
public customFunction3(functionParameter1: number, functionParameter2: boolean): void {
   /**
   * customFunction is defined in the description.json and called from outside.
   * The api functions are shown in the graphical user interface of the enginnering in the twincat
   */
   let convertedParameter1 = TcHmi.ValueConverter.toNumber(functionParameter1);
   if (convertedParameter1 === null) {
      // parameter is null: define what to do in this case

      // exit function call if the execution without this parameter is not possible
      return;
   }

   let convertedParameter2 = TcHmi.ValueConverter.toBoolean(functionParameter2);
   if (convertedParameter2 === null) {
      // parameter is null: define what to do in this case

      // exit function call if the execution without this parameter is not possible
      return;
   }

   // implement function logic with the evaluation of the parameters here
}

JavaScript:

/**
* @description This is the call of the api function 'customFunction3'.
* @param {number} functionParameter1
* @param {boolean} functionParameter2
* @returns {void}
*/
customFunction3(functionParameter1, functionParameter2) {
   /**
   * customFunction is defined in the description.json and called from outside.
   * The api functions are shown in the graphical user interface of the engineering in Visual Studio
   */
   var convertedParameter1 = TcHmi.ValueConverter.toNumber(functionParameter1);
   if (convertedParameter1 === null) {
      // parameter is null: define what to do in this case

      // exit function call if the execution without this parameter is not possible
      return;
   }

   var convertedParameter2 = TcHmi.ValueConverter.toBoolean(functionParameter2);
   if (convertedParameter2 === null) {
      // parameter is null: define what to do in this case

      // exit function call if the execution without this parameter is not possible
      return;
   }

   // implement function logic with the evaluation of the parameters here
}