Overview

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.

Properties

The properties of a file upload control are outlined below.

Named Range

A list 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.

Name

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.

Maximum File Count

The Maximum File Count property determines the maximum number of files that can be uploaded to this control. This value must be between 1 and 100. Default value for this property is 1.

Label Horizontal Alignment

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.

Label Vertical Alignment

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.

Label Size

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.

Trigger Calculations

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.

Tooltip Type

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.

Tooltip Content

This property accepts the special {FriendlyName} tag if you want to insert the value of the Name property of this control into the tooltip.

Tooltip

The Tooltip Content property determines the information that will appear in the tooltip bubble.

Popover

The Popover Content property determines the information that will appear in the popover message.

Clicking on the Edit Content button will launch an instance of a rich-text editor that supports HTML code. The editor includes a simple menu for inserting certain control sets such as tables, lists, images, videos, and links, as well as text formatting controls, such as boldness, highlighting, and font.

Modifying the HTML Content

Clicking on the HTML (</>) button will change the the editor to HTML-mode. In this mode, you can enter your own HTML code, including references to classes that are defined in the Stylesheets module. Click the 'X' button in the right corner to close this window and save your changes.

Styles that are defined in the Stylesheets module will not be visible in the User Interface Designer view of the application. These stylesheets are only loaded during the Preview and Published versions of the application.

Note that scripts that are injected into the HTML will be stripped from the contents control.

Dynamic Content Injection

The value of calculated, and input named ranges can be injected directly into the HTML contents of the popover.

All dynamically injected variables must be entered inside double curly braces - {{ }}. To inject a variable into the contents, begin by entering double curly braces, and the system will automatically display available fields.

Single Named Ranges

When you enter double curly braces, you will see a list of Single Named Ranges (SNR). Selecting one of these from the list will populate the name of the named range in the contents.

Several formatting options are available when injecting the value of a Single Named Range (SNR). To use any of the formatting options, simply type in a colon character (:) after the name to see a list of supported data types. If you don't apply any formatting, the name will be injected as an unformatted value.

The data types (Integer, Decimal, DateTime, or Text) are necessary to determine the format of the field. The system will automatically format the value of the Single Named Range (SNR) when you select a data type. The text data type will get the formatted value directly from the calculation engine. Text data type also has an optional paramater (None) for formatting that has no effect on the output.

Upon selecting the data type, add a semicolon character (;) to begin defining the desired format for the output value. The .NET formatting standards apply to this property as outlined below.

Below are some examples.

{{NamedRangeName:Decimal;C2}}

For NamedRangeName = 12, the formatted value will be $12.00.
For NamedRangeName = 1.2345561, the formatted value will be $1.23.
For NamedRangeName = 'ABC', the formatted value will be blank.

{{NamedRangeName:Decimal;P3}}

For NamedRangeName = 0.12, the formatted value will be 12.000%.
For NamedRangeName = 1.2345561, the formatted value will be 123.457%.
For NamedRangeName = 'ABC', the formatted value will be blank.

{{NamedRangeName:Decimal;00000}}

For NamedRangeName = 1234.5678, the formatted value will be 01235.
For NamedRangeName = 1.2345561, the formatted value will be 00001.
For NamedRangeName = 'ABC', the formatted value will be blank.

Predefined Formats

You can also use a predefined Numeric, or Date and Time Formatting as outlined below.

Integer (Input value: 1234)

{{ValueInteger:Integer;00}} => 1234
{{ValueInteger:Integer;#,##0}} => 1,234
{{ValueInteger:Integer;00000}} => 01234
{{ValueInteger:Integer;##-##}} => 12-34

Decimal (Input value: 123456.78)

{{ValueDecimal:Decimal;0.0}} => 123456.8
{{ValueDecimal:Decimal;0.00}} => 123456.78
{{ValueDecimal:Decimal;#,##0.0}} => 123,456.8
{{ValueDecimal:Decimal;#,##0.00}} => 123,456.78
{{ValueDecimal:Decimal;0.##}} => 123456.78
{{ValueDecimal:Decimal;00.00}} => 123456.78
{{ValueDecimal:Decimal;0,0.00}} => 123,456.78
{{ValueDecimal:Decimal;0%}} => 12345678%
{{ValueDecimal:Decimal;0.0%}} => 12345678.0%

Datetime (Input value: 12/05/2018 11:25:07 pm)

{{NamedRangeName:Datetime;yyyy}} => 2018
{{NamedRangeName:Datetime;MM}} => 12
{{NamedRangeName:Datetime;dd}} => 05
{{NamedRangeName:Datetime;yyyy/MM/dd}} => 2018/12/05
{{NamedRangeName:Datetime;MM/dd/yyyy}} => 12/05/2018
{{NamedRangeName:Datetime;dd/MM/yyyy}} => 05/12/2018
{{NamedRangeName:Datetime;HH}} => 23
{{NamedRangeName:Datetime;mm}} => 25
{{NamedRangeName:Datetime;ss}} => 07
{{NamedRangeName:Datetime;tt}} => PM
{{NamedRangeName:Datetime;HH:mm tt}} => 23:25 PM
{{NamedRangeName:Datetime;HH:mm:ss tt}} => 23:25:07 PM

Text

{{NamedRangeName:Text;None}} : None is an optional parameter
{{NamedRangeName:Text}} : Will work the same as above

While formats are Culture invariant when making a selection from the list, the values shown will be different for the current application Culture. For example #,##0.0 format will be shown as in "Thousands Comma Delimiter, Decimal Period Delimiter" Culture, but it will be shown as # ##0,0 for the "Thousands Space Delimiter, Decimal Comma Delimiter" Culture setting. Once you make a selection, the value will be inserted in the contents will be the same for all Cultures.

Inserting Stubs Using the Stubs Button

Clicking the Stubs button on the top right of the content editor will open the Insert Stub menu where you can add document stubs with the help of a graphical user interface.

On the Insert Stub menu, you can select a named range, type, and format to automatically add the stub corresponding to your selections. If you want to use text format you can click Pull format from Excel checkbox.

After selecting the named range, type and format properties, or selecting the named range field and clicking Pull format from Excel checkbox press the Insert Stub button to insert the stub text into the content editor.

Tooltip Position

The Tooltip Position property determines where the tooltip or popover will be positioned in respect to the target input.

If Auto is selected, the tooltip or popover position will be calculated automatically based on other parameters like the position of the target input, and content of the tooltip or popover.

Accepted File Types

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
PDF
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.

Maximum File Size

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.

Visible

The Visible property sets the conditions under which the gauge will be visible. This can be set to Always or Never.

If there are any Boolean Named Ranges (BNR) defined in your workbook (i.e. single named ranges that evaluate to TRUE or FALSE), then an additional option (By Value Of) will be available. This option allows you to configure a Boolean named range that determines whether or not this section is visible. This can either be calculated or input-based.

File Upload

Table of Contents