Nondeterministic Postrequisite Metaprotocol
Wondering what’s next for npm?Check out our public roadmap! »


3.3.2-rc.1 • Public • Published


Use to upload files


$ npm i --save @unicef-polymer/etools-upload


Polymer 3 component used for uploading files. When autoUpload is true and uploadEndpoint is set , it automatically uploads the file and returns an id stored in the fileUrl property.

Offline functionality

  • If the activateOffline attribute is set on the component, if there is no internet connection during the upload, the file is saved in local IndexedDb with a temp id.
  • The component expects window.Etools.AttachmentsDbName to be set from the parent application.
  • The IndexedDb is created on connectedCallback. If you need the db to exist prior to this you can call createAttachmentsDexie method directly from your code.
  • When the files have finished being saved in IndexedDb the same event as for online upload is fired - upload-finished. The event detail has the following format
    • {success:[{info about file}], error:[{error}]}
  • Any other extra information can be saved in IndexedDb along with the file by setting property endpointInfo.extraInfo :{} on the component.


  • <etools-upload>
  • <etools-upload-multi>

Resusable Methods

  1. dexie-operations file: Methods to interact with Dexie db

  2. upload-helper file exposes reusable methods that can upload files and receives a config object as param:

    • you can use upload method if you have the binary data of the file

    • uploadFileStoredInDexie gets a file stored in IndexedDb , uploads it then deletes it from IndexedDb

        Config param expected format:
        config = {
       		endpointInfo?:  {
       				endpoint: 'url',
       				extraInfo: {any: any},
       				rawFilePropertyName: 'attachment'
       		uploadEndpoint: '',
       		jwtLocalStorageKey?: ''



Upload component features

  1. label: text to be displayed on top of the control

  2. uploadBtnLabel: text to be displayed on the button, default is 'Upload file'

  3. accept: accepted file types (Ex: ".doc,.docx,.pdf,.jpg,.png")

  4. file-url: When a new file is uploaded and the upload has finished it holds the id of the file. After the id is saved on the entity for which the upload was made, it will hold the url to the file.

  5. upload-endpoint: url for the upload

  6. readonly: can be used as html attribute or polymer property (Ex: readonly$="[[!permissions.allowEdit]]"), enable/disable upload control

  7. required: can be used as html attribute or polymer property (Ex: required$="[[permissions.allowEdit]]"), specifies if control must be filled out

  8. auto-validate: if set to true and control is required validate if control is set

  9. error-message: custom text to be displayed on upload error

  10. auto-upload: if true it automatically upload the file after selection. default is true.

  11. endpointInfo: can be used to set any other information needed by the upload online or offline. If endpointInfo.endpoint is specified , uploadEndpoint is no longer needed.

    -  Expected format:
      endpoint: 'url',
      /** Any extra properties with their values, that need to be set in the FormData on the upload request */
      extraInfo: {any: any},
      /**The name of the field that will hold the binary data in the FormData on the upload request. If not specified it defaults to `file*/
      rawFilePropertyName: 'file'


  1. Download button will be displayed after uploaded file was saved
  2. show-delete-btn: if set to true, will display a 'Delete' button after file was selected, in order to be able to remove the file
  3. show-change: if set to true, will display a 'Change' button after file was selected, in order to be able to replace the file
  4. jwtLocalStorageKey specifies the local storage key where the token is stored. If window.AppMsalInstance is set , the component also checks the expiration of the token and silently refreshes it if needed.


  1. on-upload-started: triggered when upload started
  2. on-upload-finished: triggered when upload finished with the result of the action (information about the uploaded files) (Ex: {success: response} or {error: err}). This same event is triggered when offline and the files were saved in IndexedDb.
  3. on-change-unsaved-file: triggered on file selection if previous upload was not saved
  4. on-delete-file: triggered on file delete with the file url as parameter (Ex: {file: fileUrl})

Usage example

<etools-upload label="Upload Example" accept=".doc,.docx,.pdf,.jpg,.png" file-url="{{data.file_attachment}}" upload-endpoint="[[uploadEndpoint]]" on-upload-finished="_onUploadFinished" on-upload-started="_onUploadStarted" show-delete-btn="[[showDeleteBtn(data.status, data.permissions.allowEdit)]]" on-delete-file="_onAttachDelete" accept=".doc,.docx,.pdf,.jpg,.png" readonly$="[[!data.permissions.allowEdit]]" required$="[[data.attach_required]]" auto-validate on-change-unsaved-file="_onChangeUnsavedFile">

Install the Polymer-CLI

First, make sure you have the Polymer CLI installed. Then run polymer serve to serve your element locally.

Viewing Your Element

$ polymer serve

Running Tests

$ polymer test

Your application is already set up to be tested via web-component-tester. Run polymer test to run your application's test suite locally.




npm i @unicef-polymer/etools-upload

DownloadsWeekly Downloads






Unpacked Size

52.1 kB

Total Files


Last publish


  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar