# File handling web components

You can install these components via npm:

```bash
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.

```html
<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:

```html
<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](https://nextcloud.com/) instance or to a dbp-clipboard.

### Usage

```html
<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](https://developer.mozilla.org/en-US/docs/Web/API/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](https://nextcloud.com/) instance or to a dbp-clipboard. 

### Usage

```html
<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](https://developer.mozilla.org/en-US/docs/Web/API/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.<br>
This web component depends on:
- `dbp-file-sink`
- `dbp-file-source`

### Usage

```html
<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); }`

## Nextcloud file picker

The `dbp-nextcloud-file-picker` component is currently used by the file sink, file source and
clipboard components. There is a slot you can use to override to provide additional information.

### Slots

You use template tags to inject slots into the web component.
These templates will be converted to div containers when the page is loaded and will not show up before that.

#### auth-info

The content of this slot will be shown below the other text on the Nextcloud file picker connection page.

Example:

```html
<dbp-nextcloud-file-picker lang="de">
  <template slot="auth-info">
    <dbp-translated subscribe="lang">
      <div slot="de">
        Für diese Funktion ist ein Bediensteten Account nötig!
      </div>
      <div slot="en">
        An employee account is required for this function!
      </div>
    </dbp-translated>
  </template>
</dbp-nextcloud-file-picker>
```

Most likely you will override this slot across more webcomponents.

Example for `dbp-file-sink`:

```html
<dbp-file-sink lang="de" html-overrides="global-override"></dbp-file-sink>

<template id="global-override">
  <template id="dbp-nextcloud-file-picker">
    <div slot="auth-info">
      <dbp-translated subscribe="lang">
        <div slot="de">
            Für diese Funktion ist ein Bediensteten Account nötig!
        </div>
        <div slot="en">
            An employee account is required for this function!
        </div>
      </dbp-translated>
    </div>
  </template>
</template>
```

## Local development

```bash
# 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](https://gitlab.tugraz.at/dbp/nextcloud/webapppassword) Nextcloud app like this
[Nextcloud Development Environment](https://gitlab.tugraz.at/dbp/nextcloud/webapppassword/-/tree/master/docker).