Project

General

Profile

Wiki » 4GL Enhancements »

WEB-FILE-UPLOAD Statement

Overview

The WEB-FILE-UPLOAD statement is an extension to the 4GL language, designed to facilitate file uploads directly from a web browser to a 4GL application. This statement addresses modern web browser security constraints that prevent the asynchronous invocation of file upload dialog. The statement eliminates the need for the security dialog displayed during the invocation of SYSTEM-DIALOG GET-FILE AT-WEB-BROWSER UPLOAD. This was implemented in #7273.

See how WEB-FILE-UPLOAD is used in the following code sample.

DEF BUTTON b1.
DEF FRAME f b1.

WEB-FILE-UPLOAD REGISTER b1 IN FRAME f CHOOSE, MOUSE-SELECT-CLICK UPLOAD.

ON WEB-UPLOAD-COMPLETE OF b1 IN FRAME f DO:
   IF NOT SESSION:WEB-UPLOAD-ERROR THEN
      MESSAGE "A file was uploaded:" SESSION:WEB-UPLOAD-FILES.
end.

ENABLE ALL WITH FRAME f.
WAIT-FOR CLOSE OF THIS-PROCEDURE.

Syntax

The WEB-FILE-UPLOAD statement can be used in two forms: to register a widget for file uploads or to de-register a previously registered widget.

Registering a Widget

WEB-FILE-UPLOAD REGISTER widget-reference IN frame-reference event-list
    [UPLOAD [DIR "directory-path"]] 
    [MULTIPLE] 
    [TITLE "dialog-title"] 
    [FILTERS "file-type-description (*.extension) [, ...]"]

Parameters

  • REGISTER: Registers a widget to trigger file upload action on specified events.
  • widget-reference: The widget that will handle the file upload events.
  • event-list: Specifies the events that will trigger the file upload or file selection dialog. Acceptable events include mouse events, key events, or the CHOOSE event.
  • UPLOAD (optional): When specified, the selected files are uploaded to the server.
  • DIR "directory-path" (optional): Specifies the directory on the local file-system where the uploaded files will be stored.
  • MULTIPLE (optional): Allows selecting or uploading multiple files. If omitted, only a single file can be selected or uploaded.
  • TITLE "dialog-title" (optional): Specifies the title of the file selection dialog.
  • FILTERS "file-type-description (.extension) [, ...]"* (optional): Defines the file types that can be selected in the file selection dialog, following the same syntax as the SYSTEM-DIALOG GET-FILES statement.

Example Usage

WEB-FILE-UPLOAD REGISTER b1 IN frame f CHOOSE, MOUSE-SELECT-CLICK
    TITLE "4GL Files" 
    MULTIPLE
    UPLOAD DIR "/home/user" 
    FILTERS "Text Files (*.txt)" "*.txt", "Image Files (*.png)" "*.png".
In this example:
  • The widget b1 in frame f is registered for the CHOOSE and MOUSE-SELECT-CLICK events.
  • The file selection dialog is titled "4GL Files".
  • Multiple files can be selected.
  • Files are uploaded to the /home/user directory on the server.
  • Only files with .p or .r extensions can be selected.

Deregistering a Widget

Previously registered widget can be de-registered with the use of the DE-REGISTER option. After de-registration the widget will no longer allow to trigger the upload action.

Note that the use of WEB-FILE-UPLOAD DE-REGISTER is optional, the widget is automatically de-registered when it is destroyed or descoped.

WEB-FILE-UPLOAD DE-REGISTER widget-reference

Example Usage

WEB-FILE-UPLOAD DE-REGISTER b1 IN FRAME f.
In this example:
  • The widget b1 IN FRAME f is de-registered from handling file upload events.

Behavior and Events

After the upload action finishes (the file choose dialog is confirmed to select or upload files and after the files are uploaded) the new 4GL trigger WEB-UPLOAD-COMPLETE is executed.

1. If the UPLOAD option is used, the selected files are uploaded to the specified directory on the server and SESSION:WEB-UPLOAD-FILES will contain comma separated list of the full file names of the uploaded files.
2. If the UPLOAD option is not used, only the names of the selected files are stored in SESSION:WEB-UPLOAD-FILES.
3. The event WEB-UPLOAD-COMPLETE is triggered for the registered widget upon the completion of the file upload or selection process.

SESSION Attributes

Two new SESSION attributes are introduced:

  • WEB-UPLOAD-FILES: Contains the comma separated list of uploaded or selected files. When the UPLOAD option is used the list will contain the full file names of the uploaded files.
  • WEB-UPLOAD-ERROR: A boolean value that indicates if an error occurred during the file upload or selection process.

Event Registration Limitations

The WEB-FILE-UPLOAD statement can register for the following types of events:
  • Mouse events (e.g., MOUSE-SELECT-CLICK)
  • Key events
  • CHOOSE event (applicable to widgets that support it)

Example Scenarios

Scenario 1: Upload Single File

WEB-FILE-UPLOAD REGISTER btnUpload IN FRAME mainFrame MOUSE-SELECT-CLICK
    UPLOAD DIR "/var/uploads" 
    TITLE "Select a File to Upload" 
    FILTERS "Text Files (*.txt)" "*.txt".

In this scenario, clicking the btnUpload button in mainFrame will open a dialog to select a single .txt file for upload to the /var/uploads directory.

Scenario 2: Select Multiple Files Without Upload

WEB-FILE-UPLOAD REGISTER btnSelect IN frame selectFrame CHOOSE
    MULTIPLE
    TITLE "Choose Files" 
    FILTERS "All Files (*.*)" "*.*".

Here, clicking the btnSelect button in selectFrame will allow the selection of multiple files of any type, but they will not be uploaded; only their names will be passed to the 4GL application.

Summary

The WEB-FILE-UPLOAD statement provides a robust mechanism for integrating file upload capabilities into 4GL web applications, accommodating modern browser security restrictions and offering flexible options for handling file selection and upload processes.

Feel free to refer to this documentation whenever you need to implement file upload functionalities in your 4GL web applications using the WEB-FILE-UPLOAD statement.

© 2024 Golden Code Development Corporation. ALL RIGHTS RESERVED.