= UZ
== TL;DR
`git clone https://github.com/js29a/uz.git` or grab source:/uz/src/UploadZone.vue@cc1db11 and source:/uz/src/UploadTest.vue@cc1db11
== Aim of this article
In this article I'm about to demonstrate how to create and use generic file uploader component. You can use it not only with bare Vue-3 but also with Quasar, Vuetify or other Vue-3 toolkit. This article describes only browser-side concerns. You need to provide server side by you own.
The repository is also mirrored on !GitHub.
== Prerequisites
To use code covered by this wiki pages you need to have following skills:
* basic Vue-3 knowledge (especially SFC),
* very basic POST knowledge,
* rudimental knowlegde of jQuery `ajax` command.
== General info
Described component is based on a simple state machine. It has no UI by itself so you need to provide some UI on your own. To accomplish this not only component instantation is needed but there is also need to fill its //slots//. The component has several config options from which actually only one needs to be provided (i.e. target upload URL). Other options control component behavior but they will be explained later. After providing target upload URL there is need to fill component slots by your own UI. Here I will describe generic browser UI only. If you are familiar with e.g. Quasar you can implement the UI on your own.
== Basic component usage
The first thing you need to do is to import the component and create an instance of it. Place the following line in your code - be careful to specifiy correct relative component path:
{{{#!typescript
import UploadZone from './UploadZone.vue';
}}}
Then at your template code instantiate it. You will have to specify correct //target upload URL//. Endpoint specified here should handle POST requests.
{{{#!twig
}}}
As you see nothing will appear in browser. Why? You need to provide some UI. To remain generic the component has no UI by itself. This allows it to be extremely flexible. You need to use //slots// and provide some CSS styles. To remain concise this step is demonstrated in the repository (source:/uz/src/UploadTest.vue@cc1db11). After creating the UI and navigating to proper URL you should see the uploader.
== Properties
=== target
=== max-jobs
=== auto-start
=== auto-reset
=== keep-going
== Slots
=== idle
Shown when nothing is to be done. Slot props:
* `pick` - callback function for picking files.
=== hover
Displayed when files are ready to drop. Has no scope props.
=== wait
Used when some files are waiting for upload. Props:
* `start` - begin processing callback function,
* `reset` - reset component to //idle// state,
* `queue` - vector of files awaiting to upload.
=== uploading
Shown when uploading files. Slot props:
* `progress` - uploaded items,
* `current` - files that are now processed,
* `queue` - remaining files,
* `errors` - error list,
* `abort` - abort function callback.
=== done
Displayed upon completion. Props:
* `result` - results vector,
* `reset` - reset to //idle// state callback function.
=== error
=== aborted
=== with-errors
== Instance methods
=== start
=== pick
=== reset
----
{{{#!html
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
}}}