A file upload control is a drag-and-drop control that allows user to upload files to the server for storage upon performing a save action. Each file upload control must be associated with a Single Named Range (SNR) in the workbook. Note: The uploaded file will not be stored in the system unless the target named range is also appropriately bound to a File-type column in a database for the existing application.
The Named Range property lists of all Single Named Ranges (SNR) from the workbook. The name of the uploaded file will be sent to the calculation engine, as if the user entered file’s name into that cell in the spreadsheet model.
Named ranges containing formulas are excluded from the list, as well as named ranges that have already been bound to a different input in your user interface.
The Name property constitutes the label that will appear in the user interface. Other properties, such as Tooltip, will also derive their dynamic {FriendlyName} value from this property.
The Maximum File Count property determines the maximum number of files that can be uploaded to this control. A value between 1 and 100 can be chosen. Default value for this property is 1.
The Label Horizontal Alignment property determines the horizontal orientation of the label. This value can be set to Left, Center, or Right. The default horizontal alignment is Left.
The Label Vertical Alignment property determines the vertical orientation of the label. This value can be set to Top, Middle, or Bottom. The default vertical alignment is Middle.
The Label Size property is the spacing distribution of the input control’s label vs. the input control. The maximum width of both controls cumulatively is considered to be 12 – a width of 12 for the label would indicate that the label occupies a full row within its container and the input control occupies a full row beneath it.
Any label distribution below 12 will indicate that the label and the input control occupy the same row in the user interface. The label’s width will be used to calculate the control’s width such that the two controls cumulatively occupy the full width of 12.
For example, setting the Label Size to 6 will indicate that the control width is also 6. This means the label will occupy 50% the width of the row and the control will occupy 50% the width of the row.
Likewise, setting the Label Size to 3 will indicate that the control width is 9, meaning that the label will occupy 25% the width of the row while the input control occupies 75% the width of the row.
Setting the Label Size to 0 will hide the label in the user interface.
If Trigger Calculations is selected, it will trigger a calculation when file upload is completed. Calculations perform a server call with all of the inputs from the user interface and populate the output controls with the values from the updated calculation.
In workbooks with complex calculations, enabling calculations may lead to delays in the user experience.
The best practice when determining whether an input should trigger calculations should take into account the following factors:
- Does this input affect any calculated values? If the field is simply informational, then there is no reason to trigger a calculation.
- Does this input affect my user interface? If the field can change the visibility or enabled-ness of pages or other controls, then it is a good idea to trigger calculations when changes occur to the input.
- Will something else trigger calculations before this input is relevant? If the user won’t see the results of the calculations until reaching a different page, then you can hold off on triggering calculations until a button press or a different control’s value is changed.
Tooltips are informative message boxes that are displayed when you mouse-over or click on a control. The Tooltip Type property determines the message style, and when the information will be shown.
- Tooltip: The content will appear in a small bubble when the user enters focus on the target input by moving their mouse over the control.
- Popover: The content will appear in a pop-up box when the user clicks on the target input.
The Accepted File Types property is a multi-select list of acceptable file types for the upload. Leaving this option empty will allow the user to upload a file of any type. The selectable values include the following:
- PNG
- JPEG
- JPG
- SVG
- GIF
- XLS
- XLSX
- DOC
- DOCX
- ZIP
- 7Z
If restrictions are imposed on the list of acceptable file types, then the user will only be able to select those file types in the file upload dialog that launches when the user clicks on the control.
There are also several special file types that can alter the behavior of the file upload control for mobile devices:
- Image – This file type will automatically launch a mobile device’s camera when clicked. It also allows for all types of image files to be uploaded.
- Audio – If the device supports it, this file type will automatically launch a mobile device’s audio recorder when clicked. It also allows for all types of audio files to be uploaded. Note: Apple iOS devices do not support this as of the writing of this document.
- Video – This file type will automatically launch a mobile device’s camera for video recording when clicked. It also allows for all types of video files to be uploaded.
The Maximum File Size property determines the maximum file size that can be uploaded to this control in kilobytes (KB). This should not be larger than the same property for the corresponding database column for this target named range.