The gui_upload function can be used to upload content to the form. It is triggered instead of gui_event when a button is clicked that had the setUpload method called on it during form initialization. Before the function is called, the user will have had the opportunity to select the file to upload. Upon arrival in the function, the payload will have a field upload that has the following fields:

  • contentType: The content type specified with the setUpload method.
  • fileContents: Base64 encoded version of the file's contents.
  • fileName: The name of the file including extension.
  • filePath: The full path of the file including extension.

Similar to the gui_event function, you can choose what happens depending on the event that is triggered.

Alternatively, the File component can be used to upload files.


The syntax of the gui_upload function is similar to that of gui_event as shown in the example below. It shows the initialization code of a button setup for uploading an Excel file. The gui_upload function reads the contents of the file and calls a plotting function to plot the data in the form. The definition of the plotting component is not shown in the initialization code.

def gui_init(meta_data: dict) -> dict:
    form = Form()
    btn = component.Button("stage_1_upload", form)
    btn.label = "Upload analysis - stage 1"
    return {"form": form}

def gui_upload(meta_data: dict, payload: dict) -> dict:
    if payload["event"] == "UploadAnalysis":
        with open(payload["upload"]["filePath"], "r") as file:
            data = json.load(file)

        plot_stage_1(payload, data)
        # Handle other upload actions.

    return payload
function payload = guiInit(metaData)
    form        = Form();
    btn         = component.Button("stage_1_upload", form);
    btn.label   = "Upload analysis - stage 1";
    payload.form = form;

function payload = guiUpload(metaData, payload)
    switch payload.event
        case "UploadAnalysis"
            data    = jsondecode(fileread(payload.upload.filePath));
            payload = plotStage1(payload, data);
            % Handle other upload actions.