Skip to content

FileList

FileList binds a collection of file references to one form field. Use it when users must attach several files without adding a separate table or repeating form section. Use File or ImageUpload for a single value.

XML Fields

Field Meaning
XPath Selects the collection container. It does not select one file item.
ItemXPath Child element containing the XPath for repeating file items. Defaults to File; it is not an XML attribute.
MaxFiles Client-side limit on selected files; 0 means no additional widget limit.
NameXPath Optional file-name path evaluated relative to each file item. Empty uses that item's Caption attribute.
Accept Comma-separated extensions or MIME types used by client selection, such as .pdf,image/*.
RequiredForGroup Requires at least one nondeleted file item with a nonempty value other than 0 for the matching group.

FileList also inherits File's template data sources, hints, rules, and editing settings. Accept and MaxFiles are client controls; enforce business-specific restrictions on the server where required. The server's file policy and permissions apply independently.

1
2
3
<FileList XPath="Attachments" MaxFiles="5" Accept=".pdf,image/*" RequiredForGroup="Save">
    <ItemXPath><![CDATA[File]]></ItemXPath>
</FileList>

Data Model

The container holds repeating forms:File elements. Each item uses the same scalar representation as a File field: its text is a file ID, with file-name, URL, and revision attributes on that item.

1
2
3
4
<Attachments>
    <File Caption="Proposal.pdf">11111111-1111-4111-8111-111111111111</File>
    <File Caption="Drawing.png">22222222-2222-4222-8222-222222222222</File>
</Attachments>

A replacement can keep the item's canonical file ID and store the new upload ID in its Revision attribute. Each item has its own revision state. Replacing one item does not replace the collection or change the other file items.

For a custom item name, change both the data model's repeating element and ItemXPath. Keep NameXPath relative to the item; unlike a scalar File field, it is not evaluated from the item's parent.

Designer and Runtime Behavior

Creating a FileList through the designer creates a collection container and a repeating forms:File child, using the chosen item name. An existing compatible complex field must contain a repeating file child. A scalar file field is not a FileList collection.

The compact form control displays a file count. Selecting it opens the attachment list. The selection window supports batch selection and Add Selected Files; replacement of an individual item remains a single-file operation. Existing selections count toward MaxFiles.

File and ImageUpload remain scalar widgets. Do not add Multiple, ItemXPath, or MaxFiles to their definitions to create a collection; introduce a FileList and the matching data-model structure explicitly.