Differences

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

--- custom_proc:custom_processors [2020/04/15 06:39] – emcodem
+++ custom_proc:custom_processors [2023/10/25 15:42] (current) – [Plugin Development] emcodem
@@ Line 1: / Line 1: @@
 ====== Plugin Processor development ======
-Since Version 1.0, FFAStrans supports adding processors as a plugin. This allows anybody (who is able to) to create his own processors or to download existing processors that other users created.
+Since Version 1.0, FFAStrans supports adding processors as a plugin. This allows everyone (who is able to) to create his own processors or to download existing processors that other users created.
 Download an example processor to start with here: {{ :custom_proc:custom_node_example.zip |}} and extract it to \FFAStrans\Processors\plugin_nodes\custom_nodes - then restart the workflow editor and find the example node in "Others" category.
@@ Line 10: / Line 10: @@
 So the folder \Processors\plugin_nodes\custom_nodes can only contain folders, not files. Each subfolder represents one plugin processor. For information about the contents of each plugin subfolder, keep on reading.
-{{:custom_proc:plugin_base_dir.png?400|}}
+{{gallery>:custom_proc:plugin_base_dir.png?400x400&800X800&lightbox}}
 In this picture, we see the plugin base directory \Processors\plugin_nodes\custom_nodes. The 2 folders represent each one custom plugin.
-{{:custom_proc:plugin.png?400|}}
+{{gallery>:custom_proc:plugin.png?400x400&800X800&lightbox}}
 In this picture we see the contents of an example plugin. The file style.css is not mandatory, it is just used by this processor's index.html. The folder /bin is mandatory, it must contain the script/executeable.
@@ Line 21: / Line 21: @@
 ==== Plugin architecture ====
-A plugin processor consists of 3 general parts:
+A plugin processor consists of these relevant parts:
   * JSON definition file (node.json in plugin root folder)
   * HTML user interface (index.html in plugin root folder)
   * Processor script/executeable (in /bin directory of a plugin, name configured in JSON definition file)
+  * HTML help file (help.html - next to index.html)
 === Loading / Lifetime ===
@@ Line 40: / Line 41: @@
         "category":"Others",
         "enabled":"1",
-        "priortiy":"1",
+        "priority":"1",
         "description":"Example node",
         "guid": "312dccee-88e1-45b1-906c-9c1234724805",
@@ Line 46: / Line 47: @@
 	"proc_script":"processor.exe",
 	"timeout_minutes": 120,
-	"gui_window_height": 400
+	"gui_window_height": 400,
+        "version":"1.1"
 }
 </code>
@@ Line 53: / Line 55: @@
   * category: display category in the workflow canvas. possible values: TODO
   * enabled: when set to 0, processor is not shown in the processor menu in workflow canvas
+  * priority: 1 is default, when set to -1, the node is not counted as a running job. Used e.g. for sleeping and waiting processes while allowing other jobs to process instead of blocking the que
   * description: tooltip of the processor icon in workflow canvas
   * ** guid: must be unique for each custom plugin**, best use a guid generator. A workflow stores the plugin based on it's guid, so the guid should not ne changed after plugin installation.
@@ Line 59: / Line 62: @@
   * timeout_minutes: a running processor will be killed by ffastrans when the timeout exceeded
   * gui_window_height: the processor gui height in the workflow canvas
+  * version: the current version of this processor. Developers need to raise this number with every release and it can and should be displayed on the index.html gui
@@ Line 67: / Line 71: @@
 Please note that it is best for starting a new processor, to use an existing processor as a template. You can start with the example processor {{ :custom_proc:custom_node_example.zip |}}. If you want to go with another language than Csharp for the processor.exe, please ask in the forum for another example or read on this guide.
-A custom processor consists of just 3 different parts:
-  - JSON definition file (see above)
-  - User Interface (index.html)
-  - Processor script (processor.exe or any other)
 === Overview of execution ===
@@ Line 80: / Line 79: @@
   - The processor may do something different, like transcoding or whatever the programmer of the processor intends it to do
   - FFastrans cheks for variables in outputs.json and stores them so the following processor can use the new variable values
+=== Help File (help.html) ===
+This is the page that opens when a user clicks the question mark bottom left in the processor.
+To copy the style of the existing help pages of other processors, you can use this example:
+<code>
+<html>
+<head>
+<style>
+html *
+{
+  font-family: Calibri;
+  font-size: 14px;
+}
+</style>
+</head>
+<body>
+This processor node will put the job instance in pause until one of the following criterias are met:<br/>
+<br/><br/>
+<b>Sleep</b>
+<br/>
+Pauses the job instance in the amount of seconds specified in the "Time" input.<br/>
+<br/>
+Wait for files
+Pauses the job instance until the file(s) in the list is present.<br/>
+<b>One can specify any number of files in the list.</b>
+</body>
+</html>
+</code>
 === User Interface (index.html) ===
 Note that the content of the HTML page itself is not anyhow predefined but you should create a look and feel to match all other existing processor GUI's. All relevant that the html page does is to save and restore a simple JSON structure containing Inputs and Outputs which will be passed to a processor.exe at execution time.
-This is used to create the User interface of the processor in the workflow editor ONLY, it is not involved in the actual execution of the processor in a running job. You can create a custom web page that accepts inputs from the user. The input names and values of the saved processor instance in your workflow are passed using a temp JSON file to the processor.exe.
+This index.html is used to create the User interface of the processor in the workflow editor ONLY, it is not involved in the actual execution of the processor in a running job. You can create a custom web page that accepts inputs from the user. The input names and values of the saved processor instance in your workflow are passed using a temp JSON file to the processor.exe.
+{{gallery>:custom_proc:custom_proc.png?400x400&lightbox}}
+In the picture above, you see the area in green where your index.html is rendered using IE11. You cannot change the area outside as those buttons are created by FFAStrans host. The only thing you can influence is the display height by altering the plugin definition json.
 The example processor that you can download above contains examples how to use all possible functions and inteactions between the FFAStrans Engine and the index.html.
 When a user opens the processor GUI on the workflow editor, FFAStrans will create an Embedded Browser which is Internet Explorer 11 so always develop and test in IE 11.
+Note that on some Systems, it is needed to force the document to run in IE11 mode by having these 2 lines at the top of index.html. If you do not add this, the javascript base64 encoder and decoder atob and btoa migth not be available and your plugin might randomly not work on a recent Windows Version.
+<code>
+<!DOCTYPE html>
+<meta http-equiv="X-UA-Compatible" content="IE=11" />
+</code>
 For interacting with the embedded Browser, FFAStrans host "executes" or evaluates javascript functions with predefined names and passes Base64 encoded data as argument to the functions. See the example processor for more description. The opening procedure is like that:
@@ Line 97: / Line 139: @@
     - When user presses the save preset button, call the function ffas_save_preset() - this function must collect all data to save in a special JSON structue, see below.
-== function  ffas_load_preset ==
+== javascript function  ffas_load_preset(json_object) ==
 FFAStrans Host calls this function on page load to restore the last configuration or when the user loads a preset.
@@ Line 112: / Line 154: @@
-== function  ffas_save_preset ==
+== javascript function  ffas_save_preset() ==
 The Host calls this function when the user hits the OK button or saves the preset in the preset menu. This function is expected to collect the inputs and outputs from the html page (e.g. using document.getElementById) and create the same JSON structure as described above in the ffas_load_preset function.
 Don't forget to Base64 encode before returning the value.
+== javascript function  ffas_init(displayname) ==
+The Host calls this when the page was loaded and supplies the displayname as parameter. You can use this as a replacement for body.onload event if you like but it is not mandatory to implement this function.
+== javascript function  ffas_folder_selected(selected_folder,connected_input_id) ==
+Parameters are as usual base64 encoded.
+The Host calls this when a folder was selected. Folderbrowser can be opened using a special HTML element name, see below. You need to decode the selected_folder argument from base64 and set the value of the connected_input_id element accordingly (or do whatever else you want to do with the selected folder string)
+== javascript function  ffas_file_selected(selected_folder,connected_input_id) ==
+Same as folder_selected but for input with name "open_filebrowser".
+== Special HTML Elements ==
+In order to open dialogs that are not javascript native like a filebrowser, you have to give a HTML Element a special name, e.g. "open_vars". You do not need to supply the onclick event, FFAStrans listens automatically for all click events of all elements and checks if it knows the name of the clicked element. \\
+Additional Parameters are handed over using the HTML5 "data-" Attribute.
+Open a folderbrowser:
+<code>
+<input name="open_folderbrowser" type="submit" value="..." data-parent="path"/>
+</code>
+  * "data-parent" specifies the ID of the HTML Input box where the chosen path should go to
+  * When a Folder was Chosen, the javascript function ffas_folder_selected will be called
+Open a filebrowser:
+<code>
+<input name="open_filebrowser" type="submit" value="..." data-parent="path"/>
+</code>
+  * "data-parent" if present, specifies the ID of the HTML Input box where the "starting path" should be read from
+Open a variable selector window:
+<code>
+<input width="2px" type="submit" value="<" name="open_vars" data-parent="output_files_1" data-user_vars_only="true"/>
+</code>
+  * "data-parent" if present, specifies the ID of the HTML Input Box where the chosen value should go to.
+  * "data-user_vars_only" if present, values allowed: true or false, specifies if you want to hide all other variables than user_vars. Use this for all HTML inputs where a user should just specify a single variable (e.g. which variable should be filled with the outcome of processor.exe)
 === The processor (processor.exe) ===
@@ Line 170: / Line 254: @@
 ** Set Outputs from a processor **
 Setting outputs is optional. If you develop a processor that is not intended to deliver any output back to ffastrans, thats ok and you do not have to read on ;-)
@@ Line 187: / Line 270: @@
     * s_source
       * this can be used to override the current source file (in case the processor created a new file e.g. transcoding)
+      * **Note:** Setting s_source to an empty value causes the job to end immediately and dissapear from the job monitor. All cache files and records are deleted by ffastrans in that case.
     * s_success
       * this can be used to set a status message for the job monitoring
@@ Line 192: / Line 276: @@
       * setting this will cause the FFAStrans host to go the "error" path in the workflow or end the job with error
+Usually outputs are already part of the job json because they are passed in from the processor GUI html.
+So the processor code does not have to "generate" a new object but instead it only sets the "data" attribute of existing outputs in the existing job json.
+Take special note about the field names, "id" is optional as it is just the html id of the field on index.html GUI. FFAStrans only needs to know "value" and "data", where "value" has to be some existing variable (user var or predefined system var)
+<code>
+"proc_data": {
+    "inputs": [],
+    "outputs": [
+      {
+        "id": "",
+        "value": "s_source",
+        "data": "C:\\test\\test.ts"
+      }
+    ]
+  }
+</code>
+---------
+<html>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</html>[[custom_proc_download: Download Additional Custom Processors|To Plugin Processor Download]]
-----------------------------------------------
 <html>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</html>[[custom_proc:custom_processors|Back to top]]