@boewa-software/react-async-uploader/README.md

React Uploder

React Async Uploader
====================

Dieses Packet stellt verschiedene React-Komponenten zur Umsetzung eines Asynchronen Clientseitigen Datei-Uplodas bereits. Intern wird hierfür die [resumable.js]-Komponente genutzt.

Hierfür wird eine Serverseitige API genutzt, die beispielsweise vom [BoewaAsyncUploadBundle] implementiert wird.

## Instalation
```bash
$ npm install --save @boewa-software/react-async-uploader
```


## Nutzung
Zur Nutzung, muss ein serverseitiger Endpunkt in form einer URL zum Verschicken der Dateien vorhanden sein.

### Alleinstehender Uploader
Um einen grundlegenden Uploader zu erzeugen, wird lediglich der Pfad zum Endpunkt benötigt (im Folgenden über `/endpoint-url` beschrieben).

Die Uploader-Kompnente kann beispielsweise eine DOM-Node ersetzten (hier exemplarisch über `targetElement`) beschrieben: 

````jsx harmony
import React from 'react';
import {createRoot} from "react-dom/client";

import {Uploader} from '@boewa-software/react-async-uploader';

// DOM-Node zum Einhängen der React-Komponente
const targetElement = document.getElementById("target-element");

const root = createRoot(targetElement);
root.render(
    <Uploader path={'/endpoint-url'} />
);
````

#### Darstellung überschreiben
Die Darstellung des Uploaders kann nach belibeben überschrieben werden, dafür muss eine React-Komponente implementiert werden, die das Layout definiert.

Die Layout-Komponente wird über das `component`-Property an den Uploader übergeben:

```jsx harmony
import React from 'react';
import {createRoot} from "react-dom/client";
import {Uploader, DropZone, BrowseButton} from '@boewa-software/react-async-uploader';

const CustomLayoutComponent = ({ uploads, assignDrop, assignBrowse }) =>
    <DropZone assignDrop={assignDrop}>
        Uploads: {uploads.length}
        <BrowseButton assignBrowse={assignBrowse}>
            Select File
        </BrowseButton>
    </DropZone>
;
const targetElement = document.getElementById("target-element");

const root = createRoot(targetElement);
root.render(
    <Uploader
        path={'/endpoint-url'}
        component={CustomLayoutComponent}
    />
);
````

Dabei können die Bereitstellten Komponenten zur Definition einer Drop-Zone (`DropZone`) und eines Browse-Buttons (`BrowseButton`) genutzt werden.

##### Übergebene Parameter
Die Layout-Komponente erhält vom Uploader die folgenden Parameter (props) zur Nutzung übergeben:

* uploaderState : `string`

  Aktueller Status des Uploaders mit den WerteN:
  
  * `running`: Es werden Dateien hochgeladen.
  * `paused`: Uploader ist Pausiert, Dateien werden erst nach dem Aufruf von `start` weiter hochgeladen.
  * `complete`: Der Uploader ist aktiv, es sind keine Dateien zum Upload in der Warteschlange.

* uploads : `uploadObject[]`

  Array aller aktuellen Uploads. Jedes dieser Opload-Objekte hat die folgenden Properties:
  
  * uniqueIdentifier : `string`
  
    Eindeutiger Identifier zur Zuordnung der Datei (erzeugt aus dem Dateinamen).
  
  * name : `string`
  
    Dateiname des Uploads
  
  * size : `integer`
  
    Dateigröße in Bytes.
  
  * progress : `float`
  
    Upload-Fortschritt.
  
  * uploading : `bool`
  
    Status, ob die Datei aktuell hochgeladen wird.
  
  * complete : `bool`
  
    Status, ob die Datei vollständig hochgeladen wurde.
  
  * error : `?mixed`
  
    Im Fehlerfall der vom Server zurückgemeldete Fehler.
  
  * responseContent : `?object`
  
    Vom Server zurückgemeldete Antwort im Erfolgsfall.
  
  * abort : `func`
  
    Funktion zum Abbrechen des Uplodas der Datei. Die Datei kann über `retry` erneut hochgleaden werden.
  
  * cancel : `func`
  
    Funktion zum Abbrechen des Uplodas der Datei. Die Datei wird aus der Warteschlange entfernt.
  
  * retry : `func`
  
    Im Fehlerfall oder beim Abbruch kann der Upload wiederholt werden.
  
* addFile : `func(HTML5File file)`

   Mauelles Hinzufügen eines [HTML5File-Objekts](https://developer.mozilla.org/de/docs/Web/API/File).

* assignDrop : `func(DOMNode node)`

   Registriert die DOMNode `node` als Drop-Zone.

* assignBrowse : `func(DOMNode node)`

  Registriert die DOMNode `node` als Browse-Button.

* start : `func`

  Aktiviert den Uploader.

* pause : `func`

  Pausiert den Uploader.

* reset : `func`

  Setzt den Uploader zurück.

Zusätzliche `props` für die Layout-Komponente können von außen über die `componentProps`-Option übergeben werden.

#### Uploder-Optionen
Der Uploader unterstüzt die folgenden Optionen (props):

* path : `string`

  URL zum Endpunkt des Servers, der die API implementiert.

* component : `func|React.Component` (optional)

  Layout-Komponente zur Darstellung.

* componentProps : `object` (optional)

  Zusätzliche `props` für die Layout-Komponente.

* autoStart : `boolean` (optional, default: `true`)

  Deaktiviert den automatischen Start des Uploads nach dem Hinzufügen einer Datei.

* clearFileOnSuccess : `boolean` (optional, default: `false`)

  Aktiviert, dass Dateien nach erfolgreichem Upload aus der Warteschlange entfernt werden.

* onUploaderComplete : `func` (optional)

  Callback, wenn alle Dateien hochgeladen wurden.

* onUploaderProgress : `func` (optional)

  Callback, wenn sich der Fortschritt ändert.

* onUploaderPause : `func` (optional)

  Callback, wenn der Uploader pausiert wird.

* onUploaderCancel : `func` (optional)

  Callback, wenn der Uploader zurückgesetzt wird.

* onFileAdded : `func(upload)`  (optional)

  Callback, wenn eine Datei zur Warteschlange hinzgefügt wird

* onFileProgress : `func(upload)` (optional)

  Callback, wenn sich der Upload-Fortschirtt einer Datei ändert.

* onFileSuccess : `func(upload)` (optional)

  Callback, wenn eine Datei erfolgreich hochgeladen wurde

* onFileError : `func(upload)` (optional)

  Callback, wenn der Upload einer Datei fehlgeschlagen ist.

* simultaneousUploads : `number` (optional, default: `1`)

  Limit für den gleichzeitigen Upload mehrerer Dateien.

* testChunks : `boolean` (optional, default: `true`)

  Deaktiviert die Prüfung, ob ein Chunk bereits hochgeladen ist. Verringert die anzahl an Requests, bei großen ggfs. abgebrochenen Uploads wird jedoch dann die gesamte Datei erneut hochgeladen.
 

### Uploader als Formular-Feld

Über die Komponenten `UploadInput` und `MultipleUploadsInput` können Formuar-Felder erzeugt werden, die einen erfolgten Upload an den Server vermelden.

Diese können mit den `AsyncUploadType` bzw. `MultipleAsyncUploadsType`-FormularTypen aus dem [BoewaAsyncUploadBundle] verknüpft weden.

Analog zum Uploader kann das Layout dieser Komponenten über das `component`-Property (ggfs. im Zusammenspiel mit `componentProps`) überschrieben werden:

```jsx harmony
import React from 'react';
import {createRoot} from "react-dom/client";
import {UploadInput} from '@boewa-software/react-async-uploader';

const InputComponent = ({ value }) => (
    <>
        {value
            ? `File: ${value}`
            : 'Upload File'
        }
        <input type={'hidden'} name={'upload_field'} value={value ? value.identifier : ''} />
    </>
);

const targetElement = document.getElementById("target-element");

const root = createRoot(targetElement);
root.render(
    <UploadInput
        path={'/endpoint-url'}
        component={InputComponent}
    />
);
```

Das Property `initialValue` empfängt den Initialwert mit den folgenden Pflicht-Attributen:

* identifier : `string`

  Unique Identifier der Datei
   
* name : `string`

  Dateiname
  
* progress : `number`
  
  Fortschritt des Uploads
  
* completed : `boolean`

  Attribut, ob der Upload erfolgreich war.

Die `MultipleUploadsInput`-Komponente emfängt für `initialValue` ein Array von Objekten dieses Typs.

### Weitere-Komponenten

#### `DropZone`
Diese Komponente ermöglicht die Erzeugung einer Drop-Zone für Uploads. Dafür muss der `assignDrop`-Callback des Uploaders an die Komponente übergeben werden.

#### `BrowseButton`
Diese Komponente ermöglicht die Erzeugung eines Browse-Buttons für Uploads. Dafür muss der `assignBrowse`-Callback des Uploaders an die Komponente übergeben werden.

### Weiterentwicklung und DEMO
Infos hierzu sind in der [Entwicklungs-Dokumentation](./docs/Development.md) zu finden.

[resumable.js]: https://github.com/23/resumable.js
[BoewaAsyncUploadBundle]: https://gitlab.boewa-software.de/boewa-software/async-upload-bundle