Reference Dynamic Outputs

Dynamic Outputs

Dynamic outputs let an html5 module declare one output group and create a bounded set of output instances at runtime. This is for executables that do not know the exact number of reports or plots until the job runs.

Supported dynamic output types are:

• simple content: html, textarea
• scalar fields: text, integer, float, email
• media and files: image, video, file
• progress: progress
• plots/viewers: plotly, plot2d, bokeh, matplotlib, plot3d, ngl, atomicstructure

For downloadable artifacts, use module field type: file. If the field also has multiple: true, the dynamic child uses the existing filelinkm runtime renderer.

Module JSON

Declare a normal output field and add:

• dynamicoutput: set to true
• idprefix: required prefix for generated instance ids
• max: required positive integer cap on generated instances
• optional trusted renderer settings such as width, height, multiple, append, rows, cols, plot controls, or viewer settings, depending on the output type

Example:

{
    "role"          : "output",
    "id"            : "dynamic_plot",
    "label"         : "Dynamic Plot",
    "type"          : "plotly",
    "dynamicoutput" : "true",
    "idprefix"      : "dyn_plot",
    "max"           : "4"
}

Executable Output

Return an object or array under the declared dynamic group id. Each item may include:

• label: label shown next to the generated instance
• value or data: value passed to the underlying output renderer
• id: optional explicit instance id; it must be a safe GenApp-style id

Example:

{
    "dynamic_plot": {
        "items": [
            {
                "label": "Residuals",
                "value": {
                    "data": [
                        { "x": [1, 2, 3], "y": [2, 1, 2], "type": "scatter" }
                    ],
                    "layout": { "title": "Residuals" }
                }
            },
            {
                "id": "dyn_plot_summary",
                "label": "Summary",
                "value": {
                    "data": [
                        { "x": ["ok", "warn"], "y": [8, 1], "type": "bar" }
                    ]
                }
            }
        ]
    }
}

By default, a new dynamic update replaces previously generated instances for that group. Use "replace": false in the group object when a partial update should leave existing instances in place.

If a wrapper returns an empty dynamic group, GenApp clears any existing generated instances for that group and hides the group container:

{
    "dynamic_plot": {
        "items": []
    }
}

Constraints

• Dynamic outputs are html5-only.
• The field must have role: output.
• Supported module JSON types are html, plotly, image, video, file, textarea, text, integer, float, email, progress, plot2d, bokeh, matplotlib, plot3d, ngl, and atomicstructure.
• max is required and limits the number of items rendered.
• idprefix is required and must be a valid safe identifier.
• If an item omits id, GenApp generates ids as idprefix_1, idprefix_2, and so on.
• Runtime result JSON may provide item data, labels, and safe explicit item ids. It must not provide renderer type, arbitrary templates, executable setup code, or untrusted field metadata.

Runtime Behavior

GenApp generates only the dynamic group container statically. Dynamic groups start hidden; runtime data creates child output fields inside that group, routes each child value through the existing output renderer for the declared type, and shows the group when at least one item is rendered.

Resetting the module output removes generated dynamic instances, hides the group, and clears their saved last/default value state.

repeat may be used on a dynamic output group as a group visibility rule. It does not make generated output items participate in the full input repeater system. Output items remain job-result objects returned by the wrapper, which avoids making completed results depend on live form state during reattach, stale-input editing, or result review.

If a wrapper returns a key for a declared dynamic output group whose field is inactive or not present in the current output DOM, GenApp clears any existing instances for that group and does not report it as a generic unexpected result. The wrapper should still avoid returning inactive groups unless it is explicitly clearing them; non-empty inactive updates are treated as developer diagnostics rather than user-facing result errors.

matplotlib dynamic outputs render as iframe instances and update by setting the iframe src from the item value.

ngl dynamic outputs use the existing NGL viewer runtime path. Each item value should use the same payload documented in NGL viewer: loadname is required, loadparams is optional, representation defaults to cartoon, optional representationParams are passed through to component.addRepresentation(type, params), and optional representations may provide multiple { type, params } entries for selection-specific views. The runtime creates an NGL.Stage, loads loadname with optional loadparams, adds one or more representations, and disposes the stage through ga.ngl.clear() during reset/removal.