Attachment¶
This container item allows users to add or take a photo as an attachment.
When assigning a rule to a property of Attachment, the rule will be passed an instance of the following proxy class as an argument:
Attachment Properties¶
| Property | Type | Required | Default |
|---|---|---|---|
| AllowedFileTypes | string[] |
No | |
| AttachmentActionType | enum[] |
Yes | |
| AttachmentAddTitle | string |
No | "Add" |
| AttachmentCancelTitle | string |
No | "Cancel" |
| AttachmentTitle | string |
No | "Attachments (%d)" |
| HelperText | string |
No | |
| IsEditable | boolean |
No | true |
| IsVisible | boolean |
No | true |
| MaxAttachments | integer |
No | |
| MaxFileSize | number |
No | |
| OnPress | ActionOrRule | No | |
| OnValueChange | ActionOrRule | No | |
| RequiredIndicator | BooleanOrString | No | false |
| Separator | boolean |
No | true |
| Styles | object |
No | |
| Validation | Validation | No | |
| Value | object[] |
No | |
| _Name | string |
Yes | |
| _Type | const |
Yes | |
| validationProperties | ValidationProperties | No |
AllowedFileTypes¶
List of file types which can be uploaded. Only applicable when AttachmentActionType is SelectFile.
Refer to Android file types and iOS file types for details.
If the customized file types are not supported by Android or iOS, you can assign an empty array, i.e. [], to allow choosing all files.
In iOS, since odt, docx, xlsx and pptx are all actually contained in a zip file wrapper, they also conform to 'zip' format. So, when you specify 'zip' in the list, it also includes all other types that conform to 'zip' format.
- type:
string[]
All items must be of the type: string
AttachmentActionType¶
List of supported attachment types.
- type:
enum[]
| Value | Description |
|---|---|
AddPhoto |
Only supported on iOS and Android |
TakePhoto |
Only supported on iOS and Android |
SelectFile |
Supported on iOS, Android and Web |
All items must be of the type: string
AttachmentAddTitle¶
Title string for the add attachment popover. Android / web only.
- type:
string - default:
"Add"
AttachmentCancelTitle¶
iOS compact mode (phone) only. Title string for the cancel button on the add attachment popover.
- type:
string - default:
"Cancel"
AttachmentTitle¶
String for the attachment header. Parameterized strings are accepted as well, e.g. 'Photos [%d]', where the parameter is substituted by the number of attachments.
- type:
string - default:
"Attachments (%d)"
HelperText¶
Helper text to be displayed if there is no validation view.
- type:
string
IsEditable¶
MDK now supports restricting attachment management within a FormCell Attachment control. When disabled, the control automatically hides the Add button as well as the Remove (or delete) option for each attachment. This is applicable to iOS and Android only.
- type:
boolean - default:
true
IsVisible¶
Sets the visibility of the control.
- type:
boolean - default:
true
MaxAttachments¶
You can now configure FormCell Attachment control to restrict how many attachments a user can upload. Once the specified limit is reached, the control disables the Add button to prevent further uploads.
- If the property is not configured—or is set to zero or a negative value—no limit is enforced by default.
-
Platform behavior:
- iOS: The limit is applied directly to the native file picker, which prevents additional file selection once the maximum is reached.
- Android: The native file picker does not restrict selection. Users may select more files than allowed, but only the first N attachments (where N is the configured limit) are retained after confirmation.
- type:
integer
MaxFileSize¶
The maximum file size (in megabytes) allowed for each attachment added to the FormCell Attachment control. If not specified, or set to a value less than or equal to 0, no file size limit is enforced.
- type:
number
OnPress¶
Action/Rule to be triggered when the existing attachment is pressed. This event is supported only on mobile platforms.
The clientAPI in rule function is object with AttachmentEntryProxy definition.
The action binding information from page proxy is stored pressed attachment object with the interface IAttachment and index of the pressed attachment item.
- type: ActionOrRule
- Formatter and Binding are not supported
OnValueChange¶
Action or rule to perform after a new attchment is added or an existing attachment is deleted.
- type: ActionOrRule
- Formatter and Binding are not supported
RequiredIndicator¶
Specifies whether a field is mandatory by displaying a visual indicator. This property accepts either a Boolean (true / false) or a single character (e.g., '!') as its value.
By default, the indicator is a red asterisk (*) displayed at the end of the field's caption. You can customize the indicator character by setting this property. Additionally, the appearance (e.g., color or size) can be styled through metadata as well.
Note:
- This indicator is purely visual—it does not enforce that the user must fill out the field.
- If more than one character is defined, the system will revert to using the default indicator.
- type: BooleanOrString
- default:
false
Separator¶
Sets the visibility of the separator line below the control. This property will take precedence over ControlSeparator
in section and is only supported for Form Cell control in Sectioned Table and not supported in Form Cell Container.
- type:
boolean - default:
true
Styles¶
Set styles for Background.
- type:
objectwith following properties.
| Property | Type | Required | Default |
|---|---|---|---|
| Background | string | No | |
| RequiredIndicator | string | No |
Background¶
The string value is a style class name of Background.
- Background style class
RequiredIndicator¶
The string value is a style class name of RequiredIndicator.
- RequiredIndicatorColor style class
Validation¶
The validation view properties.
- type: Validation
Value¶
List of resources which are to be added by default. Each item is in accordance with the interface IAttachment definition.
- type:
object[]
_Name¶
- type:
string
_Type¶
- type:
const
The value of this property must be:
"Control.Type.FormCell.Attachment"
validationProperties¶
Deprecated. Please use Validation property. The validation view properties.
- type: ValidationProperties
Android Platforms File Types List¶
| Android Version |
|---|
| 9.0 |
| 8.1 |
| 8.0 |
| 7.1.1 |
| 7.0 |
| 6.0 |
Examples¶
// Attachment Form Cell metadata
{
"_Type": "Page",
"_Name": "FormCellsPage",
"Caption": "FormCell Example",
"Controls": [{
"_Type": "Control.Type.FormCellContainer",
"_Name": "FormCellContainer",
"Sections": [{
"Caption": "Section",
"Controls": [{
"_Type": "Control.Type.FormCell.Attachment",
"_Name": "AttachmentFormCell",
"AttachmentTitle": "Photos [%d]",
"AttachmentAddTitle": "Add photos",
"AttachmentCancelTitle": "No!",
"AttachmentActionType": ["AddPhoto", "TakePhoto", "SelectFile"],
"AllowedFileTypes": [ "jpg", "png", "gif" ],
"MaxFileSize": 1,
"OnValueChange": "/MyMDKApp/Actions/ShowMessage.action",
"RequiredIndicator": true,
"Styles": {
"Background": "AttachmentFormCellBackground",
"RequiredIndicator": "RequiredIndicatorColor"
},
"Validation": {
"Message": "This is validation view message",
"Visible": true,
"SeparatorVisible": true,
"Styles": {
"Message": "ValidationMessage",
"ValidationView": "ValidationView"
}
}
}]
}]
}]
}
Set attachment Value from a Rule and OnPress event handler¶
// Attachment Form Cell metadata
{
"_Type": "Page",
"_Name": "FormCellsPage",
"Caption": "FormCell Example",
"Controls": [{
"Sections": [{
"_Type": "Control.Type.FormCellContainer",
"_Name": "FormCellContainer",
"Caption": "Section",
"Controls": [{
"_Type": "Control.Type.FormCell.Attachment",
"_Name": "AttachmentFormCell",
"AttachmentTitle": "Photos [%d]",
"AttachmentAddTitle": "Add photos",
"AttachmentCancelTitle": "No!",
"AttachmentActionType": ["AddPhoto", "TakePhoto", "SelectFile"],
"Value": "/MyMDKApp/Rules/InitializeAttachments.js",
"AllowedFileTypes": ["jpg", "png", "gif"],
"OnValueChange": "/MyMDKApp/Actions/ShowMessage.action",
"OnPress": "/MyMDKApp/Rules/AttachmentOnPress.js"
}]
}]
}]
}
// set local attachments to Value property
// InitializeAttachments.js
function InitializeAttachments(formcellProxy) {
var serviceName = '/MyMDKApp/Services/Amw.service';
var entitySet = 'Images';
var queryOption = '$top=1'
var promises = [];
var attachmentData = [];
return formcellProxy.read(serviceName, entitySet, [], queryOption).then(function (attachments) {
attachments.forEach(function (attachmentObject) {
var documentObject = attachmentObject.Document;
var readLink = documentObject['@odata.readLink'];
var entitySet = readLink.split('(')[0];
promises.push(formcellProxy.isMediaLocal(serviceName, entitySet, readLink).then(function (isMediaLocal) {
return [isMediaLocal, documentObject];
}));
});
return Promise.all(promises).then(function (results) {
results.forEach(function (result) {
var isMedialLocal = result[0];
var attachment = result[1];
if (isMedialLocal && !attachment.FileSize) {
var entitySet = 'Documents';
var property = 'Document';
var readLink = attachment['@odata.readLink'];
var service = '/MyMDKApp/Services/Amw.service';
var documentPath = attachment.path;
var attachmentEntry = formcellProxy.createAttachmentEntry(documentPath, entitySet, property, readLink, service);
if (attachmentEntry) {
attachmentData.push(attachmentEntry);
}
}
});
return attachmentData;
});
});
}
// on press event handler for existing attachment
// AttachmentOnPress.js
import { ImageSource, knownFolders, path } from '@nativescript/core';
// clientAPI is instance of AttachmentEntryProxy
export default function AttachmentOnPress(clientAPI) {
// get action binding information
const binding = clientAPI.getPageProxy().getActionBinding();
if (binding.index === 0) {
// execute the default open behaviour
clientAPI.open();
} else if (binding.index === 1) {
ImageSource.fromResource("download_icon").then((imageSource) => {
const folderPath = knownFolders.documents().path;
const fileName = "test.png";
const filePath = path.join(folderPath, fileName);
const saved = imageSource.saveToFile(filePath, "png");
if (saved) {
console.log("Image saved successfully!");
}
let newAttachmentEntry = clientAPI.createAttachmentEntry(filePath, binding.entitySet, binding.property, binding.readLink, binding.service);
// replace to the new file
clientAPI.setValue(newAttachmentEntry, false);
setTimeout(() => {
// execute the default open behaviour
clientAPI.open();
}, 1000);
});
} else if (binding.index === 2) {
clientAPI.executeAction('/MyMDKApp/Actions/Popover/Popover.action');
} else {
alert(clientAPI.getIndex() + '\n' + clientAPI.getValue().urlString);
}
}
Style Classes Definition¶
/* Attachment Form Cell - Background */
.AttachmentFormCellBackground {
background-color: yellow;
}
/* Validation view */
.ValidationView {
background-color: #83AF9B;
border-top-color: #ff00ee;
}
/* Validation message */
.ValidationMessage {
font-size: 16;
font-color: #0000ff;
}
/* Required indicator's color - font-color / color can be used */
.RequiredIndicatorColor {
font-color: blue;
}