Functions

Framework control functions defined in Description.json must be defined and implemented in Source.js. 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 for Source.js:

/**
* @description This is the call of the api function 'customFunction'.
* @returns {void}
*/
FrameworkControlJs1.prototype.customFunction = function () {
   /**
   * 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 return value is defined in Description.json under "type".

"type": "tchmi:general#/definitions/Boolean"

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

/**
* @description This is the call of the api function 'customFunction'.
* @returns {Boolean}
*/
FrameworkControlJs1.prototype.customFunction = function () {
   /**
   * 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
   return true;
};

Function with parameter values

A function with 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 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 Source.js like a normal function. The parameter values are passed with the function call. The parameters must be checked for validity before they are used, similar to the attribute setters.

/**
* @description This is the call of the api function 'customFunction'.
* @returns {void}
*/
FrameworkControlJs1.prototype.customFunction = function (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 enginnering in the twincat
   */
   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
};