The ResultFile component

The ResultFile component is the counterpart of the File component, that allows the user to download result files created by the back-end. In comparison to the gui_download functionality, there are several differences.

  • The ResultFile component is able to show multiple download links in a list, instead of being just a download button.
  • The ResultFile component does not block the user interface during the download. It also does not trigger an event in the back-end.
  • For deployed applications, the file is downloaded via the portal webserver instead of being part of the submission data. This makes the ResultFile component suitable for downloading larger files.

ResultFile

There are two modes of operation:

  • base64: In base64 mode, the selected files are base64 encoded and put in the submission data. This is the default mode for local applications.
  • portal: In portal mode, the selected files are uploaded to the portal webserver. Download URLs are provided in the submission data. This is the default mode for deployed applications.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any ResultFile component has a label and tooltip property even though these are not explicitly listed here.

Properties

NameDescriptionDatatypeDefault
tableViewWhen true and the component is part of an EditGrid, the component's value is shown (simplified) in the collapsed row of the EditGrid.BooleanFalse

Methods

NameSyntaxDescription
uploadpayload = upload(filePaths, mimeTypes, metaData, payload, key, Parent=parent, NestedForm=nestedForm, FileNames=fileNames, Append=false)Upload results files such that the user can download them1. The inputs are documented below. Note that when using upload for a second time, previously uploaded files are removed from the submission data2.
useBase64Uploadobj.useBase64Upload()Use base64 mode in deployed mode.
Upload method

The input of the static upload method are:

  • filePaths: list/array of paths to files to upload
  • mimeTypes: list/array of MIME-types corresponding to the files to upload
  • metaData: Metadata dict/struct
  • payload: The payload dict/struct
  • key: Key of the ResultFile component
  • Parent/NestedForm: Optional inputs for further specifying what ResultFile component is used to upload the files
  • FileNames: Optional input for specifying an list/array of file names to display in the component3
  • Append: Optional input to control whether previously uploaded files remain listed. Per default the list is cleared before the new file is uploaded.

Example

In the gui_event code snippets below a simple dict/struct is written to a .json file in the session folder of the back-end and made available in the front-end.

# Write a dict to a .json file in the back-end's session folder.
session_folder = utils.getSessionFolder(meta_data, create=True)
nice_name = "example_table.json"
file_name = os.path.join(session_folder, f"example_table-{uuid.uuid4()}.json")

with open(file_name, 'wt') as f:
    json.dump({"hello": "world"}, f)

# Upload the created .json file to make it available in the front-end.
component.ResultFile.upload(
    file_paths=[file_name],
    mime_types=["application/json"],
    meta_data=meta_data,
    payload=payload,
    key="result_file_key",
    file_names=[nice_name]
)
% Write a struct to a .json file in the back-end's session folder.
sessionFolder   = utils.getSessionFolder(metaData, "Create", true);
niceName        = "example_table.json";

fileName = fullfile( ...
    sessionFolder, ...
    sprintf("example_table-%s.json", matlab.lang.internal.uuid()));

fid = fopen(fileName, 'w');
fprintf(fid, '%s', jsonencode(struct("hello", "world")));
fclose(fid);

% Upload the created .json file to make it available in the front-end.
payload = component.ResultFile.upload( ...
    fileName, ...
    "application/json", ...
    metaData, ...
    payload, ...
    "result_file_key", ...
    'FileNames', niceName);

See also

  • File for uploading files.

1

Note that the uploaded files stay present on the back-end server, unless they are stored in the session folder. For other files a custom cleanup action needs to be implemented in gui_close.

2

The upload function only provides the submission data for the files uploaded in the last call. To retain previously uploaded files, they must be added to the submission data again. The files uploaded to the portal are not removed, so it is not necessary to re-upload the file.

3

It is recommended to use unique file names, e.g. using a timestamp or random suffix, to avoid unintentionally overwriting files. The FileNames input argument can be used to provide the original name to the user.