Newer
Older
Bekerle, Patrizio
committed
# File handling web components
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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>
```
Bekerle, Patrizio
committed
## 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.
Bekerle, Patrizio
committed
### Usage
<dbp-file-source></dbp-file-source>
Bekerle, Patrizio
committed
### 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)
Bekerle, Patrizio
committed
- `enabled-targets` (optional, default: `local`): sets which sources are enabled
- you can use `local`, `nextcloud` and `clipboard`
Bekerle, Patrizio
committed
- example `<dbp-file-source enabled-targets="local,nextcloud"></dbp-file-source>`
- `disabled` (optional): disable input control
- example `<dbp-file-source disabled></dbp-file-source>`
Bekerle, Patrizio
committed
- `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", "")`
Bekerle, Patrizio
committed
- `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>`
Bekerle, Patrizio
committed
- `enabled-targets` (optional, default: `local`): sets which destination are enabled
- you can use `local`, `nextcloud` and `clipboard`
Bekerle, Patrizio
committed
- example `<dbp-file-sink enabled-targets="local,nextcloud"></dbp-file-sink>`
Bekerle, Patrizio
committed
- `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>`
Bekerle, Patrizio
committed
- `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`)
Bekerle, Patrizio
committed
### Properties
- `files`: an array of [File](https://developer.mozilla.org/en-US/docs/Web/API/File) objects which should be downloaded in the dialog
Bekerle, Patrizio
committed
- 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>
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
```
### 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); }`
# 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).