Archive Trac docs module fields

Docs Module Fields

Legacy Trac archive page imported from docs_module_fields. Source: https://genapp.rocks/wiki/wiki/docs_module_fields. Active canonical page: Reference-Module-JSON. Review age, links, and examples before treating as current.

module json

• the module json describes the input and output for a wrapped executable module
• many examples are found here

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
• 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
• 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
• 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

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. ||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 (example calculate:calculate_2, analysis:pm)||notes||genapptest example|| ||integer||yes||yes||yes||no||yes||yes||html5-only||yes||html5-only||html5-only||more info including sync ||tools:center brrepeater example interact:interact_1 brstep example tools:center|| ||float||yes||yes||no||yes||yes||yes||html5-only||yes||no||html5-only|| ||tools:center|| ||text||yes||yes||no||yes||no||no||no||yes||no||html5-only|| ||build:build_1|| ||textarea||yes||yes||html5-only||yes||no||no||no||yes||no||html5-only||multiline default input not yet supported||build:build_2|| ||checkbox||yes||yes||no||no||no||no||no||yes||html5-only||html5-only||additional 'checked' attribute||build:build_2brrepeater example calculate:calculate_1|| ||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||build:build_2|| ||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||build:build_2 brrepeater example calculate:calculate_2|| ||plot2d||no||yes||no||no||no||no||no||no||no||html5-only||more info ||tools:data_interpolation|| ||atomicstructure||no||yes||no||no||no||no||no||no||no||html5-only||more info ||tools:data_interpolation|| ||file||yes||yes||no||no||no||no||no||yes||no||html5-only||additional multiple attribute(input-only)||simulate:simulate_1|| ||lrfile||html5-only||html5-only||no||no||no||no||no||yes||no||html5-only||more infobr"multiple" attribute not yet supported||tools:filetest|| ||rfile||html5-only||html5-only||no||no||no||no||no||yes||no||html5-only||more infobr"multiple" attribute not yet supported||tools:filetest|| ||rpath||html5-only||html5-only||no||no||no||no||no||yes||no||html5-only||more infobr"multiple" attribute not yet supported||tools:filetest|| ||label||html5-only||html5-only||no||yes*||no||no||no||no||no||html5-only||*can be header1,2,3,4 or blank||interact:interact_2|| ||hidden||html5-only||no||no||yes||no||no||no||no||no||no||this is primarily to pass a value in json to the executable||analysis:pm|| ||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||tools:center||