Un documento è una classe del progetto Instant Developer Cloud che estende la classe base Application.Document. È possibile creare documenti sia a livello di applicazione che di libreria, ma siccome essi servono per gestire i dati del database, si consiglia di inserirli in una libreria in modo che siano utilizzabili da ogni applicazione presente nel progetto.
Creazione di un documento in una libreria
Dopo aver creato e nominato il documento è importante impostare la proprietà Derivato da scegliendo la tabella del database che tale documento deve gestire. A questo punto nel documento apparirà una cartella chiamata Properties in cui sono state inserite le proprietà di classe relative ad ogni campo della tabella.
Per aggiungere le collection, è sufficiente utilizzare il comando +Collection del menu relativo all’oggetto documento, come si vede nell’immagine alla pagina seguente. Una collection è una proprietà di classe di tipo Collection, e per poterla collegare al database, occorre definire le seguenti proprietà:
- Tipo contenuto: la classe di documenti contenuti nella collection.
- Collegato a: la relazione del database da utilizzare per caricare la collection.
- Ordina per: proprietà opzionale che indica come comporre la clausola order by della query di caricamento.
Riprendendo l’esempio precedente, volendo inserire nel documento Ordine la collection delle righe, occorre prima definire il documento RigaOrdine relativo alla tabella OrderDetails, poi è possibile aggiungere al documento Ordine una collection di nome righeOrdine, che contiene documenti di tipo RigaOrdine, collegata alla relazione OrdersFK.
Il documento Ordine a cui sta per essere aggiunta una collection
Un metodo più veloce per definire documenti e collection è quello di derivarli direttamente dalla struttura del database, tramite il pulsante Crea documenti che appare nella parte centrale dell’IDE selezionando l’oggetto database nell’albero del progetto. Dopo averlo cliccato apparirà un elenco di tabelle per cui è possibile creare i documenti.
La generazione dei documenti avviene come segue:
- Per ogni tabella selezionata viene generato un documento con lo stesso nome della tabella. Esso viene posizionato in una libreria che contiene già documenti derivati dallo stesso database; se una tale libreria non esiste, ne viene creata una nuova. Se esiste già un documento che deriva dalla stessa tabella, tale tabella non apparirà nell’elenco di quelle selezionabili per la generazione di documenti.
- Per ogni documento vengono generate le proprietà di classe relative a tutti i campi della tabella. Inoltre se la tabella ha relazioni di tipo possessivo con altre tabelle, vengono generate anche le relative collection. Una relazione è definita come possessiva se la regola di cancellazione è cascade.
Al termine dell’operazione di generazione è possibile rinominare a piacere gli oggetti creati (librerie, documenti, proprietà e collection). Il modo consigliato è quello di dare ai documenti il nome della tabella in forma singolare per indicare che un’istanza del documento gestisce un singolo record di quella tabella; ad esempio il documento Prodotto gestirà i record della tabella Prodotti.
Proprietà unbound e proprietà derivate #
Oltre alle proprietà derivate dai campi della tabella del database a cui il documento è collegato, come tutte le classi di codice, i documenti possono contenere altre proprietà di classe che non sono collegate al database.
Tali proprietà sono spesso chiamate unbound, proprio per indicare che non hanno un collegamento con la tabella del database.
Esiste un terzo tipo di proprietà del documento, chiamate proprietà derivate. Esse derivano da tabelle del database diverse da quella su cui è basato il documento. Un esempio di proprietà derivata può essere il nome del prodotto a cui una determinata riga ordine è collegata. Se non ci fosse la proprietà derivata, ogni volta che il documento riga ordine deve recuperare il nome del prodotto, dovrebbe fare una query.
Le proprietà derivate sono molto importanti perché i loro valori vengono recuperati automaticamente quando il documento viene caricato dal database nella stessa query che estrae il documento. Questo vale anche per il caricamento di collection di documenti: tutta la collection viene recuperata con un’unica query che estrae anche tutte le proprietà derivate di tutte le istanze in fase di caricamento. Si tratta di un’ottimizzazione importante che il framework DO mette a disposizione.
Per definire una proprietà derivata, occorre inserire una proprietà unbound, poi impostare la proprietà Collegato a selezionando la relazione della tabella da usare per il caricamento, infine impostare la proprietà Derivato da selezionando il campo della tabella di arrivo della relazione.
Esiste un modo più veloce per creare le proprietà derivate:
- Nel documento da cui si desidera estrarre l’informazione, selezionare la proprietà e poi usare il comando Copia (Ctrl-C).
- Selezionare il documento in cui creare la proprietà derivata e usare il comando Incolla (Ctrl-V).
Viene in ogni caso creata una nuova proprietà, che sarà derivata se fra i due documenti esiste una relazione utilizzabile, altrimenti rimarrà unbound. Per distinguere i due casi è sufficiente osservare le proprietà Collegato a e Derivato da che rimarranno vuote nel caso unbound.
Si noti che una volta che è presente una proprietà derivata, sarà possibile derivare ulteriori proprietà anche usando le relazioni della tabella della prima proprietà derivata. Ad esempio se la classe RigaOrdine ha la proprietà derivata NomeProdotto, sarà possibile anche aggiungere la proprietà NomeCategoria che deriva dalla tabella delle categorie di prodotto.
Adattamento alla struttura del database #
Le modifiche alla struttura del database si riflettono sui documenti collegati. In particolare:
- Cancellando una tabella dal database i documenti collegati perdono il collegamento e non verranno più caricati dal database.
- Cancellando un campo di una tabella, le proprietà collegate vengono cancellate.
- Cancellando una relazione, le collection o le proprietà derivate perderanno il collegamento e non verranno più caricate automaticamente dal database.