Nexus
Drop, paste, and pick files
Connect file import to the page and add-on logic using tools suited to the task.
Files, screenshots, and in-page dragging are different
The host handles desktop file drops and file pastes, delivering resource events rather than ordinary HTML5 dragover highlighting. Dragging a card inside a page is a different interaction. File interactions have defaults, but screenshot bitmaps require explicit paste_image.
Prepare page helper scripts
Copy these scripts from your framework's websdk into web/vendor and add each to the packaging manifest. Load them only on pages needing resource interaction, not from a CDN.
<script src="vendor/nexus-resource-io.js"></script>
<script src="vendor/nexus-resource-dom.js"></script>
<script src="vendor/nexus-resource-kit.js"></script>io supplies operations, dom supplies attributes/adapters, and kit mounts last. Trusted local pages receive core action/state communication automatically; do not copy another core injection script.
Minimal image import area
Place these controls inside the existing shell and retain drag and close areas. Load scripts in the previous order.
<div id="gallery" data-nexus-import="images" data-nexus-import-mode="append"></div>
<button type="button" data-nexus-pick="images"
data-nexus-accept="image/*" data-nexus-target="#gallery">Choose image</button>Resource tools handle dropped or pasted files by default. To paste screenshots, add the resource_io declaration below without external_files.
resource_io=web.resource_io(
imports=web.resource_imports(sources=("drop", "paste_files", "paste_image"))
)Choose the simplest suitable tool
| Method | Suitable for |
|---|---|
| Attributes | Image collections and simple canvases using the markers above. |
| Standard file input | Load nexus-file-input-takeover.js and use input type='file'. Disabled inputs do not open a picker. |
| Custom components | Register an adapter with canHandle and import when local coordinates are needed. Load both io and dom. |
| Custom JavaScript | Use resourceIO.pickFiles, onImages, or importDirectory for your own interface logic. |
Distinguish cancellation and partial failure
pickFiles, pickImages, and importDirectory return null on cancellation. Inspect full results or onImport: files means received resources, including images/text that may fail decoding and also appear in rejected. Usable content is in images, texts, and binaries; binary references still need reading and parsing. onFiles means only files is nonempty, not that all content is usable.
After a successful pick, matching callbacks also receive the result, with a null subscription ID. If you already handle the picker return value, skip that case in the callback.
Policies limit types, counts, and sizes. Scanning a file does not mean accepting it. Filters do not replace content validation. resource_io supports only local pages and is mutually exclusive with external_files.
Try a complete import
- Pick a supported image and confirm it appears in the target container.
- Cancel selection without losing content or showing a false error.
- Drop a file and check resource events, not HTML5 events.
- If screenshot paste is enabled, test it separately from ordinary text paste.
- Import a directory containing unsupported files and show actual accepted/rejected results.
To return content to application logic, see Return page resources. Successful import does not mean Blender was updated.