[incubator-hop] branch master updated: HOP-3218 updated javascript transform doc page

[ha...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hansva pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-hop.git


The following commit(s) were added to refs/heads/master by this push:
     new aed57ff  HOP-3218 updated javascript transform doc page
     new b0a5c59  Merge pull request #1224 from bamaer/HOP-3218
aed57ff is described below

commit aed57ffad01dba968e179c97783e06f943c804a3
Author: Bart Maertens <ba...@know.bi>
AuthorDate: Wed Dec 15 20:54:33 2021 +0100

    HOP-3218 updated javascript transform doc page
---
 .../assets/images/transforms/javascript-dialog.png | Bin 0 -> 71279 bytes
 .../images/transforms/javascript-functions.png     | Bin 0 -> 53892 bytes
 .../transforms/javascript-script-right-click.png   | Bin 0 -> 34679 bytes
 .../ROOT/pages/pipeline/transforms/javascript.adoc | 164 ++++++++++++++++++---
 4 files changed, 146 insertions(+), 18 deletions(-)

diff --git a/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-dialog.png b/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-dialog.png
new file mode 100644
index 0000000..d8a10c4
Binary files /dev/null and b/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-dialog.png differ
diff --git a/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-functions.png b/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-functions.png
new file mode 100644
index 0000000..97f1ed5
Binary files /dev/null and b/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-functions.png differ
diff --git a/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-script-right-click.png b/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-script-right-click.png
new file mode 100644
index 0000000..0b39fcc
Binary files /dev/null and b/docs/hop-user-manual/modules/ROOT/assets/images/transforms/javascript-script-right-click.png differ
diff --git a/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/javascript.adoc b/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/javascript.adoc
index 3f0d153..6b31d32 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/javascript.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/javascript.adoc
@@ -17,29 +17,157 @@ under the License.
 :documentationPath: /pipeline/transforms/
 :language: en_US
 :description: The JavaScript transform allows you to create JavaScript scripts that use the available pipeline fields as variables.
+:imagesdir: ../../../assets/images
 
 = JavaScript
 
 == Description
 
-The JavaScript transform allows you to create JavaScript scripts that use the available pipeline fields as variables.
+The JavaScript transform provides a user interface for building JavaScript expressions that you can use to modify your data. The code you type in the script area is executed once for each input row.
 
-== Options
+The transform allows multiple scripts in a single transform instance.
 
-[width="90%",options="header"]
+The Javascript transform is not an input transform and therefore requires an input stream from the pipeline.
+
+image:transforms/javascript-dialog.png[Javascript Transform Dialog, width="90%"]
+
+== Javascript functions Panel
+
+image:transforms/javascript-functions.png[Javascript Functions Panel, width="35%"]
+
+The Javascript functions panel contains a tree view of scripts, constants, functions, input fields, and output fields as described below.
+
+Double click on any of the scripts, constants, functions or fields to add them to the script.
+
+Transform Scripts::
+Scripts you have created in this transform.
+
+Transform Constants::
+A number of pre-defined, static constants that control what happens to the data rows. +
+To use these constants, you must first set a pipeline_Status variable to CONTINUE_PIPELINE at the beginning of the script, so that the variable assignment is made to the first row being processed. Otherwise, any subsequent assignments to the pipeline_Status variable are ignored. +
+The available constants are:
+
+* SKIP_PIPELINE: Excludes the current row from the output row set and continues processing on the next row.
+* ERROR_PIPELINE: Excludes the current row from the output row set, generates an error, and any remaining rows are not processed.
+* CONTINUE_PIPELINE: Includes the current row in the output row set.
+* ABORT_PIPELINE: Excludes the current row from the output row set, and any remaining rows are not processed, but does not generate an error. (This constant does not display in the transform dialog, but can be used in your script)
+
+Transform Functions::
+String, numeric, date, logic, special, and file functions you can use in scripts. These included functions are implemented in Java and execute faster than JavaScript functions. Each function has a sample script demonstrating its use. Double-click the function to add it to the Javascript pane. Right-click and choose Sample to add the sample to the Javascript pane.
+
+Input Fields::
+Input fields for the transform.
+
+Output Fields::
+Output fields for the transform.
+
+
+== Javascript Panel
+
+The Javascript pane is the editing area for writing your code. You can insert constants, functions, input fields, and output fields from the Javascript functions panel on the left by double-clicking the node you want to insert or by using drag-and-drop to place the object onto the Javascript panel.
+
+The position at the bottom of the Javascript panel displays the line number and position of the cursor.
+
+The `Optimization level` selects the level of JavaScript optimization. The values are:
+
+* 1: JavaScript runs in interpreted mode.
+* 0: No optimizations are performed.
+* 1-9: All optimizations are performed. 9 performs the most optimization with faster script execution, but compiles slower. The default is 9.
+
+
+== Script types
+
+image:transforms/javascript-script-right-click.png[Javascript transform right click menu, width="35%"]
+
+You can right-click a tab in the Javascript panel to open a context menu with the following commands:
+
+* **Add new** – Add a new script tab.
+* **Add copy** – Add a copy of the existing script in a new tab.
+* **Set Transform Script** - Specify the script to execute for each incoming row. Only one tab can be set as a transform script. The first tab is a transform script by default.
+* **Set Start Script** - Specify the script to execute before processing the first row.
+* **Set End Script** – Specify the script to execute after the last row has been processed.
+* **Remove Script Type** - Specify to not execute the script. The script tab is not removed. To remove a script tab, click the Close button (the red “X”) and choose Yes to delete the script tab.
+
+The icon for the script type displays on the tab to denote the type of script on the tab. To rename a script tab, right-click the tab name in the Transform Scripts section of the Javascript functions panel, choose Rename, and enter the new name.
+
+== Fields table
+
+The Fields table contains a list of variables from your script, and enables you to add metadata to the fields, like descriptive names.
+
+[%header, width="90%"]
+|===
+|Field|Description
+|Fieldname|Specify the name of the incoming field.
+|Rename to|Specify a new name for the incoming field.
+|Type|Specify a data type for the output field.
+|Length|Specify the length of the output field.
+|Precision|Specify the precision value of the output field.
+|Replace value ‘Fieldname’ or ‘Rename to’|Specify whether to replace the value of the selected field with another value or to rename a field. The values are Y (Yes) and N (No).
+|Get variables|Retrieve a list of Javascript variables from your script.
+|Test Script|Test the syntax of your script, and displays the Generate Rows dialog box with a set of rows for testing.
 |===
-|Option|Description
-|Transform name|Name of the transform this name has to be unique in a single pipeline.
-|Scripts|Displays a list of scripts you have created in this transform.
-|Constants|A list of pre-defined, static constants.
-|Functions|Contains a variety of String, Numeric, Date, Logic and specialized functions you can use to create your script.
-To add a function to your script, simply double-click on the function or drag it to the location in your script that you wish to insert it.
-|Input Fields|A list of inputs coming into the transform.
-Double-click or use drag and drop to insert the field into your script.
-|Output Fields|A list of outputs for the transform.
-|Java Script|This section is where you edit the script for this transform.
-You can insert functions, constants, input fields, etc. from the tree control on the left by double-clicking on the node you wish to insert or by dragging the object onto the Java Script panel.
-|Fields|The Fields table contains a list of variables from your script including the ability to add metadata like a descriptive name.
-|Get Variables|Retrieves a list of variables from your script.
-|Test script|Use this button to test the syntax of your script.
-|===
\ No newline at end of file
+
+== Javascript Internal API Objects
+
+You can use the following internal API objects (for reference see the classes in the source):
+
+* **_PipelineName_**: A String holding the pipeline name
+* **_transform_**: the actual transforms instance for this transform (org.apache.hop.pipeline.transforms.javascript.ScriptValues)
+* **rowMeta**: The actual instance of org.apache.hop.core.row.IRowMeta
+* **row**: The actual instance of the data Object[]
+
+== Examples
+
+=== Check for the Existence of Fields in a row:
+
+[source, javascript]
+----
+var idx = getInputRowMeta().indexOfValue("lookup");
+if ( idx < 0 )
+{
+   var lookupValue = 0;
+}
+else
+{
+   var lookupValue = row[idx];
+}
+----
+
+=== Add a New Field in a Row
+
+Fields must be added to the rows in the same order to keep the structure of the row coherent.
+
+To add a field, define it as var in the Javascript pane, and add it as a field in the Fields table.
+
+=== Numeric values
+
+Most values that are assigned in JavaScript are floating point values by default, even if you think you have assigned an integer value. If you are having trouble using == or switch/case on values that you know are integers, use the following constructs:
+
+[source, javascript]
+----
+switch(parseInt(valuename))
+{
+case 1:
+case 2:
+case 3:
+ strvalueswitch = "one, two, three";
+ break;
+case 4:
+ strvalueswitch = "four";
+ break;
+default:
+ strvalueswitch = "five";
+}
+----
+
+=== Filter Rows
+
+To filter rows (remove the rows from the output for example) set the pipeline_Status variable as follows:
+
+[source,javascript]
+----
+pipeline_Status = CONTINUE_PIPELINE
+if (/* your condition here */) pipeline_Status = SKIP_PIPELINE
+----
+
+All rows matching the specified condition are removed from the output.
\ No newline at end of file