In questa lezione ci occuperemo di un’altra importante specifica relativa ad HTML5, descritta in un documento separato che potete consultare a questo indirizzo, si tratta File APIs che permettono di gestire i files lato client.
File APIs
Poiché lavorare con i files è un task quotidiano, anche sul web, HTML5 finalmente ci fornisce delle APIs standard per farlo. La specifica permette di leggere, scrivere, rimuovere file locali, sincronamente e soprattutto asincronamente.
Pensiamo ad un form che preveda l’invio al server di un file locale tramite un elemento input file: grazie alle APIs avremo finalmente la possibilità di controllare il MIME type lato client prima di inviarlo al server, leggerlo e persino decidere che i contenuti non sono quelli che ci aspettavamo, il tutto senza chiamare in causa il server.
Ci concentreremo sulle operazioni asincrone, quindi parleremo dell’interfaccia FileReader e non di FileReadersync perchè lo stesso draft dice chiaramente:
It is desirable to read data from file systems asynchronously in the main thread of user agents.
L’intero meccanismo gira intorno a quattro oggetti:
FileList
interface FileList {
getter File? item(unsigned long index);
readonly attribute unsigned long length;
};
FileList possiede un attributo length che contiene il numero dei files nella lista e un metodo item(index) che ritorna l’oggetto File sito alla posizione index.
Blob
interface Blob {
readonly attribute unsigned long long size;
readonly attribute DOMString type;
//slice Blob into byte-ranged chunks
Blob slice(optional long long start,
optional long long end,
optional DOMString contentType);
};
Blob rappresenta dati grezzi immutabili. Fornisce il metodo slice per sezionare i dati in pezzi di lunghezza definita. Espone un attributo size (dimensione del Blob) e type (il MIME type del Blob).
File
interface File : Blob {
readonly attribute DOMString name;
readonly attribute Date lastModifiedDate;
};
Rappresenta un singolo File nella lista, ottenuto dal filesystem; possiede gli attributi name e la data di ultima modifica lastModifiedDate. File eredita da Blob.
FileReader
[Constructor]
interface FileReader: EventTarget {
// async read methods
void readAsArrayBuffer(Blob blob);
void readAsBinaryString(Blob blob);
void readAsText(Blob blob, optional DOMString encoding);
void readAsDataURL(Blob blob);
void abort();
// states
const unsigned short EMPTY = 0;
const unsigned short LOADING = 1;
const unsigned short DONE = 2;
readonly attribute unsigned short readyState;
// File or Blob data
readonly attribute any result;
readonly attribute DOMError error;
// event handler attributes
attribute [TreatNonCallableAsNull] Function? onloadstart;
attribute [TreatNonCallableAsNull] Function? onprogress;
attribute [TreatNonCallableAsNull] Function? onload;
attribute [TreatNonCallableAsNull] Function? onabort;
attribute [TreatNonCallableAsNull] Function? onerror;
attribute [TreatNonCallableAsNull] Function? onloadend;
};
FileReader espone metodi per leggere oggetti File o Blob in memoria e di accedere ai dati attraverso eventi; permette letture asincrone su oggetti Blob singoli lanciando eventi progress (gestiti dagli event handlers associati) mano a mano che la lettura procede.
Gli event handlers previsti sono:
- onloadstart
- onprogress
- onabort
- onerror
- onload
- onloadend
L’oggetto prevede tre stati, lo stato corrente è ottenibili tramite l’attributo readyState.
- EMPTY (0): l’oggetto è istanziato a enon ci sono letture in corso; è lo stato iniziale.
- LOADING (1): è in corso la lattura di una File o di un Blob tramite uno dei metodi di lettura.
- DONE (2): la lettura del File o Blob è terminata oppure si è verificato un errore oppure la lettura è stata interrotta tramite la chiamata ad abort().
FileReader espone quattro metodi per leggere File e Blob in modo asincrono, ciascuno di essi valorizzerà l’attributo result al termine delle operazioni:
- readAsArrayBuffer: result conterrà i dati del File o del Blob sottoforma di un oggetto ArrayBuffer.
- readAsBinaryString(blob) deprecato in favore di readAsArrayBuffer(blob); result conterrà i dati sottoforma di una bynary string.
- readAsText: result conterrà i dati del File o del Blob sottoforma di stringa (testo) decodificata di default in UTF-8 o nel formato indicato.
- readAsDataURL: result conterrà i dati del File o del Blob sottoforma di URL data.
Una volta invocato uno di questi metodi gli handlers intercetteranno gli avanzamenti dell’operazione.