File handling web components

You can install these components via npm:

npm i @dbp-toolkit/file-handling

After you have installed the file handling components via npm you can use this example to get a button that opens the file source dialog. After you have selected a file you will see it in your browser log, and the file sink dialog will open, so you are able to store the file again.

<button onclick="openFilePicker()">Open file picker</button>
<dbp-file-source lang="en"></dbp-file-source>
<dbp-file-sink lang="en"></dbp-file-sink>

<script>
    const fileSource = document.querySelector("dbp-file-source");
    const fileSink = document.querySelector("dbp-file-sink");

    // Listen to the event from file source
    fileSource.addEventListener("dbp-file-source-file-selected", (ev) => {
        const file = ev.detail.file;
        console.log("File selected: ", file)

        // This will open the file sink dialog
        fileSink.files = [file];
    }); 

    function openFilePicker() {
        // This will open the file source dialog
        fileSource.setAttribute("dialog-open", "");
    }
</script>
<script type="module" src="node_modules/@dbp-toolkit/file-handling/dist/dbp-file-source.js"></script>
<script type="module" src="node_modules/@dbp-toolkit/file-handling/dist/dbp-file-sink.js"></script>

Or you can include the JS files directly via CDN:

<script type="module" src="https://unpkg.com/@dbp-toolkit/file-handling@0.2.5/dist/dbp-file-source.js"></script>
<script type="module" src="https://unpkg.com/@dbp-toolkit/file-handling@0.2.5/dist/dbp-file-sink.js"></script>
<script type="module" src="https://unpkg.com/@dbp-toolkit/file-handling@0.2.5/dist/dbp-clipboard.js"></script>

FileSource

This web component allows the selection of local files via file dialog or drag and drop and to select and download files from a Nextcloud instance or to a dbp-clipboard.

Usage

<dbp-file-source></dbp-file-source>

Attributes

• lang (optional, default: de): set to de or en for German or English
  • example <dbp-file-source lang="de"></dbp-file-source>
• allowed-mime-types (optional): if set accepts only files matching mime types
  • example <dbp-file-source allowed-mime-types='application/pdf'></dbp-file-source> ... PDFs only
  • example <dbp-file-source allowed-mime-types='image/*'></dbp-file-source> ... images (of all sub types) only
  • example <dbp-file-source allowed-mime-types='image/png,text/plain'></dbp-file-source> ... PNGs or TXTs only
  • example <dbp-file-source allowed-mime-types='*/*'></dbp-file-source> ... all file types (default)
• enabled-targets (optional, default: local): sets which sources are enabled
  • you can use local, nextcloud and clipboard
  • example <dbp-file-source enabled-targets="local,nextcloud"></dbp-file-source>
• disabled (optional): disable input control
  • example <dbp-file-source disabled></dbp-file-source>
• decompress-zip (optional): decompress zip file and send the contained files (including files in folders)
  • example <dbp-file-source decompress-zip></dbp-file-source>
  • mime types of allowed-mime-types will also be checked for the files in the zip file
• nextcloud-auth-url (optional): Nextcloud Auth Url to use with the Nextcloud file picker
  • example <dbp-file-source nextcloud-auth-url="http://localhost:8081/index.php/apps/webapppassword"></dbp-file-source>
  • nextcloud-web-dav-url also needs to be set for the Nextcloud file picker to be active
• nextcloud-web-dav-url (optional): Nextcloud WebDav Url to use with the Nextcloud file picker
  • example <dbp-file-source nextcloud-web-dav-url="http://localhost:8081/remote.php/dav/files"></dbp-file-source>
  • nextcloud-auth-url also needs to be set for the Nextcloud file picker to be active
• nextcloud-file-url (optional): Nextcloud File Url to use with the Nextcloud file picker
  • example <dbp-file-source nextcloud-file-url="http://localhost:8081/apps/files/?dir="></dbp-file-source>
• nextcloud-auth-info (optional): Additional authentication information text that is shown in the Nextcloud file picker
  • example <dbp-file-source nextcloud-auth-info="You need special permissions for this function"></dbp-file-source>
• dialog-open (optional): if this attribute is set at runtime the dialog for selecting local or Nextcloud files will open
  • example document.querySelector("dbp-file-source").setAttribute("dialog-open", "")
• button-label (optional): the text that is shown on the button to select files
  • example <dbp-file-source button-label="Select files"></dbp-file-source>
• initial-file-handling-state (optional): An object: initial-file-handling-state' = {target: "", path: ""} for initial opening behaviour. This is supported by the provider! Use this object to sync file source and file sink on one page at first time open.
  • example <dbp-file-source initial-file-handling-state="{target: 'local', path:'my/server/path'}"></dbp-file-source>
  • example provider <dbp-file-source subscribe="initial-file-handling-state"></dbp-file-source>

Emitted attributes

The component emits a dbp-set-property event for the attribute initial-file-handling-state:

• initial-file-handling-state.target: Target that should be selected the first time (possible values local, nextcloud)
• initial-file-handling-state.path: Path to initially jump to (only supported by target nextcloud)

Outgoing Events

dbp-file-source-file-selected

This event is sent if a file was selected.

dbp-file-source-file-upload-finished

This event is sent if multiple files are selected.

dbp-nextcloud-file-picker-number-files

This event is sent from nextcloudfilepicker and is send when files are picked and sends the number of selected files

Payload: {'file': File} where File is the binary file that was selected

Exposed CSS variables

• --dbp-override-image-nextcloud is used to override the cloud image on the connection screen
  • example CSS: html { --dbp-override-image-nextcloud: url(/icons/nextcloud.svg); }

FileSink

This web component is able to receive files and present as them as ZIP file download or upload files to a Nextcloud instance or to a dbp-clipboard.

Usage

<dbp-file-sink></dbp-file-sink>

Attributes

• lang (optional, default: de): set to de or en for German or English
  • example <dbp-file-sink lang="de"></dbp-file-sink>
• enabled-targets (optional, default: local): sets which destination are enabled
  • you can use local, nextcloud and clipboard
  • example <dbp-file-sink enabled-targets="local,nextcloud"></dbp-file-sink>
• filename (optional, default: files.zip): sets a file name to use for downloading the zip file
  • example <dbp-file-sink filename="signed-documents.zip"></dbp-file-sink>
• nextcloud-auth-url (optional): Nextcloud Auth Url to use with the Nextcloud file picker
  • example <dbp-file-sink nextcloud-auth-url="http://localhost:8081/index.php/apps/webapppassword"></dbp-file-sink>
  • nextcloud-web-dav-url also needs to be set for the Nextcloud file picker to be active
• nextcloud-web-dav-url (optional): Nextcloud WebDav Url to use with the Nextcloud file picker
  • example <dbp-file-sink nextcloud-web-dav-url="http://localhost:8081/remote.php/dav/files"></dbp-file-sink>
  • nextcloud-auth-url also needs to be set for the Nextcloud file picker to be active
• nextcloud-file-url (optional): Nextcloud File Url to use with the Nextcloud file picker
  • example <dbp-file-sink nextcloud-file-url="http://localhost:8081/apps/files/?dir="></dbp-file-sink>
• nextcloud-auth-info (optional): Additional authentication information text that is shown in the Nextcloud file picker
  • example <dbp-file-sink nextcloud-auth-info="You need special permissions for this function"></dbp-file-sink>
• button-label (optional): the text that is shown on the button to download the zip file
  • example <dbp-file-sink button-label="Download files"></dbp-file-sink>
• initial-file-handling-state (optional): An object: initial-file-handling-state' = {target: "", path: ""} for initial opening behaviour. This is supported by the provider! Use this object to sync file source and file sink on one page at first time open.
  • example <dbp-file-source initial-file-handling-state="{target: 'local', path:'my/server/path'}"></dbp-file-source>
  • example provider <dbp-file-source subscribe="initial-file-handling-state"></dbp-file-source>

Emitted attributes

The component emits a dbp-set-property event for the attribute initial-file-handling-state:

• initial-file-handling-state.target: Target that should be selected the first time (possible values local, nextcloud)
• initial-file-handling-state.path: Path to initially jump to (only supported by target nextcloud)

Properties

• files: an array of File objects which should be downloaded in the dialog
  • if the property is set the dialog opens
  • example: document.querySelector("dbp-file-sink").files = [file] where file is your File object

Exposed CSS variables

• --dbp-override-image-nextcloud is used to override the cloud image on the connection screen
  • example CSS: html { --dbp-override-image-nextcloud: url(/icons/nextcloud.svg); }

Clipboard

This web component is for a clipboard which saves the files to a provider. These files are available till the page is reload or the browser is closed.

Depencencies

This web component can only used if a dbp-provider is around it.
This web component depends on:

• dbp-file-sink
• dbp-file-source

Usage

<dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name">
</dbp-clipboard>

Attributes

• clipboardFiles is the object which should be subscribed to the provider to recieve and send the clipboard files to the provider.
  • exmaple <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name"></dbp-clipboard>
• lang (optional, default: de): set to de or en for German or English
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" lang="de"></dbp-clipboard>
• enabled-targets (optional, default: local): sets which destination are enabled
  • you can use local and nextcloud
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" enabled-targets="local,nextcloud"></dbp-clipboard>
• allowed-mime-types (optional): if set accepts only files matching mime types
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" allowed-mime-types='application/pdf'></dbp-clipboard> ... PDFs only
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" allowed-mime-types='image/*'></dbp-clipboard> ... images (of all sub types) only
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name"e allowed-mime-types='image/png,text/plain'></dbp-clipboard> ... PNGs or TXTs only
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" allowed-mime-types='*/*'></dbp-clipboard> ... all file types (default)
• mode (optional, default: MODE_TABLE_ONLY): the clipboard can used in three different contexts: only showing the clipboard content, in the file-source context and in the file-sink context.
  • you can use MODE_TABLE_ONLY, MODE_FILE_SINK or MODE_FILE_SOURCE
  • example <dbp-clipboard mode="MODE_TABLE_ONLY></dbp-clipboard> ... only the table will shown
  • example <dbp-clipboard mode="MODE_FILE_SINK></dbp-clipboard> ... the file-sink text and functionality is turned on
  • example <dbp-clipboard mode="MODE_FILE_SOURCE></dbp-clipboard> ... the file-source text and functionality is turned on
• filesToSave this attribute is used by the dbp-file-sink to set the files in an array, which should be saved to the clipboard to the dbp-clipboard web component
• allow-nesting (optional): is an boolean for demo purposes or special use cases. It availables the clipboard in the file-source and file-sink in the clipboard itself.
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" allow-nesting></dbp-clipboard> ... all file types (default)
• nextcloud-auth-url (optional): Nextcloud Auth Url to use with the Nextcloud file picker
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" nextcloud-auth-url="http://localhost:8081/index.php/apps/webapppassword"></dbp-clipboard>
  • nextcloud-web-dav-url also needs to be set for the Nextcloud file picker to be active
• nextcloud-web-dav-url (optional): Nextcloud WebDav Url to use with the Nextcloud file picker
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" nextcloud-web-dav-url="http://localhost:8081/remote.php/dav/files"></dbp-clipboard>
  • nextcloud-auth-url also needs to be set for the Nextcloud file picker to be active
• nextcloud-file-url (optional): Nextcloud File Url to use with the Nextcloud file picker
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" nextcloud-file-url="http://localhost:8081/apps/files/?dir="></dbp-clipboard>
• nextcloud-auth-info (optional): Additional authentication information text that is shown in the Nextcloud file picker
  • example <dbp-clipboard subscribe="clipboard-files:clipboard-files-global-name" nextcloud-auth-info="You need special permissions for this function"></dbp-clipboard>

Exposed CSS variables

• --dbp-override-image-nextcloud is used to override the cloud image on the connection screen
  • example CSS: html { --dbp-override-image-nextcloud: url(/icons/nextcloud.svg); }

Local development

# get the source
git clone git@gitlab.tugraz.at:dbp/web-components/toolkit.git
cd toolkit/packages/file-handling

# install dependencies
yarn install

# constantly build dist/bundle.js and run a local web-server on port 8002 
yarn run watch-local

# build local packages in dist directory
yarn run build

Jump to http://localhost:8002 and you should get a demo page.

To use the Nextcloud functionality you need a running Nextcloud server with the webapppassword Nextcloud app like this Nextcloud Development Environment.