sc-uploader

This document is a user guide for the sc-uploader component release version 7.1.9.

1 Purpose

sc-uploader places an uploader field on a form, providing the user with the ability to select a file, upload it, save it to the Formbird document database and link it to the document displayed on the form.

To select a file for upload, the user has the choice of:

1. EITHER clicking the "Select Files" button which will open their device's file manager, allowing the user to select one or more files for upload.
2. OR clicking the "Select Files" button on a mobile device that has a camera (e.g. iPhone, iPad) which will open the device's photos folder, allowing the user to select one or more image files (e.g. jpg, png, etc) for upload.
3. OR selecting, dragging and dropping the required file onto the "Or drop file here" area of the uploader field.

Having selected one or more files for upload, the form will display:

1. Each selected file as a thumbnail under the uploader field. Clicking a thumbnail will open and display the file on the form in a modal pop-up. Each thumbnail provides a dedicated delete button (small red trash can), clicking it will prompt the user to confirm or cancel the delete of the uploaded file.
2. The flashing "Save" icon , indicating a change has occurred to the document displayed on the form i.e. a file has been uploaded to the document. Clicking the flashing "Save" icon will:
   • Save each uploaded file to the Fombird document database.
   • For each uploaded file, create a file reference document which stores the link between the uploaded file and the document displayed on the form.

Four sytem wide properties of the sc-uploader component are defined in the Formbird "Environment Configuration" document's, "serverConfiguration" section, by the "fileUploader" field and its four sub fields "defaultTemplateId", "relatedDocumentField", "fileUploaderField" and "extensionWhitelist".

Example

        "fileUploader": {
            "defaultTemplateId": "2d5d90f0-9da9-11e7-b329-9f0a52692ed3",
            "relatedDocumentField": "relatedDocument",
            "fileUploaderField": "fileDetails",
            "extensionWhitelist": [
                "json",
                "jpeg",
                "jpg",
                "png",
                "tiff",
                "bmp",
                "gif",
                "txt",
                "doc",
                "docx",
                "ppt",
                "pptx",
                "xls",
                "xlsx",
                "zip",
                "rar",
                "7zip",
                "gzip"
            ]
        }

The four fields within the "fileUploader" field are described in the table below.

The sc-uploader definition provides fields for setting the properties of a sc-uploader field on a form and is fully described below.

2 Definition

sc-uploader is defined by a set of name/value pair fields consisting of:

• Required system fields
• Required customizable fields
• Optional customizable fields

Note:

1. Default values for the sc-uploader definition fields described in the tables below are shown in bold text.

2.1 Required System Fields

2.2 Required Customizable Fields

2.3 Optional Customizable Fields

3 Typical Definition

Below is a typical sc-uploader definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-uploader",
    "fullWidth": true,
    "label": "Typical Defn sc-uploader",
    "name": "typicalDefnScUploader",
    "maxImageHeight": 960
}

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

    "disableSave":true,
    "enabled":false,
    "fileReferenceTemplateId": "d0995380-5c5e-11e7-bfda-cb86d7c461c0"
    "mandatory": true,
    "visible":false,

4 Examples

Example 1

sc-uploader defined with the typically needed fields.

        {
            "componentName": "sc-uploader",
            "fullWidth": true,
            "label": "Typical Defn sc-uploader",
            "name": "typicalDefnScUploader",
            "maxImageHeight": 960
        }

Resulting field on the form:

Resulting field on the form after selecting an image file (sc-uploader PNG test file 'Formbird makes it possible'.png) for upload:

• The uploaded image file will display as a thumbnail under the sc-uploader field.
• To delete an uploaded image file, click the red trash can in the top right corner of its thumbnail.
• To view an uploaded file, clicking the thumbnail to open and display the file on the form in a modal pop-up. The file name and file exension is shown beneath the displayed file.:

Resulting field in document and database after saving the uploaded file:

    "documentId": "e8f2a0a0-5b11-11ed-aa86-0fbaa4c2db1e",
    "typicalDefnScUploader": [
        {
            "fileName": "sc-uploader PNG test file 'Formbird makes it possible'.png",
            "fileType": "PNG",
            "fileNo": "5326b480-5b20-11ed-aa86-0fbaa4c2db1e",
            "basePath": "20221101"
        }
    ]

Resulting File Reference Document:

As the sc-uploader is defined without a "fileReferenceTemplateId" field, the file reference template, whose documentId is specified in the "Environment Configuration" document by the fileUploader . defaultTemplateId field, wiil be used to create a file reference document. The file reference document stores the link between the uploaded file and the document displayed on the form.

In File Reference Document, part of which is shown below:

• The "fileDetails" field stores details of the uploaded file.
• The "relatedDocument" field stores stores the documentId of the document displayed on the form this linking the uploaded file to the document displayed on the form.

    "fileDetails": [
        {
            "fileNo": "5326b480-5b20-11ed-aa86-0fbaa4c2db1e",
            "fileName": "sc-uploader PNG test file 'Formbird makes it possible'.png",
            "fileType": "PNG",
            "basePath": "20221101",
            "ext": "png",
            "mimeDetailsObj": {
                "contentType": "image/png"
            }
        }
    ],
    "relatedDocument": [
        {
            "documentId": "e8f2a0a0-5b11-11ed-aa86-0fbaa4c2db1e",
            "name": "e8f2a0a0-5b11-11ed-aa86-0fbaa4c2db1e"
        }
    ]