Mark Steps as script documentation & make available in Perform Script dialog

Idea created by mrwatson-gbs on May 22, 2017
    Active
    Score7
    • mark_scott
    • Ben
    • arnoldkegebein
    • Johan Hedman
    • jbante
    • mrwatson-gbs
    • robertnaud

    Context

     

    With the introduction of Built-in JSON Functions as a new and attractive method of passing (many &) Multiple script parameters (alongside all the other methods of named or sequential parameter passing) it has become more necessary than ever to be able to document script parameters and results and, above all, to have access to this information when calling scripts.

     

    I have suggested in a previous idea that a Method is needed to Define & Document Multiple Script Parameters & free up Script Name

     

    In the current shipping FileMaker the only method of communicating parameter requirements to the calling script (using native FM-technology) is within the script name - which is severely limited by the maximum 100 character script name.

     

    This idea thus suggests a method how this information gap could be plugged - easily & independently of coding-style, i.e. in a very FileMakery kind of way.

     

    Idea

     

    1. It should be possible to mark script steps as "script documentation" to be shown in the Perform Script dialog.
    2. In the Perform Script dialog this information should be made available - for example in a gear popup to the right of the script name
    3. It should be possible using an insert button or copy + paste to transfer the information easily to the Parameter calculation editor

     

    Here are some (possible) mock-ups of what it COULD be like (FMI would do it better though )...

     

    Script_Documentation.png

     

    The Specify Script dialog could then maybe look something like this:

     

    SpecifyScript with Script documentation.png

     

     

    Afterthought about security: Of course, the marked steps would also have to be visible to any user allowed to perform the script, no just the users allowed to edit the script.

     

    Benefits

     

    • This idea maximises support for the "code-is-documentation paradigm"
      • by allowing the developer to choose the code which is documentation
      • It thus minimises documentation effort and maximises productivity
    • It does not force developers to adopt a specific parameter-passing technique, rather...
    • This method supports all developers coding styles! For example:
      • Comment script steps can be marked / used to document script parameters
      • Set Variable steps can be marked / used to document script parameters (supporting the "code-is-documentation paradigm")
      • Exit Script steps can be highlighted to document script result parameters
      • Where parameters are conditional it is also possible to mark the If conditions, or any other code which is relevant
    • The ability to transfer the documentation to the parameter calculation will
      • avoid errors
      • minimise effort
      • maximise productivity
    • The visible juxtaposition of parameter-passing-code and parameter-receiving-code
    • Moreover, script names would be freed up, allowing them to describe script function instead of script parameters. This means

     

    Note: A small drawback of this method is that this information will not be available to external script callers (via Data Api, CWP, URLScript, …)

     

     

    Use Cases

     

    • Script Steps + Buttons + Custom menus + Script Triggers
      • Perform Script
      • Perform Script on Server
      • Plugin Call Script by name / Push to stack
      • (later) PerformScript [by Name]
    • Writing new code
    • Deploying code: Notice changed script signature when deploying code (patch or new functionality) to customised database
    • Working on 'foreign' database