Archive Trac docs defaults

Docs Defaults

Legacy Trac archive page imported from docs_defaults. Source: https://genapp.rocks/wiki/wiki/docs_defaults. Review age, links, and examples before treating as current.

getting values to populate input fields

• Only available in the github version of genapp currently in the php7designer branch

• users must be logged in to the application or clicking this button will return an appropriate error message box.

• to populate input fields, a "hook" or parser program is needed

  • this will take JSON input and produce JSON output which will populate the UI

• add to your module JSON fields a button to perform this task, e.g.

        ,{
            "role"         : "input"
            ,"id"          : "getdefaults"
            ,"label"       : "Get defaults"
            ,"type"        : "button"
            ,"buttontext"  : "Get defaults"
            ,"buttonstyle" : "select"
            ,"hook"        : "load_defaults.php"
            ,"hookdata"    : "_allformdata"
            ,"file"        : "lfile"
        }

• optional properties:
  • buttonstyle
    • defaults to "select", but can currently also be "submit" or "reset"
  • hookdata
    • provides additional field data values by id to the hook input object
    • can be an a single module field id that is not under a repeater
      • if under a repeater, the flattened id must be used (tree parent ids joined with dashes) (see 'handling repeat & repeater values' section)
    • the special value "_allformdata" adds all module field ids
      • keys under repeaters will be flattened (see 'handling repeat & repeater values' section)
  • file
    • if included, a file dialog will be presented to the user allowing them to select a file, the contents of which will be passed to the JSON input of the "hook" as "_filedata"
    • currently supports values of "lfile" & "lrfile". "rfile" can be added upon request.
• all other parameters are required
  • hook
    • name of a program relative to the standard "bin" directory

== the "hook" program

• this will receive a JSON object in standard input
  • N.B. this is different to the standard executable which receives its input via a command line argument
• it must return JSON and nothing else to standard output
• this program is responsible for taking the input data and producing the JSON to populate the UI
• object values should match those expected as input to the executable
  • the exception to this is when a repeat or repeater value is updated (see 'handling repeat & repeater values' section)
• the current working directory of the hook program is the users current project directory
  • this enable parsing expected outputs of an existing server file without the user loading a file

php example

• a short php example script for a "hook"

#!/usr/local/bin/php
<?php
{};

$request = json_decode( file_get_contents( "php://stdin" ) );
$result  = (object)[];

function error_exit( $msg ) {
    global $result;
    $result->error = $msg;
    echo json_encode( $result );
    exit;
}

if ( $request === NULL ) {
    error_exit( "Invalid JSON input provided" );
}

if ( $request->_filedata ) {
    $filelines = explode( "\n", $request->_filedata );
    $result->textfield = sprintf( "file found with %d rows", count( $filelines ) );
} else {
    $result->textfield = "no file found";
}

echo json_encode( $result );
exit;

• the associated module JSON extract

        ,{
            "role"        : "input"
            ,"id"         : "textfield"
            ,"label"      : "Text field"
            ,"type"       : "text"
        }

== checkbox can also load "hook"

• add a "hook":"program-name" to the checkbox module field JSON, e.g.

        ,{
            "role"         : "input"
            ,"id"          : "sparams"
            ,"label"       : "Simulation parameters"
            ,"type"        : "checkbox"
            ,"repeater"    : "true"
            ,"hook"        : "equilibration_defaults.php"
        }

• this will automatically run the hook when the checkbox is checked on
• "file" is not supported
• this case uses a checkbox as a repeater - this is not required, but can be useful to populate fields under the checkbox only when switched on

== handling repeat & repeater values

• setting repeat values requires special handling in the "hook"
• the key value will be a hyphenated join of all parent repeats
• array indices (integer repeaters) must be numerically appended
• e.g.
  • given module json fields excerpt:

...
,{
    "role"         : "input"
    ,"id"          : "sparams"
    ,"label"       : "Details"
    ,"type"        : "checkbox"
    ,"repeater"    : "true"
    ,"hook"        : "runrelax_defaults.php"
}
,{
    "role"         : "input"
    ,"id"          : "description"
    ,"label"       : "Description"
    ,"type"        : "textarea"
    ,"repeat"      : "sparams"
}

,{
    "role"         : "input"
    ,"id"          : "runjobs"
    ,"label"       : "Number of minimization jobs"
    ,"type"        : "integer"
    ,"repeat"      : "sparams"
    ,"repeater"    : "true"
    ,"hidden"      : "true"
}
,{
    "role"         : "input"
    ,"id"          : "min_steps"
    ,"label"       : "Minimization steps for job"
    ,"type"        : "integer"
    ,"repeat"      : "runjobs"
}
...

- to set values for ids {{{description}}} & {{{runjobs}}}, the keys would be {{{sparams-description}}} & {{{sparams-runjobs}}} respectively.
- to set 2 "array" values for id {{{min_steps}}}, the keys would be {{{sparams-runjobs-min_steps-0}}} & {{{sparams-runjobs-min_steps-1}}}