9.11. API delle entità di Drupal. Creare un tipo di entità personalizzato. Generare un tipo di entità utilizzando Drupal Console.
Abbiamo già studiato la Form API, la Fields API e sappiamo come i dati in Drupal vengono inseriti nel database. Ora analizziamo le fondamenta di tutti i siti Drupal, ovvero la Entity API.
Avrai probabilmente notato che i campi non esistono autonomamente, ma sono “collegati” alle entità: nodi, blocchi, termini di tassonomia, viste, ecc. Puoi creare bundle di entità, ad esempio tipi di contenuto, tipi di blocchi, vocabolari di tassonomia. Ma cosa succede se hai bisogno di creare una nuova entità con i tuoi bundle personalizzati? In questo caso, ti servirà la Entity API per creare un nuovo tipo di entità.
Ho aggiunto tutto il codice su GitHub nel modulo drupalbook_product; puoi scaricare il modulo e aggiungerlo al tuo sito:
https://github.com/levmyshkin/drupalbook8
Il modo più semplice per creare nuovi tipi di entità è usare Drupal Console, poiché basta eseguire un solo comando.
Non è necessario creare spesso nuovi tipi di entità. La maggior parte dei progetti di piccole e medie dimensioni utilizza moduli contrib come base, ad esempio Commerce per i negozi online:
https://www.drupal.org/project/commerce
Se hai intenzione di creare un tuo modulo personalizzato, allora potresti avere bisogno di definire un nuovo tipo di entità. Tuttavia, tra i moduli Drupal già esistenti, potresti trovarne uno con la funzionalità necessaria, da estendere o integrare con ulteriori caratteristiche personalizzate.
In questo articolo analizzeremo la Entity API e creeremo un nostro tipo di entità “Product”, che servirà come base per un piccolo catalogo o negozio personalizzato. Se decidi di creare un negozio personalizzato, ti consiglio vivamente di utilizzare il modulo Commerce, perché ti farà risparmiare moltissimo tempo, sia a te che ai tuoi clienti.
Quando vuoi creare un nuovo tipo di entità, potresti chiederti: perché non creare semplicemente un altro tipo di contenuto “Product” e usarlo per il catalogo? Sì, questo è possibile per un piccolo catalogo di prodotti, con output tramite Views e filtri semplici per prezzo e disponibilità. Ma quando i prodotti diventano migliaia, sarà scomodo per il gestore cercarli nella pagina dei contenuti. Il gestore vorrà aggiungere filtri per codice articolo, categoria, colore, nome e altre proprietà nella pagina:
/admin/content
Questo renderebbe la gestione troppo pesante e confusa, interferendo con altri tipi di contenuto come Notizie, Articoli, Eventi e Pagine. Per questo motivo, in tali situazioni si crea un tipo di entità separato “Product”, con un proprio pannello amministrativo e impostazioni dedicate.
Iniziamo quindi la creazione di un tipo di entità separato “Product”. Prima di eseguire il comando per creare il tipo di entità, ti consiglio vivamente di eseguire un backup del sito, almeno del database. Il processo di creazione di un tipo di entità comporta la generazione di configurazioni che vengono scritte nel database, e se qualcosa dovesse andare storto e solo parte delle configurazioni venisse salvata senza i file dell’entità nel modulo, il sito potrebbe smettere di funzionare. Quindi, prima di tutto, crea un backup.
Ora creiamo un nuovo modulo, che può essere generato anch’esso tramite Drupal Console:
drupal generate:module
https://hechoendrupal.gitbooks.io/drupal-console/en/commands/generate-module.html
$ vendor/bin/drupal generate:module
// Benvenuto nel generatore di moduli Drupal
Inserisci il nome del nuovo modulo:
> Drupalbook Product
Inserisci il nome macchina del modulo [drupalbook_product]:
>
Inserisci il percorso del modulo [modules/custom]:
>
Inserisci la descrizione del modulo [My Awesome Module]:
> Products catalog
Inserisci il nome del pacchetto [Custom]:
>
Inserisci la versione del core di Drupal [8.x]:
>
Vuoi generare un file .module? (yes/no) [yes]:
> no
Definire il modulo come feature (yes/no) [no]:
> no
Vuoi aggiungere un file composer.json al modulo? (yes/no) [yes]:
> no
Vuoi aggiungere dipendenze per il modulo? (yes/no) [no]:
> no
Vuoi generare una classe di test unitario? (yes/no) [yes]:
> no
Vuoi generare un template grafico? (yes/no) [yes]:
> no
Vuoi procedere con l’operazione? (yes/no) [yes]:
> yes
Generated or updated files
Percorso di generazione: /home/laptop/projects/drupalbook
1 - /modules/custom/drupalbook_product/drupalbook_product.info.yml
Generated lines: "5"Oppure crea manualmente un modulo con il file drupalbook_product.info.yml:
name: 'drupalbook_product'
type: module
description: 'Products catalog'
core: 8.x
package: 'Drupalbook'Ora possiamo generare il tipo di entità Product.
https://hechoendrupal.gitbooks.io/drupal-console/en/commands/generate-entity-content.html
$ vendor/bin/drupal generate:entity:content
// Benvenuto nel generatore di entità di contenuto di Drupal
Inserisci il nome del modulo [admin_toolbar]:
> drupalbook_product
Inserisci il nome della classe della tua nuova entità di contenuto [DefaultEntity]:
> DrupalbookProductEntity
Inserisci il nome macchina della nuova entità [drupalbook_product_entity]:
>
Inserisci l’etichetta della tua nuova entità [Drupalbook product entity]:
> Product
Inserisci il percorso base per le rotte dell’entità [/admin/structure]:
>
Vuoi che questa entità abbia bundle? (yes/no) [no]:
> yes
La tua entità è traducibile? (yes/no) [yes]:
> yes
La tua entità è revisionabile? (yes/no) [yes]:
> no
Generated or updated files
Percorso di generazione: /home/laptop/projects/drupalbook
(lista completa dei file generati nel modulo)Ora che il modulo è stato generato, puoi abilitarlo per far apparire il nuovo tipo di entità nel sito:
Durante la generazione dell’entità, Drupal Console chiede che tipo di entità vogliamo creare.
Enter the class of your new content entity [DefaultEntity]:
Il nome della classe PHP per la nostra entità; è consigliabile aggiungere “Entity” alla fine del nome.
Enter the machine name of your new content entity [drupalbook_product_entity]:
Il nome macchina della classe verrà proposto in base al nome della classe; se premi Invio, verrà utilizzato quello suggerito.
Enter the base-path for the content entity routes [/admin/structure]:
Il tuo tipo di entità avrà una propria pagina per le operazioni CRUD.
La visualizzazione della pagina del prodotto è piuttosto semplice, ma potrà essere migliorata in futuro o gestita tramite Views:
Per creare una nuova entità, devi prima creare un bundle per il tipo di entità Product. Abbiamo scelto di generare un’entità con bundle:
Do you want this (content) entity to have bundles? (yes/no):
Quindi creiamo un nuovo tipo di prodotto. Ci servirà per creare diversi campi come Peso, Dimensioni, Colore e altre caratteristiche aggiuntive. Ad esempio, i monitor avranno la diagonale dello schermo, mentre le scarpe avranno la taglia.
Creiamo un nuovo tipo di prodotto: Clothes.
Ora, con il nostro nuovo tipo di prodotto, possiamo personalizzare i campi:
Abbiamo sicuramente bisogno almeno di un campo “Prezzo”.
Creiamo un paio di prodotti e diamo un’occhiata al database. Troveremo la tabella drupalbook_product_entity che contiene gli UUID dei nostri prodotti:
Esiste anche la tabella drupalbook_product_entity_field_data, nella quale vengono salvate le Proprietà. Si tratta di campi speciali dell’entità memorizzati direttamente nelle tabelle, poiché campi come “Nome” (etichetta dell’entità, ad esempio il titolo di un nodo) non cambiano tra le revisioni.
Se aggiungi nuovi campi, verranno create due tabelle per ciascun campo, poiché abbiamo scelto di utilizzare le revisioni:
Is your entity revisionable? (yes/no) [yes]
Ora dovresti aver capito come creare nuovi tipi di entità. Negli articoli successivi espanderemo le funzionalità del nostro catalogo/negozio personalizzato.
Ho aggiunto tutto il codice su GitHub nel modulo drupalbook_product; puoi scaricarlo e aggiungerlo al tuo sito: