Show TOC

Upload CollectionLocate this document in the navigation structure

Upload Collection is a list control for attachment management that provides the ability to upload, edit or delete attachments.

The UploadCollection control allows users to upload single or multiple files from their devices (desktop PC, tablet or phone) to an app. Due to its responsiveness, the upload collection can be used in containers of different sizes .

Overview

You can use the UploadCollection control to show a list of files, for example, attachments or uploads, that can be modified, or you can allow users to add or remove files to or from this list.

The UploadCollection control can be used in two different scenarios:

  • Instant Upload

    This scenario allows users to upload single or multiple files from their devices (desktop, PC, tablet, or smartphone) and attach them to the application immediately. The selection and upload process is completed in one step and is automatically triggered by the UploadCollection control.

  • Upload Pending

    With this UploadCollection scenario, you can select attachments and add them to the upload list (multiple selection is possible). You can cancel the upload of one file in this selection without canceling the upload of the other selected files. In a second step, you can upload the selected files. The application triggers the upload with an event.

The following features are available:

  • Upload files

    The upload is triggered by the Add pushbutton (plus icon). Afterwards the OS-native file picker dialog appears and you can select one or multiple files. However, the consuming application need to enable the upload of multiple files by using the multiple property during the instantiation. During the upload process, a progress indicator provides information about the status.

  • Open files

    To open a listed file, you can choose the icon or thumbnail of the attachment as well as the filename itself. Depending on the file extension, browser capabilities, and device type (PC or mobile), the file is handled differently, for example, it is opened in a new tab or downloaded, if no display capability is available in the browser.

  • Rename files

    Choosing on the Rename pushbutton (pen icon) turns the file name into an input field and allows modification. You can confirm the renaming by choosing the OK or cancel by choosing Cancel. If the sameFilenameAllowed property is set to true, the new file name is validated and, if the file name already exists in the current list, an error occurs, which indicates that you need to change the file name.

  • Delete files

    You can delete files by using the Delete pushbutton (x icon with a circle). After choosing the Delete pushbutton, a dialog appears, asking the user to confirm the deletion of the respective file that removes the file from the list.

  • Download files

    In the Instant Upload scenario, you can download a file item from the Upload Collection list and save it on your device or desktop. For example, you can provide a Downloadbutton in the header, and once you marked one of the items the download feature can be used. To use this feature, new API methods have been added, one to the UploadCollection control and the other one to the UploadCollectionItem control. Using the askForLocation parameter, in both cases you can configure that the browser should ask for the location where to store the file or not (depending on the browser). When this parameter is set to false, the download method acts in the same way as when clicking on the file link. If the askForLocation parameter is set to true, the browser opens a Save As dialog.

Layout

For an overview of how the uploaded files are listed, see the UploadCollection control on the Explored tab in the Demo Kit.

  • The two pushbuttons Rename and Delete that are displayed for each item are active and visible by default. However, both icons can be set to invisible or inactive. For more information, see the UploadCollection control on the API Reference tab in the Demo Kit.

  • While most file types have generic icons (such as Word documents, Excel sheets, PDFs, and so on), graphic files can be displayed with a small thumbnail preview of its graphic if the respective URL is provided.

  • The header toolbar of the UploadCollection control can be customized.

    • To customize the toolbar, the aggregation toolbar can be set to the sap.m.OverflowToolbar control which can contain your preferred UI5 controls. To make the position of the upload (+) button configurable, the new sap.m.UploadCollectionToolbarPlaceholder type was introduced. To configure the position of the button, you can set the placeholder element to the desired position.

    • If the toolbar is not customized it only provides the upload (+) button.
    • In case the customizable toolbar has been configured and the placeholder is missing, an exception will be thrown.

  • The mode property of the UploadCollection control can be set. Therefore the sap.m.ListMode type was introduced.

    • The listmode Delete is not supported and will be set to listmode None if used.

    • Also the listmode MultiSelect is not supported in case of an Upload Pending scenario of the UploadCollection control is used, in this case it will be set to listmode None automatically

Constraints and Dependencies

By using the UploadCollection control, you need to be aware of the following constraints:

  • The UploadCollection control does not work with IE9 because of a missing header parameter handling needed for the upload.

  • The file name of an upload item can contain any text and special characters but not a URL.

The sap.m.UploadCollection control uses the sap.ui.unified.FileUploader control and contains dependencies to this control. If you want to use the UploadCollection control, you need to be aware of these dependencies. For more information, see the FileUploader control on the API Reference tab in the Demo Kit.