Differences

This shows you the differences between two versions of the page.

Link to this comparison view

dglux_v2_wiki:dgscript [2018/08/31 18:50]
dglux_v2_wiki:dgscript [2019/07/18 18:12] (current)
Line 1: Line 1:
 +{{indexmenu_n>​98}} ​
 +====== DGScript ======
 +
 +===== Introduction =====
 +In addition to visual programming blocks, DGLux also provides the ability to write custom script that interacts with the client-side environment. DGSript is utilized in several areas of the application.
 +
 +The “DGScript” Non-Visual Component provides the ability to define custom “Dynamic Properties” that get passed in as variables that are accessible by name from the script property.
 +
 +//​Examples://​
 +
 +<code actionscript3>​
 +//Simple Equality
 +
 +if (property1 >= property2)
 +{
 + output = “Greater”;​
 +}
 +else
 +{
 + output = “Less”;
 +}
 +</​code>​
 +
 +<code actionscript3>​
 +//​Concatenate all “Dynamic Properties” of a DGScript block
 +
 +var dProperties = parent.parent.dynamicProperties;​
 +var tStr = "";​
 +
 +for (var i=1; i < dProperties.length;​ i++)
 + //output property is first so we want to skip it
 +{
 + var name = dProperties[i].name;​
 + var value = dProperties[i].value;​
 +
 + tStr += value;
 +}
 +
 +output = tStr;
 +</​code>​
 +
 +<code actionscript3>​
 +//Table Property Operations
 +
 +getTableRows(name:​String,​ sheetId:​int,​ makecopy:​Boolean = true):Array
 +getTableColumns(name:​String,​ sheetId:​int):​Array
 +setTableColumns(name:​String,​sheetId:​int,​ arrayofStrings:​Array):​Boolean
 +setTableRows(name:​String,​ sheetId:​int,​ arrayOfObjects:​Array):​Boolean
 +</​code>​
 +
 +The “Table” data type supports a formula column that contains a script. All columns in the current sheet are accessible by name in the script.
 +
 +//​Examples://​
 +
 +<code actionscript3>​
 +(columnA + columnB) / 2;
 +</​code>​
 +
 +<code actionscript3>​
 +if (columnA >= columnB)
 +{
 + return true;
 +}
 +else
 +{
 + return false;
 +}
 +</​code>​
 +
 +<code actionscript3>​
 +if (row == 0) //Execute only once
 +{
 + var runningTotal = 0;
 + for (var i=0; i < rows.length;​ i++) //rows is an Array of all rows in the sheet
 + {
 + runningTotal += rows[i].columnA;​
 + }
 + return (runningTotal / rows.length);​
 +}
 +else
 +{
 + return null;
 +}
 +</​code>​
 +
 +<code actionscript3>​
 +formatDate(string2Date(ts),​ "​D-MMM-YYYY L:NN A")
 +</​code>​
 +
 +===== The Language =====
 +
 +The language supported by DGScript is essentially full AS3 with some minor differences. Its major features are listed here. This chapter explains the language features in detail. A full AS3 reference is available from Adobe at: 
 +[[http://​help.adobe.com/​en_US/​FlashPlatform/​reference/​actionscript/​3/​package-detail.html]]
 +
 +===== Supported Functionality =====
 +
 +DGScript supports a powerful language, which is essentially a full actionscript3Script with some minor differences. The following list shows its major features:
 +  - Supports all the operators and flow control statements of actionscript3Script/​AS3.
 +  - Supports all E4X operators and operations.
 +  - Supports user function declaration.
 +  - Supports the syntax of AS3-style type declarations for var and function return values and parameters. Type, however, is simply discarded.
 +  - Supports import statement to import AS3 classes so that they can be used to new instances or call its static methods.
 +  - All Flash top-level functions are available to dynamic code, and a number of built-in functions, including printf(),​importFunction() and importStaticMethods().
 +  - Provides comprehensive interaction with the hosting AS3 environment,​ with support at both the language and the API levels.
 +  - Does not support actionscript3Script object-orientation afterthoughts such as prototype and actionscript3Script-style object constructors. In other words, the language does not support defining classes in any way. Object usage, i.e., the dot-notation,​ is supported.
 +  - Extended keyword support of and, or, not, xor, nand, and nor, useful for taking end-user input with more English-like logical expressions.
 +
 +===== Variables =====
 +
 +Variables do not have to be declared with var before use. All variables are dynamically typed; you can specify a type for a variable in var but that type is ignored.
 +
 +===== Expressions =====
 +
 +All AS3 expressions are supported, including literals and E4X expressions.
 +Literal syntax includes null, this, boolean, integer, number, string, object, array and E4X objects. This references the current object scope on which DGScript is running. The super keyword in AS3 is not supported.
 +
 +===== Extended Logical Operator Keywords =====
 +
 +In addition to actionscript3Script/​AS3 operators, the dynamic language supports these extended logical operator keywords: and, or,not, nand, nor, and xor. They are useful for taking end-user input with more English-like logical expressions:​
 +
 +<code actionscript3>​
 +var sick = false;
 +var young = true;
 +
 +if (young and not sick) premium = "​low";​
 +</​code>​
 +
 +===== Using ActionScript 3 Classes =====
 +
 +Like in AS3, a class must first be imported via the import statement before it can be used. Unlike AS3, only fully qualified class names are accepted; no wildcard characters are allowed. Also, the AS3 classes to be used by the dynamic code must be present at runtime. You can import multiple classes in a single statement.
 +Once a class is imported, it can be used just like in AS3. The class name without the package part is used; classes can be assigned to variables; you can create instances of a class, and call static methods of that class. For instance:
 +
 +<code actionscript3>​
 +import flash.display.Sprite,​ mx.utils.StringUtil;​
 +
 +var mySprite:​Sprite = new Sprite;
 +
 +printf( StringUtil.trim(' ​  ​abc ​  '​) );
 +</​code>​
 +
 +===== Statements =====
 +
 +All AS3 statements are supported in the dynamic language with a handful of exceptions. The following table lists supported statements and directives.
 +
 +^ ActionScript 3 ^ DGScript ^ Comment ^
 +| break | break | Same as AS3 |
 +| case | case | Same as AS3 |
 +| continue | continue | Same as AS3 |
 +| default | default | Same as AS3 |
 +| do..while | do..while | Same as AS3 |
 +| else | else | Same as AS3 |
 +| for | for | Same as AS3 |
 +| for..in | for..in | Same as AS3 |
 +| for each..in | for each..in | Same as AS3 except that, when var is used to declare the variable, type is not allowed; this is different from the rest of the language. |
 +| if | if | Same as AS3 |
 +| return | return | Same as AS3 |
 +| switch | switch | Same as AS3 and actionscript3Script;​ the case values can be any expressions and are not necessarily constants. |
 +| throw | throw | Same as AS3 |
 +| try..catch..finally |  | Not supported. |
 +| while | while | Same as AS3 |
 +| with |  | Not supported. |
 +| default xml namespace | default xml namespace | Same as AS3 |
 +| import | import | Supported to import AS3 classes that are avaiable at the time of running. |
 +| include |  | Not supported. |
 +| use namespace |  | Not supported. |
 +
 +===== User-Defined Functions =====
 +
 +Functions can be defined dynamically,​ too. The syntax is exactly the same as in AS3, but the type information for parameters and return type is simply discarded. But notice! These functions are not the same as AS3 functions! Therefore, they can not be returned to the calling AS3 code nor be passed as parameters to imported AS3 functions (see below). User-defined functions can be assigned to variables or passed as parameters to other user-defined functions, like so:
 +
 +<code actionscript3>​
 +function inc(x) {
 +  return x+1
 +}
 +function dec(x) {
 +  return x-1
 +}
 +function delegate(x:​int,​ f:​Function):​int {
 +  return f(x)
 +}
 +
 +delegate(5, dec)
 +</​code>​
 +
 +===== Using AS3 Top-Level Classes and Functions =====
 +
 +Flash top-level classes and functions can be used exactly like in AS3. For example:
 +
 +<code actionscript3>​
 +var date = new Date(1987, 3, 5);
 +
 +var value = escape('​cond=age<​50 and age>​30'​);​
 +
 +var num = Number('​1234'​);​
 +
 +trace('​TRACE from dynamic code.'​);​
 +</​code>​
 +
 +===== Built-in Functions =====
 +
 +The dynamic language includes a few built-in functions.
 +
 +<code actionscript3>​
 +function printf(msg_fmt,​ ...):void
 +</​code>​
 +
 +This function prints the message to the system'​s output display. The first parameter can be a string containing parameter indicators like {0}, {1}, etc.; they are replaced by values of the following parameters.
 +
 +<code actionscript3>​
 +function importFunction(name,​ theFunction):​void
 +</​code>​
 +
 +This function imports a function, typically a class static method, to be globally invokable. For instance:
 +
 +<code actionscript3>​
 +import mx.utils.StringUtil;​
 +importFunction('​trim',​ StringUtil.trim);​
 +
 +printf( trim(' ​   abc    ') ); // call the imported function
 +</​code>​
 +
 +<code actionscript3>​
 +function importStaticMethods(cls,​ criteria:​*=null):​void
 +</​code>​
 +This function imports all the static methods of cls, a class object, that match the criteria. If criteria is null, all static methods are returned; otherwise, the criteria can be either a RegExp object or an array of strings. For instance:
 +
 +<code actionscript3>​
 +importStaticMethod(Math,​ [ '​sin',​ '​cos'​ ]);
 +
 +printf( sin(0.12) ); // call the imported function
 +</​code>​