How To Upload Files To The Database

There are two data types in Kitto^x that allow a user to upload files to the server. The two data types differ in the storage medium: You use Blob if you want to store the data in a blob field of the model underlying table, and FileReference if you want the file to be stored outside the database, in a file system directory of your choice. The GUI that Kitto^x generates is identical in the two cases, and features a read-only description of the contents plus buttons to upload, download and clear the field.

In order to use the Blob data type, you need a blob column in the underlying database table. A FileReference(N) data type maps onto a string column (usually varchar) of length N, which will store the file name (without a path). Examples:

A blob field.

Fields:
  ...
  Picture: Blob
    Hint: Select a picture
    # Size constraint for uploads. You can use KB, MB and GB
    # suffixes for convenience.
    MaxUploadSize: 100KB
    # Predefined file name for downloads. If not specified,
    # it is inferred by the model CaptionField.
    DefaultFileName: test.gif
    # Assumes the data is a picture and uses a different
    # display GUI with a thumbnail generated on the fly.
    # Otherwise a plain text description is displayed.
    IsPicture: True
      Thumbnail:
        Width: 150
        Height: 150

A file reference field.

Fields:
  ...
  Picture_File: FileReference(150)
    # By default, Kitto generates short file names and does
    # not store the path in each record, so you can use a
    # shorter field if you want.
    DisplayWidth: 40
    # This is mandatory and indicates where to store the files
    # whose automatically generated names are stored in the
    # field.
    Path: %Config:BlobPath%
    # Assumes the data is a picture and uses a different
    # display GUI with a thumbnail generated on the fly.
    # Otherwise a plain text description is displayed.
    IsPicture: True
      Thumbnail:
        Width: 150
        Height: 150

In both cases, you can store the uploaded file name in a separate field of the same model, as needed, by specifying its name in the FileNameField attribute:

Fields:
  ...
  Picture_File_Name: String(100)
  ...
  Picture_File: FileReference(150)
    ...
    FileNameField: Picture_File_Name
    ...

File field behavior in forms

Picture fields (IsPicture: True)

When IsPicture: True is set, the widget shows an inline thumbnail of the image sized according to Thumbnail/Width and Thumbnail/Height, with four action buttons:

Button	Description
Upload	Opens the native file picker (filtered to image files). The selected image is shown immediately in the thumbnail via a local DataURL — no server round-trip is needed until the form is saved.
Download	Downloads the image from the saved record.
Preview	Opens a full-size popup showing the image scaled to 75% × 80% of the browser viewport. Works both for newly selected images (before saving) and for saved records.
Clear	Removes the current image.

The Preview popup reads the URL directly from the thumbnail <img> element, so it reflects the image just selected by the user even before the form is saved.

Non-picture fields (IsPicture: False or not set)

When IsPicture is not set (or False), the widget shows the file name as a read-only text input alongside four action buttons:

Button	Description
Upload	Opens the native file picker. The selected file is uploaded immediately to a server-side temporary area via AJAX — before the form is saved.
Download	Downloads the file. If a new file has been uploaded but the form has not been saved yet, the temporary file is downloaded; otherwise the saved record is used.
Preview	Opens an inline popup showing the file content. Images are displayed scaled to fit; other file types (PDF, Office documents, etc.) are shown in an <iframe>. The popup is sized to 75% × 80% of the viewport. Enabled only when PreviewWindow: True is set on the field.
Clear	Removes the current file. Disables Download/Preview/Clear until a new file is uploaded.

Upload flow (non-picture)

The upload is performed immediately when the user selects a file, without waiting for the form to be saved:

1. The user clicks Upload and selects a file.
2. The file is sent to the server (POST kx/view/{view}/upload/{field}) and stored in a temporary location.
3. The file name display is updated and the companion FileNameField (if configured) is populated.
4. When the user saves the form, the temporary file is moved to its final destination (blob column or Path directory).

If the user clicks Clear after uploading, the temporary file is abandoned (the server cleans it up by age) and the clear flag is sent on save.