Wasabi plugin API

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 (described 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: You can use nested Javascript object instead of JSON for less stringent formatting rules.

 

Used terms:

  • program – command-line executable
  • 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
  • tracked name – name of an option in JSON (set with name or option attribute)
  • 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 executable file to be launched from its Wasabi plugins folder (or alternatively from global path).
  • “options”: array
    Array can contain strings (displayed as is) and option objects (described in the next section).

Optional attributes:

  • “group” – options are displayed in bordered, collapsible area below the label.
    Can be accompanied with one of these optional attributes:

    • “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).
  • “group” / “section” / “line” / “select”: string
    String is a label displayed above or next to the set of grouped option elements.
  • “desc”: string
    Description of the program. Displayed on top of the Wasabi interface window.
    HTML is allowed (web addresses are automatically parsed to HTML links).
  • “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 the plugin folder). Example: “images/icon.jpg”
      It’s good to provide an array with both SVG (for the menu) and JPG/PNG image (for the window title).
  • “outfile”: string / object / array
    Specifies full or partial name of expected main output file. Use array of strings for alternative considerations.
    This attribute tells Wasabi which file to use for the “Open” button in analysis library.
    Use objects for conditional output naming (see “default” attribute below).
    Tip: Prorgam’s console output is captured to a file named output.log
  • “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, with spaces converted to underscore)
  • “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 labeling (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.

JSON objects in the “options” array can use these {attribute: value} pairs:


 

  • “type”: “bool” / “tickbox” / “checkbox” / “int” / “float” / “number” / “text” (default) / “string” / “file” / “hidden” / “select” / “output”
    Type of the program option.
    Valid option types:

    • “file” – for input filedata.
      Additional attributes:

      • “source”: “current sequence” (default) / “current tree” / “current data” / “filedrop” / “fileselect” / “import” / “filedrop fileselect” / “filedrop import”
        File data source. Could be currently open dataset or external data added by user (using file drag-drop area and/or a button for either data import or file browsing).
        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 by Wasabi 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: “output”: “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).
    Inclusion of flag prefix overrides “prefix” attribute. Set to empty string (“”) for positional options.
    Note: options are passed to the program in the order of appearance in JSON.
  • “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”)
  • “check”: string / object
    Check the option value. Displays a message (string) when the input element is empty.
    A rule object can be used ({“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.
  • “required”: string / object
    The option needs to have a value. Works as “check” attribute, except 1) displays the error message only after the “submit” button is clicked, and 2) prevents plugin launch as long as the error is unresolved.
  • “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: result1}, {condition2: result2}, …]
    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 \”tracked_name_as_string\”” : “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 “enable” 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 with the value of this option (this_option_name) before passing 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)
    Note: 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 )”