Getting Started

Installazione

Installazione di @pzeta/vue-attachment, registrazione del VueAttachmentPlugin e configurazione dell'AttachmentAdapter.

Installazione

npm install @pzeta/vue-attachment

Peer dependencies

Pacchetto	Versione
`vue`	`^3.5.0`
`axios`	`^1.13.5`
`@pzeta/vue-components`	`^1.4.0`
`@pzeta/vue-i18n`	`^1.0.2`

@pzeta/vue-components e @pzeta/vue-i18n devono essere già configurati prima di registrare VueAttachmentPlugin.

Node >= 22.0.0. La libreria importa axios come peer dependency: l'istanza che fornisci (axios.create(...)) viene riusata 1:1, quindi i tuoi interceptors (auth, retry, tracing) si applicano automaticamente.

Registrazione del plugin

Il plugin registra globalmente i componenti e (opzionalmente) fornisce l'adapter via provide/inject. Una volta installato, useAttachments e i componenti *Connected risolvono l'adapter automaticamente.

// main.ts
import { createApp } from 'vue'
import axios from 'axios'
import App from './App.vue'
import {
  VueAttachmentPlugin,
  createAxiosAdapter
} from '@pzeta/vue-attachment'
import '@pzeta/vue-attachment/style.css'

const http = axios.create({ baseURL: '/api/storage' })
http.interceptors.request.use(addAuthHeader) // i tuoi interceptor

const app = createApp(App)

app.use(VueAttachmentPlugin, {
  adapter: createAxiosAdapter(http, { storagePath: 'attachments/tickets' }),
  // storagePath: 'attachments/tickets', // alternativa: storage path globale via inject
  // prefix: 'Pz', // → componenti registrati come PzAttachmentsManager, ...
})

app.mount('#app')

Opzioni `VueAttachmentPluginOptions`

Opzione	Tipo	Default	Descrizione
`adapter`	`AttachmentAdapter`	—	Data source globale fornito a tutti i componenti via `provide`. Tipicamente `createAxiosAdapter(http, opts)`
`storagePath`	`string`	—	Storage path di default usato se non sovrascritto via prop
`prefix`	`string`	`''`	Prefisso per i nomi dei componenti (es. `'Pz'` → `PzAttachmentsManager`)
`components`	`ComponentName[]`	tutti	Lista selettiva dei componenti da registrare

Adapter solo dove serve: i componenti *Connected e useAttachments risolvono l'adapter via inject. I componenti presentational (AttachmentsManager, AttachmentPopover, AttachmentsList, ecc.) ricevono i dati via prop e non richiedono alcun adapter — utili per demo, Storybook e SSR.

Componenti registrati globalmente

Dopo app.use(VueAttachmentPlugin) sono disponibili senza import:

AttachmentsManager, AttachmentsManagerConnected
AttachmentPopover, AttachmentPopoverConnected
AttachmentDialog
AttachmentsList, AttachmentsGrid, AttachmentsToolbar
AttachmentCard, AttachmentRow

Configurazione del backend

L'adapter axios di default si aspetta un backend REST con i seguenti endpoint, relativi al basePath (default /attachments):

Adapter method	HTTP	Path
`list(query)`	`GET`	`/?<querystring>`
`get(id)`	`GET`	`/:id`
`upload(params)`	`POST`	`/` (multipart/form-data)
`download(id, disposition)`	`GET`	`/:id/download?disposition=...`
`delete(id)`	`DELETE`	`/:id`
`deleteMany(ids)`	`POST`	`/delete` (body: `{ ids }`)
`findOrphaned()`	`GET`	`/admin/orphaned`
`cleanOrphaned(dryRun)`	`POST`	`/admin/cleanup`

L'adapter accetta sia il formato wrapped PZeta ({ success: true, data }) sia il payload diretto. Per backend con basePath o schema diverso, vedi createAxiosAdapter.

Adapter custom (non-REST)

Per backend GraphQL, fetch puro, tRPC o mock in-memory implementa l'interfaccia AttachmentAdapter:

import type { AttachmentAdapter } from '@pzeta/vue-attachment'

const myAdapter: AttachmentAdapter = {
  async list(query) { /* ... */ },
  async get(id) { /* ... */ },
  async upload(params) { /* ... */ },
  async download(id, disposition) { /* ... */ },
  async delete(id) { /* ... */ },
  async deleteMany(ids) { /* ... */ }
  // findOrphaned / cleanOrphaned sono opzionali
}

app.use(VueAttachmentPlugin, { adapter: myAdapter })

Vedi AttachmentAdapter per i contratti completi.

Verifica

Una pagina minima per verificare l'installazione:

<template>
  <AttachmentsManagerConnected
    reference-table="tickets"
    reference-column="idticket"
    :reference-value="1"
  />
</template>

Se vedi la toolbar con il pulsante upload e una grid vuota → l'installazione è OK.

Vue Attachment

Libreria Vue 3 per la gestione allegati con upload, download, preview ed eliminazione. Architettura Adapter Strategy + componenti Presentational/Connected.

Components

Componenti UI per la gestione allegati. Architettura Presentational + Connected, decoupled dal trasporto via AttachmentAdapter.