Skip to content

sc-uploader

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

go-to-typical-definition

sc-uploader-field-Example-1-Image-1

 

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 Icon-sc-uploader-paper-clip-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 Icon-sc-uploader-camera-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.

Field Valid Values Description
defaultTemplateId A valid template documentId Specifes the documentId of a file reference template.
When a file is uploaded and saved, Formbird uses a file reference template to create a file reference document which stores the link between the uploaded file and the document displayed on the form. File reference documents are created with "systemType": "fileReference"

If required, a file reference template can be defined with an "attachKeys" field, its value being an array of one or more keys. This means the file reference template will then write those keys to each file reference document it creates. Hence only users with a matching account key will be able to view an uploaded file when they click on its thumbnail under the uploader field.

Note:
The optional "fileReferenceTemplateId" field of the sc-uploader component definition (see Section 2) can also be used to specify the documentId of a file reference template. As such, "attachKeys" of the "fileReferenceTemplateId" field provide the ability to restrict view access to uploaded documents at the uploader field level rather than at the system wide level which the "defaultTemplateId"field would do.

If an uploader field has been defined without a "fileReferenceTemplateId" field, then Formbird will use the "defaultTemplateId".
relatedDocumentField The name of field in a file reference document The file reference document field that stores the documentId of the document displayed on the form.
fileUploaderField The name of field in a file reference document The file reference document field that stores details of the uploaded file. These details can include file name, file type (i.e. file extension) and file number.
extensionWhitelist An array of valid file extensions Restricts the files that can be uploaded by an uploader field to those with a file extension matching one of those defined by the "extensionWhitelist" field.

The "extensionWhitelist" field shown in the example above, would restrict the files that can be uploaded to those with a file extension matching one of the 18 listed file extensions.

Note:
Updating the "extensionWhitelist" will replace the existing "extensionWhitelist" (i.e. not add to it) and being a server configuration, will require a restart of the Formbird server.

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

Field Valid Values Description
componentName sc-uploader The component name.

Example:
"componentName": "sc-uploader"

2.2 Required Customizable Fields

Field Valid Values Description
name Any value written in camel case. Defines the name of the sc-uploader field in the document and database.

Example:
"name": "typicalDefnScUploader"

2.3 Optional Customizable Fields

Field Valid Values Description
disableSave true Changing the sc-uploader field value (i.e. by uploading a file) does not trigger the form's "Save" icon to flash.
Exiting the form without saving changes to the sc-uploader field value does not trigger a warning message to display.
In the Angular version of the sc-uploader component, clicking the "Save" icon will not save the sc-uploader field value to the document.
In the AngularJS version of the sc-uploader component, clicking the form's "Save" icon will save the sc-uploader field value to the document.

Example:
"disableSave": true
false Default value.
Changing the sc-uploader field value (i.e. by uploading a file) does trigger the form's "Save" icon to flash.
Exiting the form without saving changes to the sc-uploader field value does trigger a warning message to display.
In both the Angular or AngularJS versions of the sc-uploader component, clicking the form's "Save" icon will save the sc-uploader field value to the document.
enabled false The sc-uploader field is greyed out.
A Stop icon appears on mouseover of the uploader field.
A file for upload cannot be selected or dropped in the "Or drop file here" area.

Example:
"enabled": false
true Default value.
A file for upload can be selected or dropped in the "Or drop file here" area.
fileReferenceTemplateId A valid template documentId The fileReferenceTemplateId field specifes the documentId of a file reference template.

When a file is uploaded and saved, Formbird uses a file reference template to create a file reference document which stores the link between the uploaded file and the document displayed on the form. File reference documents are created with "systemType": "fileReference"

If a file reference template has an "attachKeys" field defining an array of one or more keys, then the file reference template will write those keys to the file reference documents it creates. Hence only users with a matching account key will be able to view a file uploaded by the uploader field when they click on the file's thumbnail under the uploader field.

Example:
"fileReferenceTemplateId": "d0995380-5c5e-11e7-bfda-cb86d7c461c0"
Defaults to the file reference template whose documentId is specified in the "Environment Configuration" document by the fileUploader . defaultTemplateId field (see Section 1 Purpose).

Note:
If the fileReferenceTemplateId field is not defined or is defined without an access key and the defaultTemplateId is defined without an access key then all users will be able to view all files uploaded by the uploaded field.
fullWidth true The sc-uploader field displays full width on the form.

*Example:
"fullWidth": true
false Default value.
The sc-uploader field does not display full width on the form.
label Any value Defines the name of the sc-uploader field on the form i.e. the field label.

Example:
"label": "Test sc-uploader"
Defaults to no label is displayed.
mandatory true The sc-uploader field displays as mandatory (i.e. label in red text with an asterisk).
Saving without a value, a message prompts the user to enter a value for the sc-uploader field, in this case by uploading a file.

Example:
"mandatory": true
false Default value.
The sc-uploader field displays as optional (i.e. label in black text).
maxImageHeight Integer The height resolution at which to compress and save an uploaded image file.
If the image height is less than the specified value then no compression occurs.
If the image height is greater than the specified value then compression occurs such that the aspect ratio is maintained.

**Example:
"maxImageHeight": 960

In the above example:
If the resolution of the image to be uploaded was 640 x 480, then no compression would occur as 480 is less than 960
If the resolution of the image to be uploaded was 1920 x 1080, then compression would occur as 1080 is greater than 960. To maintain the aspect ratio (960/1080 = 0.88), the image would be saved with a resolution of 1690 x 960.
Defaults to upload and save the image with no change to the resolution.
visible false The sc-uploader field is not visible on the form.

Example:
"visible": false
true Default value.
The sc-uploader field is visible on the form.

 

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:

sc-uploader-field-Example-1-Image-1

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

sc-uploader-field-Example-1-Image-2

  • 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.:

sc-uploader-field-Example-1-Image-3

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"
        }
    ]