Encourage script writer style

[jamoore]

For lists and map parameters, the UI has no way of knowing the type of object expected and can only populate with strings. Then the script has to convert to Int, Image_ID, Color etc. This is OK, but would be nicer if the client could know what is expected, and not leave type-checking to the client.

Standard ways for:

• Script description should be one or two lines of text. Will be displayed as a tool tip in Insight's scripts menu. Also displayed in the script dialog - where any url will be 'clickable' - so can be used for more info on what the script does etc.
• defining parameters, Human readable form e.g. thumbnailSize should probably displayed as "thumbnail Size".
• Enumeration. Human readable e.g. MAXIMUMINTENSITY.
• defining related parameters. e.g. need a list of ids either dataset or image. Better to have a parameter: id, and a parameter type with 2 values available dataset and image
• How to handle result: unify the name of the parameters and what do to with the result e.g. fileAnnotation indicates that a file annotation has been created and can possibility be annotated.
• Clear parameters to determine the target e.g. Image, Dataset, etc. So we can remove script from the display depending on the selected objects. This will only be possible if the loading of the parameters is quick enough. Should they be cached as soon as they are uploaded or installed?
• Need to handle Units e.g. scale bar size in microns
• Good practice: add the type of object expected for list or map

e.g. better to say RList<RSting>, RList<RInt> so the client can
display the correct field in the first case a text field, in the second case a text field accepting only numerical value

• It will be nice to identify the target of a script e.g. datasets. Most of the scripts will work at the images level but will be nice to know if the script works at the dataset level.

This should probably be done at the top level i.e. not need to parse the parameters to know that. NOT TOP PRIORITY

---

Suggestions:

• Parameters name and enumeration. Use "_". If we go back to our example: use Thumbnail_Size, display Thumbnail Size (client will handle the transformation). For the Enumeration, Maximum_Intensity => Maximum Intensity

Vote: Yes/No? Will?

• Results: See ​Insight 1385

[wmoore]

(In [6868]) Starting to adopt script-writing style. See #1858

[wmoore]

(In [6872]) More param updates to conform to Naming_Convention. See #1858

[jmoore]

Notes from May 6th chat (Donald, Jean-Marie, Josh, Will)

Script Style

 - unify how we handle parameters (UI on the fly)
 - "A_B" rather than "aB"
 - Using list of IObject? Yes.
 - enumerations with actions?
  -- DOWNLOAD, VIEW, ... possibly something like "CREATED" / "UPDATED"
  -- OTHER (key-value pair)
  -- VIEW: popping up image viewer in client
  -- need explanation of all of these
 - convention
  -- return rstring "status_message"
  -- possibly not enough time for UI
 - grouping
  -- scale bar (on/off, width, etc.)
  -- notifications within the UI
  -- Group param? too complicated
  -- Dot notation? How to turn them off?
  -- Summary: using dot notation for lexicographical sorting
   --- will add a service in a later version

[jmoore]

(In [6894]) see #1858 - Added grouping & namespaces to params. Improved ctors.

[jmoore]

(In [6899]) see #1858 - Refactoring group_params method

[jmoore]

(In [6905]) see #1858 - Adding Int, Double, Float omero.scripts.Types and better wrapping

[jmoore]

(In [6909]) see #1858 - Fixing Param.values parsing. May need more work

[wmoore]

(In [6912]) Updated according to guidelines. See #1858

[jmoore]

(In [6914]) see #1858 - Adding scripts.List().ofType(ImageI) support

[wmoore]

​http://trac.openmicroscopy.org.uk/omero/wiki/OmeroPy/ScriptingStyleGuide