Reference Module JSON

Docs Module Fields

Module JSON

• the module json describes the input and output for a wrapped executable module
• historical genapptest examples are tracked on Legacy GenAppTest Examples

current target languages

• html5
• qt3
• qt4

special note on loading filenames in text fields

• Filenames loaded in via input as text should be declared "safefile" : "true" in the field JSON.
• the acceptable pattern is currently: starts with alphanumeric then followed by alphanumeric, dot (.), underscore (_), dash (-), and forward slashes (for directory traversal within the job tree), but after every slash you must again start with an alphanumeric character. e.g. abc/.xyz is not acceptable, abc/x./y./z is.
• This will prevent attempts at wandering outside the job's directory tree
• e.g.:

                  {
                   "role"     : "input",
                   "id"       : "filetext",
                   "label"    : "filetext",
                   "type"     : "text",
                   "safefile" : "on"
                   },

target compute resource

• optional top-level attribute
  • i.e. in module.json, not under fields
• "resource" : "xyz"
• this module-specific attribute will override the global default "resourcedefault" attribute in the application configuration json
• the attribute value must be defined in "resources" as described in the application configuration json
• historical example in genapptest: data_interpolation

submit policy

• optional top-level attribute
  • i.e., in module.json, not under fields
• "submitpolicy" : "login"
  • the user must be logged in to submit this module
• "submitpolicy" : "all"
  • anyone (logged in or not) can submit this module
• this module-specific attribute will override the global default "submitpolicy" in the application configuration json
• historical example in genapptest: align

unique run directory

• optional top-level attribute
  • i.e., in module.json, not under fields
• "uniquedir" : "on"
• see more about projects and files here
• historical example in genapptest: data_interpolation

specified project - html5-only

• for the case when each run should get a specified project identifier
  • it will be assembled as a sequence of selected input field values
  • each field to be part of that sequence needs
  • "specifiedproject" : "pp"
  • this will add that field's specifiedproject and its value to assemble the project name
  • do to project naming restrictions, any non-alphanumeric character will be replaced by an underscore
  • specified projects results can be cached
  • note the project is not automatically added as a "project", to enable this add as a top-level attribute
  • "addproject" : "true"

module help

• optional top level attribute
• "help" : "help text"
• "help text" will appear over the module load button when help is on

module field help

• optional field level attribute
• "help" : "help text"
• "help text" will appear over the module's field when help is on

captcha

• any module can optionally require a "captcha" human verification upon submit
• to enable, you must enable captcha in directives.json and add to the module json as a top level attribute:

    "captcha" : "true",

hide buttons if not logged on

• this option will hide the submit and reset buttons if the user is not logged in
• one use is for viewing public cached results

    "hideifnotlogon" : "true",

autosubmit

• if modules have no input (i.e. are simply a result), they "self submit" automatically with the "autosubmit" tag

    "autosubmit" : "true",

background image

• a module specific background image can be specified with the "backgroundimage" tag
• note: a global image can be specified in directives.json
• N.B. can not be currently combined with user colors
• e.g.

    ,"backgroundimage" : "pngs/simulate.png"

• these images should be placed in add/pngs/ before running genapp.pl

center

• by default, module fields are left justified on the screen. To "center" the module fields, add the following to your module json:

    ,"center" : "true"

centeroutput

• by default, module output fields are left justified on the screen. To "center" the only the module output fields, add the following to your module json:

    ,"centeroutput" : "true"

submit_label

• by default, the submit label is labeled "Submit", to change this

    ,"submit_label" : "your submit label text"

nowrap

• by default, text in columns such as labels, wraps when there is insufficient room on the screen. To prevent this:

    ,"nowrap" : "true"

notify

• rev 1039+
• email notification is available for modules by specifying the following

    ,"notify" : "email"

• in git:php7designer
  • executable can set "_disable_notify" : 1 in the output object to disable email notification

job limits / weight

• by default, the module's running job does not count against any configured job limits
• if you wish to include a module to be limited, you need to add a 'jobweight' field to the module json

    ,"jobweight" : 1

• the value (1) used above is a typical value to use, but you can use any floating point value
• controlling the job limits for users is described in the appconfig.json info.

getting the module json as part of your executable input

• to activate this option, add the following to your module json:

    ,"sendmodulejson" : "true"

• the executable will receive an additional input field with the _json tag

rfile and lrfile

• n.b. when a remote (server-side) file is given to the module's executable, only the path is given, a copy is not made in the job directory

action fields

• action is an explicit input button for running a module-local helper executable before normal submit.
• It is intended for pre-run checks, calculations from current form values, warnings, and field updates that should happen only when the user clicks the button.
• It is separate from hook-backed button fields. Hooks remain automatic/helper behavior and should not be overloaded for precheck work.
• In html5 and ui2, action helpers run outside the Job Manager and do not create a run UUID, project lock, cache entry, or job log entry.
• In ui2, action is implemented in the core ui2 runtime. React/shadcn workbenches receive it through the normal ui2 field bridge; ui2-react is not a separate target language for this feature.
• The field can use normal repeat conditions, so an action button can appear only for a selected branch or repeater-controlled section.
• The helper executable receives JSON on stdin and must return JSON on stdout. Diagnostics should go to stderr.
• The first implementation requires a logged-in web user and runs in a per-user project action directory: results/users/<user>/<project>/_actions/<module>/<action>.
• If an action creates files that later belong to a run, the wrapper should treat them as prepared data and move or copy them into the run-name module folder during the normal submit/run step. Do not leave final run data only in the action scratch directory.
• GenApp also keeps a standalone UI2/React-style hand-test page for this contract at standalone/ui2-react-precheck/.

Example input field:

{
    "role"       : "input",
    "id"         : "precheck",
    "label"      : "Pre-run check",
    "type"       : "action",
    "buttontext" : "Precheck",
    "executable" : "precheck_action",
    "actiondata" : "_allformdata",
    "timeout"    : "30"
}

actiondata can be _allformdata or a comma-separated list of field ids. The helper response can include:

{
    "status"  : "pass",
    "summary" : "Inputs look consistent",
    "actions" : [
        {
            "action" : "set_fields",
            "fields" : {
                "precheck_summary" : "checked"
            }
        },
        {
            "action" : "message",
            "level"  : "info",
            "text"   : "Precheck finished"
        }
    ]
}

Supported html5 and ui2 response actions are set_fields, clear_fields, message, and dialog. Other language targets should use the same field schema and response vocabulary when they add runtime support.

currently defined types

• notes:
  • module entry id's must be unique
  • html5-only should only be temporary until the feature is ported to other languages
  • decimal number values for min, max etc must begin with a digit: e.g. .5 is not a valid number and will not behave as expected.
  • dynamic output groups are html5-only; supported renderer types are documented in Dynamic Outputs ||name||input support||output support||append (output-only)brprimarily for messaging)||default (input-only)||min (input-only)||max (input-only)||step (input-only)||required (input-only)||repeater (input-only)||help br examples||notes||historical genapptest example|| ||integer||yes||yes||yes||no||yes||yes||html5-only||yes||html5-only||html5-only||more info including sync ||Legacy GenAppTest Examples|| ||float||yes||yes||no||yes||yes||yes||html5-only||yes||no||html5-only|| ||Legacy GenAppTest Examples|| ||text||yes||yes||no||yes||no||no||no||yes||no||html5-only|| ||Legacy GenAppTest Examples|| ||textarea||yes||yes||html5-only||yes||no||no||no||yes||no||html5-only||multiline default input not yet supported||Legacy GenAppTest Examples|| ||checkbox||yes||yes||no||no||no||no||no||yes||html5-only||html5-only||additional 'checked' attribute||Legacy GenAppTest Examples|| ||action||html5/ui2||no||no||no||no||no||no||no||html5/ui2||html5/ui2||explicit user-triggered helper executable for pre-run checks or field updates; target-neutral schema, html5 and ui2 runtime support||none currently|| ||radio||yes||yes||no||no||no||no||no||yes||no||html5-only||one entry for each buttonbrname is the name of the radio button (common for all members)br||Legacy GenAppTest Examples|| ||listbox||yes||no||no||yes||no||no||no||no||html5-only||html5-only||no required attribute, but it will always have a value brrow spacing minor layout issue on repeater||Legacy GenAppTest Examples|| ||plot2d||no||yes||no||no||no||no||no||no||no||html5-only||more info ||Legacy GenAppTest Examples|| ||atomicstructure||no||yes||no||no||no||no||no||no||no||html5-only||more info ||Legacy GenAppTest Examples|| ||file||yes||yes||no||no||no||no||no||yes||no||html5-only||additional multiple attribute(input-only)||Legacy GenAppTest Examples|| ||lrfile||html5-only||html5-only||no||no||no||no||no||yes||no||html5-only||more infobr"multiple" attribute not yet supported||Legacy GenAppTest Examples|| ||rfile||html5-only||html5-only||no||no||no||no||no||yes||no||html5-only||more infobr"multiple" attribute not yet supported||Legacy GenAppTest Examples|| ||rpath||html5-only||html5-only||no||no||no||no||no||yes||no||html5-only||more infobr"multiple" attribute not yet supported||Legacy GenAppTest Examples|| ||label||html5-only||html5-only||no||yes*||no||no||no||no||no||html5-only||*can be header1,2,3,4 or blank||Legacy GenAppTest Examples|| ||hidden||html5-only||no||no||yes||no||no||no||no||no||no||this is primarily to pass a value in json to the executable||Legacy GenAppTest Examples|| ||html||no||html5-only||no||yes||no||no||no||no||no||no||allows html output||none currently, but it's a typical field layout|| ||progress||no||html5-only||no||no||no||yes (for output)||no||no||no||no||progress bar default ranges is 0 to 1.0, setting max to a positive value will make the range 0-max||Legacy GenAppTest Examples||