Wasabi plugin API reference. ================================= The Wasabi plugin API allows to describe command-line tool options and corresponding Wasabi interface in JSON-format. Each option is specified with an object containing one or more attributes (see below). * Valid values in JSON are: boolean (true/false), string ("somevalue") or  number (0.01), nested in {object} or [array]. * The interface elements are generated in the same order as their objects in JSON. Tip: Native Javascript data object can be used in place of JSON for less stringent formatting. Used terms: * program - command-line executable file * options - 1) additional parameters added to the program launch command 2) descriptions of program parameters in the plugin JSON file * attributes - JSON-formatted text fields for describing program options * input - HTML input element (a textbox, checkbox or selection menu) in the generated plugin interface in Wasabi * string/boolean/array/object - valid (Javascript) value types for attributes Recognised attributes in JSON objects. =========================================== * "program": string Name of the binary that is launched in Wasabi plugins folder. * "options": array List of option objects (see below). Optional attributes: * "group" / "section" / "line" / "select": string String is a label displayed above or next to the set of grouped option elements. *"group" - options are displayed in bordered, collapsible area below the label. Additional attribute: * "collapsed": boolean - whether area is initially collapsed (default: true). *"section" - options are displayed below the label. *"line" - listed options are displayed in one line (wrapped if necessary). *"select" - same as {"type": "select", "title": string} (see "type" attribute below). * "desc": string Description of the program. Displayed on top of the Wasabi interface window. HTML is allowed (web links are parsed to HTML automatically). * "menudesc": string Short description of the program. Displayed as tooltip in the Wasabi tools menu (on mouseover). * "name": string Name of the program. Displayed in tools menu and window title. * "icon": string / array Icon of the program. Displayed in tools menu and window title. Recommended size: 25*25px. String can be: SVG path. Example: "M 11.193359 0.55078125 z" Image data URI: Example: "data:image/gif;base64,R0lGODlhEA..." Path to image file in Wasabi plugins folder. Example: "images/icon.jpg" If possible, provide an array with both SVG (for menu) and jpg/png image (for window). * "outfile": string / object / array Specifies full or partial name of expected main output file. Use array of strings for alternative considerations. Use objects for conditional output naming (see "default" attribute below). * "translate_names": boolean If set to "true", all sequence names in input file(s) are converted to simple IDs ("seq1","seq2",...), which are translated back to the original names when output is opened in Wasabi. Default: false (input file(s) retain names (spaces converted to "_")) * "libraryname": string Default name for the stored results in the analysis library (default: "my analysis"). * "submit": string / object / array String is a label displayed on the submit button in Wasabi interface (default: "Send job"). Use (array of) objects for conditional labelling (see "default" attribute below). * "prefix": string Specifies leading character(s) for each option name in the command line (default: "-"). Can also be set per option/option group. ================================================== Option-defining JSON objects in the "options" array recognize following {attribute: value} pairs: * "type": "bool" / "tickbox" / "checkbox" / "int" / "float" / "number" / "text" (default) / "string" / "file" / "hidden" / "select" / "output" Type of option/form element and its allowed value. If type is not specified for an option/input element, "text" is used. Valid option types: * "file" - defines input filedata. Additional attributes: * "source": "current sequence" (default) / "current tree" / "current data" / "filedrop" / "import" / "filedrop import" File data source. Either currently open dataset or external data added by user (using filedrop or import button). Tip: "type":"file" and "source" can be combined. Example: "file" : "filedrop" Tip: use "title" property to add custom text to the filedrop area Tip: use "desc" property to add custom text next to file/data that user had added * "fileformat": "fasta" (default for sequence) / "newick" (default for tree)/ "extended newick" / "phyloxml" / "hsaml" / "phylip" / "nexus" / "original" File will be converted to specified format before feeding to the program. Use "original" to skip file conversion. Tip: Use multiple or compound file formats if both tree and sequence data is accepted. * "output" - specifies output directory. This option receives the filepath of the assigned library folder in the server. If no "output" option is used, the program is expected to write output files to the current working directory. Custom strings can be appended to the filepath with "default" attribute. Tip: "output" and "default" can be combined. Example: "outfile": "myCustomString" * "hidden" - automatically added option. Use "default" attribute to set a value. Tip: For type "hidden", you can combine the "type" and "default" attributes. Example: "hidden": "myvalue" * "select" - list of options or values for an option/element where only one can be selected. Additional attributes: * "options": array List of values (strings or objects) to choose from. Valid attributes for objects: * "title": string. Text to be displayed in the list (compulsory). Tip: {"title": "somestring"} can be written as "somestring". * "option": string. Command-line parameter (boolean option) to be enabled when selected. Tip: "title" can be omitted if "option" is specified * "value": string / "no value". String is the value that the program option gets when this selection option is selected. "no value" assigns an empty value (""). When "value" attribute is omitted, "title" is used instead. * "desc": string. Additional text to be displayed (above the selection) when this value is selected. * "default": true / "yes". Specifies initial selection. * "extendable": true / "yes" / "configurations" User can add options to the list. "configurations" uses current configuration (values of all options) as value for the list addition. * "bool" / "tickbox" / "checkbox" / "switch" - Tickbox element. Boolean value that adds/removes the option from command line. * "text" / "string" - Text input box. Text input is assigned to an option (see "option" attribute) and/or tracked name ("name" attribute). * "number" / "int" / "float" - Same as "text", but accepts only numerical input. "int" restricts input to whole numbers. * "title": string Text to be displayed next to form input element. Tip: "type" and "title" can be combined (exception: types "file" and "hidden"). Example: "checkbox": "tick this option" * "desc": string Tooltip text, displayed when hovering the title (or form element when title is missing). * "option": string Specifies command-line option flag name. Also sets a reference name for its value tracking (unless "name" is set). Omit for positional options. * "name": string Enables option value tracking. String is unique reference name that can be used by other options (see e.g. "enable" and "default" attributes). Overrides the "option" attribute as reference name for tracking. Note: Avoid choosing predefined API names/values for the trackable name: "DNA","RNA","codons","protein","sequence","tree" * "enable" / "disable": boolean / string / object / array Display/remove a particular input element or group of elements (and associated options). String or object (or array of these) define rules for conditional enabling/disabling. Rule can contain name(s) of tracked options/elements and custom logic (see "default" attribute). Examples: "enable":"option_name is not ticked", "disable":{"option_name is equal to some_value":"yes"}. Special tracked values (see "default" attribute) can be used to check for data currently imported in Wasabi: "enable":"no tree" Multiple conditional values can be defined with objects and alternative condition objects can be joined into an array (see "default" attribute). Note: Tracked names with spaces need escaped quotes to add logic. Examples: {"enable":"\'my option\'==true"} (same as "enable":"my option") * "required": string / object Option requires a value. String is a message to be displayed when value left undefined. Object is {"rule" : string}, where "rule" is a logic expression (see "default" attribute) to check the input element value against and string is corresponding error message to be displayed. * "default": value / object / array Initial default value for an option. Can be overriden by user input, unless input element is disabled with "fixed", "disabled" or "hidden" attribute. The default value can change according to the value of some other tracked option, defined as object: "default": { condition: resulting_default_value } Multiple alternative condition>default_value objects can be listed in array: [{condition1:result},{condition2:result},...] Valid conditions (object attributes): * "tree" / "sequence": result_value Resulting (here, the default) value depends on the type of data currently open in Wasabi. Tip: type of imported sequence can be checked with keywords "DNA"/"RNA"/"codons"/"protein" Example: { "sequence and no tree": "ticked" } or { "sequence is DNA": 0.5 } Tip: Keywords "tree"/"sequence" can also be used to check the content of file from a file input element. Example: { "name_of_file_input contains \'sequence\'": "\'result value\'"} Note: For file input, keywords "tree"/"sequence" need to be quote-wrapped to differentiate from predefined names for imported data (see Note below). * condition_string: result_value / object - default value depends on value of another tracked option. condition_string is a rule that can contain name(s) of tracked options/elements and custom javascript logic and/or keywords: "is"/"equals", "contains", "not"/"is not", "and", "or", "ticked"/"selected"/"on"/"enable", "no"/"off"/"disable"/"invert". Examples: "name_of_some_option is not ticked" : "disable", "option_name is selected": "invert", "option_name > other_option_name and no tree": "somevalue" Objects can be used to define multiple conditions on the same tracked option. Example: "option_name": {"option_value1": result, "not option_value2": result2} (same as [ {"option_name is option_value1": result}, {"option_name is not option_value2": result2} ] ) Note: To use tracked names with spaces, or to differentiate between tracked name and identical literal string, wrapping in escaped quotes (\') is required. Example: { "\'tracked name with spaces\' equals \'other_tracked_name\'" : "Use this unquoted text with spaces but without trackable names/keywords" }. Note: For text inputs, it is assumed that the default value does not need to be added to the program command line parameters, and is shown just for information when user has not inserted its own value. If it's not the case, make the program option compulsory with the "required" attribute. * "fixed": "yes" / true / string / object / array Input element cannot be changed by user. String or object (or array of these) define rules for conditional fixing (see "enabled" attribute). If input element is disabled by "fixed", the default value (see "default" attribute) overrides input value from user. * "format": "invert" / expression_string / object Do some postprocessing of the value of this option (use: this_option_name) before it is passed to the program. "invert" is same as "invert this_option_name" (only useful for boolean type options). expression_string is a fixed value or javascript code for formatting. Example: "this_option_name + \' concatenated text\'". Objects can be used for conditional formatting (see "default" attribute). Example: { "this_option_name is less than 0": "Math.abs( this_option_name )" } Note: the type of the variable this_option_name is defined by "type" attribute (string/bool/number) Note2: in javascript expression, use spaces around option_name, \'quoted text\' and other tokens * "line": bool Options marked with "line" property are displayed in one line (alternative to grouping with "line") * "prefix": string Option-specific command-line prefix (see "prefix" in first section). Tip: Javascript console can be used for debugging. Example: "console.log( some_option_name )"