galaxy-iuc / standards

Documentation for standards and best practices from the Galaxy IUC
http://galaxy-iuc-standards.readthedocs.io/en/latest/
6 stars 16 forks source link

Advanced options (clear conditional labels vs collapsed section) #38

Closed peterjc closed 6 years ago

peterjc commented 7 years ago

Background

http://galaxy-iuc-standards.readthedocs.io/en/latest/best_practices/tool_xml.html#dynamic-options says:

"Certain options such as “Advanced Options” should be a select box and not a boolean. A checkbox is not expected to change the content of the mask from a user point of view."

This pattern is widely used, and is currently in the planemo tutorial using seqtk_seq as an example, see https://planemo.readthedocs.io/en/latest/writing_appliance.html#conditional-parameters source https://raw.githubusercontent.com/galaxyproject/planemo/master/docs/_writing_parameters.rst

https://github.com/galaxyproject/planemo/blob/e2454efdb4e6a342522abf3732f6785098be3508/project_templates/seqtk_complete/seqtk_seq.xml#L27

        <conditional name="settings">
            <param name="advanced" type="select" label="Specify advanced parameters">
                <option value="simple" selected="true">No, use program defaults.</option>
                <option value="advanced">Yes, see full parameter list.</option>
            </param>
            <when value="simple">
            </when>
            <when value="advanced">
                ... 

Unfortunately advanced option conditionals with wording like "Show" and "Hide" (or don't show) seems common, and can cause confusion:

  1. Log into Galaxy
  2. Select a tool with advanced parameters implemented with a conditional block
  3. Show the advanced options
  4. Change an advanced option
  5. Hide the advanced options
  6. Run the tool
  7. Did your change in step (4) have any effect?

The terms show/hide would lead you to think the setting would be used, but it will NOT. In discussion with colleagues this afternoon we wondered agreed this was misleading, and thought captions using something like "Enable" and "Disable" would be better.

Question

Should the IUC best practises recommend something like "Specify advanced parameters" or "Use Additional Params" with explicit Yes/No options (as in the Planemo example)?

Or, should the best practise guidelines recommend following the example of e.g. https://github.com/bgruening/galaxytools/blob/master/tools/salmon/salmon.xml Salmon Transcript Quantification from RNA-seq data (Galaxy Version 0.7.2), and use a collapsed section:

<section name="adv" title="Additional Options">
            <param argument="--writeMappings" type="boolean" truevalue="--writeMappings" falsevalue="" checked="False"
                label="Write Mappings"
                help=" Setting this option then the quasi-mapping results will be written out in SAM-cpmpatible format. By default, output will be directed to stdout, but an alternative file name can be provided instead." />
            ...
nsoranzo commented 7 years ago

I'd vote for a collapsed section for "Additional options".

hexylena commented 7 years ago

seconding @nsoranzo's suggestion. Sections are ideal here when the only decision being done is "show vs hide" rather than some interactive decision tree.

peterjc commented 7 years ago

This is also my preference - it makes the command definition simpler as well without an if statement. When did Galaxy first support the collapsed sections though?