` | Make this element a drop zone for the `avatar` slot. Adds the `upload-dragover` class while a file is being dragged over. | | `dj-upload-preview="avatar"` | Container the client fills with a preview thumbnail for image files. | | `djust:upload:progress` | Window event fired as the server acknowledges chunks; `e.detail` carries `uploadName`, `progress` (0–100) and `status`. | | `dj-update="ignore"` + `id` on the `` | Keeps server re-renders from resetting the `value` the script sets. | | `djust:upload:error` | Window event fired when the client refuses a file itself: `e.detail.file` and `e.detail.error` (`"File too large"`). | | `djust:error` with `"Upload rejected …"` | The server refused to register the file (extension or MIME type outside `accept`, active content, or `max_entries` reached). No upload entry exists, so the view never sees it. | **The upload starts when the file is picked or dropped**, and the progress bar fills as the chunks stream. Clicking "Save avatar" then calls `save_avatar` on the server, which keeps the file that arrived. --- ## Step 3 — The server-side handler ```python # myapp/views.py — append to AvatarView _ACCEPTED = {"image/jpeg": ".jpg", "image/png": ".png", "image/webp": ".webp"} class AvatarView(UploadMixin, LiveView): # ... mount() as before ... @event_handler def save_avatar(self, **kwargs): self.error = "" latest = None # Read each entry's bytes INSIDE the loop: the temp files are # deleted when the generator is exhausted. Drain it fully, so every # completed entry is cleaned up, and keep only the newest valid # file: a user who picks a second file before saving has two # completed entries, and only one of them is their avatar. for entry in self.consume_uploaded_entries("avatar"): data = entry.data # Magic-byte check: decide the type from the content, not # from the client's filename or MIME type. kind = next((m for m in _ACCEPTED if validate_magic_bytes(data, m)), None) if kind is None: self.error = "That doesn't look like a JPEG, PNG or WebP image." continue latest = (data, entry.safe_client_name, entry.client_name) if latest is None: if not self.error: rejected = [e.error for e in self.get_uploads("avatar") if e.error] self.error = rejected[0] if rejected else "No file uploaded yet." return data, safe_name, display_name = latest profile, _ = Profile.objects.get_or_create(user=self.request.user) if profile.avatar: profile.avatar.delete(save=False) # one avatar per user # upload_to="avatars/" + a server-generated directory: the stored # path never comes from the client. profile.avatar.save(f"{uuid4().hex}/{safe_name}", ContentFile(data), save=True) self.error = "" self.avatar_url = profile.avatar.url self.avatar_name = display_name self.avatar_size = len(data) @event_handler def reset_avatar(self, **kwargs): self.avatar_url = "" self.avatar_name = "" self.avatar_size = 0 self.error = "" ``` Four things to call out: 1. **`consume_uploaded_entries("avatar")`** is the way to read the bytes. It is a generator over the completed entries; each entry is yielded once, and all of them are removed and their temp files deleted when the generator is exhausted — calling it again returns nothing, which prevents accidental double-saves. Don't `list()` it and read the entries afterwards: by then their temp files are gone and `entry.data` is empty. 2. **`max_entries=1` limits uploads in flight, not completed ones.** Once the first file finishes, the user can pick another before pressing Save, so the handler can see two entries. It keeps the newest valid one, and deletes the previously stored avatar. 3. **`entry.client_name` is hostile input.** Build storage paths from `entry.safe_client_name` (a path-safe basename) under a server-generated directory, never from `client_name`, which can carry `../` segments. Use `client_name` only for display. 4. **Where each rejection shows up.** A file over `max_file_size` is refused by the client (`djust:upload:error`), and an extension or MIME type outside `accept` by the server at registration (`djust:error`, "Upload rejected …"). Neither creates an upload entry, so the view never hears about them; the Step 2 script shows the message. A file whose magic bytes don't match its declared type (`evil.exe` renamed to `cute.png`) uploads but never completes; its message is on the entry's `error`, which `save_avatar` shows. The explicit `validate_magic_bytes` check keeps the decision about what you store in your own code. --- ## Step 4 — Style the drop zone ```html ``` The framework adds the `upload-dragover` class to the drop zone while a file is being dragged over the page (so the visual hover state activates without any JS from you). --- ## What just happened, end to end ``` Browser Server │ │ │ user picks "me.png" │ │ ──── start upload ─────►│ (UploadMixin checks size, │ │ extension and type) │ │ │ ── chunk 1 (binary) ───►│ │ ── chunk 2 (binary) ───►│ (each chunk is 64 KB) │ ── chunk N (binary) ───►│ │ ◄ progress: 8% ─────────│ (interleaved with chunks) │ ◄ progress: 16% ────────│ │ ◄ progress: 100% ───────│ (magic bytes checked) │ │ │ user clicks "Save" │ │ ─── dj-submit ─────────►│ → calls save_avatar() │ │ ↓ consume_uploaded_entries() │ │ ↓ magic-byte check │ │ ↓ profile.avatar.save() │ │ ↓ self.avatar_url = ... │ ◄── HTML diff ──────────│ (drop zone replaced with preview card) ``` The whole thing is one WebSocket session — the same one carrying your normal events. `dj-form-pending` covers the in-flight UX on the submit button, the progress event fills the `` bar, and the final state change replaces the drop zone with the saved-avatar card via the standard diff cycle. --- ## Where to go next - **Multiple files at once:** raise `max_entries` (e.g. `max_entries=10`) and iterate `consume_uploaded_entries("attachments")`. The drop zone accepts a multi-select drag, and the progress event fires per-entry. - **Preview-then-confirm:** the bytes stream on selection, but nothing is stored until `save_avatar` runs. The preview thumbnail plus a "Looks good?" submit button is already a confirm step; `window.djust.uploads.cancelUpload(ref)` stops a transfer the user changes their mind about. - **External storage (S3, GCS, Azure):** set the `FileField`'s `storage=` (or Django's default storage) to a configured backend; `ContentFile(data)` works with any of them. To stream chunks straight to the store instead, pass a `writer=` to `allow_upload()` (see [Uploads](uploads.md)). - **Resumable uploads for very large files:** pass `resumable=True` to `allow_upload()`; see the [Uploads guide](uploads.md) — the framework persists per-session chunk ranges, so a dropped WebSocket reconnects and resumes mid-file. - **Direct-to-S3 presigned uploads:** if you want the bytes to bypass the server entirely, use `@server_function` to mint a presigned URL and have the client PUT directly to S3 — same pattern as the [typeahead-with-server_function tutorial](tutorial-typeahead-server-function.md). The five-primitive recipe (`UploadMixin`, `allow_upload`, `dj-upload`, `djust:upload:progress`, `consume_uploaded_entries`) is the same shape every upload feature uses — single file, multiple files, image-with-crop, video-with-thumbnail, CSV import. Once the avatar uploader works, dragging in more file types is mostly new server-side validation.