Uvod u Entity API u Drupalu 8

Sistem entiteta u Drupalu 8

Entiteti su tipizirane klase sa metodama

Pozadina

Sistem entiteta uveden je pri kraju razvojne faze Drupala 7 sa osnovnim standardima za učitavanje entiteta. Modul entity.module dodatno je proširio API, dodajući podršku za čuvanje i brisanje entiteta i mnoge druge funkcionalnosti.

Većina ovih unapređenja sada je uključena u Drupal 8. Provera entiteta se sada vrši u posebnom API-ju (koji može, na primer, proveriti entitet sačuvan preko REST-a, a ne preko forme).

Dve varijante

Tipovi entiteta u jezgru postoje u dve varijante.

Objekat konfiguracije
Koristi Sistem konfiguracije. Podržava prevode i može da obezbedi korisničke podrazumevane postavke za instalacije. Objekti konfiguracije se čuvaju u zajedničkoj tabeli baze podataka za konfiguraciju kao stringovi.

Sadržaj entiteta
Sastoji se od podesivih i osnovnih polja, može imati revizije i podržavati prevode. Entiteti sadržaja se čuvaju u posebnoj korisničkoj tabeli baze podataka kao stringovi. Ime tabele odgovara imenu objekta "id", a kolone definiše metod "baseFieldDefinitions" objekta.

Bundli

Bundli su različite varijante tipa entiteta. Na primer, za tip entiteta "node", bundli su različiti tipovi nodova kao što su "article" i "page".

Obično je bundl predstavljen kao objekat konfiguracije, mada postoje i druge modele u contrib modulima. Tako, u primeru nodova, tip nod-a "article" je sam objekat konfiguracije. Konfiguracija čuva razlike između tipova entiteta sadržaja, kao što su postavke i polja. Kada kreirate novi tip entiteta sa bundlovima, kreiraćete i content entitet koji upravlja detaljima i operacijama sadržaja, kao i objekat konfiguracije koji upravlja razlikama između tipova entiteta sadržaja.

Anotacije

Kada kreirate novi tip entiteta, koristićete sistem anotacija ugrađen u jezgro. Anotacije izgledaju kao docblock komentari iznad klase, ali ih Drupal jezgro čita i kešira. Na mnogo načina, anotacije zamenjuju neke od starijih stilova iz Drupala 7.

Parser anotacija

Anotacije se čitaju i analiziraju u toku izvršavanja mehanizmom anotacija. Drupal 8 koristi Doctrine Annotation parser koji ih pretvara u PHP objekte koje može koristiti kod.

Sintaksa. Sintaksa anotacije je unutar @ClassName(), uglavnom se sastoji od parova ključ/vrednost i može sadržati nizove u viticastim zagradama. Ključevi na vrhunskom nivou ne smeju biti u navodnicima, dok ključevi u nizovima moraju biti u navodnicima. Svaki par ključ/vrednost se piše u posebnom redu koji se završava zarezom. Određene funkcije se mogu primenjivati na vrednosti, naročito @Translation().

Neispravan primer sintakse anotacije:

/**
 * @ContentEntityType(
 *   id = "my_entity_type_id",
 *   label = @Translation("My entity type label"),
 *   example_pair = "this_examples_value",
 *   example_array = {
 *     "array_key" = "array_value",
 *     "some_other_key" = "some_other_value",
 *   },
 * )
 */

Opšte anotacije na vrhunskom nivou

Handleri

Handleri se definišu u anotaciji entiteta kao niz. Oni podržavaju entitet tako što određene delove njegove implementacije prebacuju na druge PHP klase. Te klase "rukuju" dodeljenim delovima implementacije entiteta.

Skladištenje – rukuje učitavanjem, čuvanjem i brisanjem entiteta. Po defaultu, content entiteti koriste Drupal\Core\Entity\Sql\SqlContentEntityStorage, dok konfiguracioni entiteti koriste Drupal\Core\Config\Entity\ConfigEntityStorage. Možete definisati sopstveni storage handler da proširite standardne metode skladištenja entiteta. Ovo je korisno ako želite dodati metode za dobijanje revizijskih ID-jeva ili broja prevoda entiteta.
Primer: "storage" = "Drupal\node\NodeStorage",

Forma – u anotaciji handlera za svaki entitet postoje form handleri koji preusmeravaju forme za dodavanje, uređivanje i brisanje entiteta na druge PHP klase.
Primer:

"form" = {
  "add" = "Drupal\block\BlockForm",
  "edit" = "Drupal\block\BlockForm",
  "delete" = "Drupal\block\Form\BlockDeleteForm",
}

Takođe, možete definisati "default" form handler koji pokriva i "add" i "edit" forme, umesto da ih definišete posebno. Vredno je napomenuti da "delete" forma obično ima poseban handler jer je to "confirmation" forma koja samo pita da li je korisnik siguran da želi da obriše entitet.

View builder – handler koji obezbeđuje klasu koja upravlja prikazom entiteta krajnjem korisniku. Na primer, kod prikaza nod-a u Drupal 8, prikaz entiteta obrađuje NodeViewBuilder.
Primer: "view_builder" = "Drupal\node\NodeViewBuilder",

List builder – klasa koja upravlja listama entiteta za administrativne svrhe. Ova klasa definiše zaglavlja, redove i akcije na stranici upravljanja entitetima. Na primer, na URI /admin/content, sadržaj tabele pruža NodeListBuilder.
Primer: "list_builder" = "Drupal\node\NodeListBuilder",

Route provider – opciona klasa koja, ako je implementirana, generiše rute za upravljanje entitetom. Implementacija može zameniti potrebe za entity putanjama definisanim u routing.yml fajlu modula. Imajte na umu da route_provider funkcioniše zajedno sa linkovima definisanim za entitet (pogledajte primer u sekciji "Linkovi"). Anotacija route_provider je niz.
Primer:

"route_provider" = {
  "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
}

Access – handler za pristup koji se koristi za dinamičku proveru permisija entiteta. Ovo je klasa koja implementira EntityAccessControlHandlerInterface. Jezgro ima podrazumevanu implementaciju kao EntityAccessControlHandler, ali za bolju kontrolu nad entitetom možete proširiti tu klasu sopstvenom implementacijom.
Primer: "access" = "NodeAccessControlHandler",

Views data – handler koji omogućava entitetu da proširi modul Views sopstvenim podacima. Ovo može uključivati dodavanje baseFieldDefinitions kao polja Views-a, povezivanje tabela preko entitetskih odnosa, ili druge izmene podataka za Views.
Primer: "views_data" = "Drupal\node\NodeViewsData",

Storage schema – handler koji može da menja postavke skladištenja baze podataka, na primer dodavanjem dodatnih indeksa na tabelama.
Primer: "storage_schema" = "Drupal\node\NodeStorageSchema",

Translation – handler za upravljanje prevodima i njihovim integracijama u forme entiteta.
Primer: "translation" = "Drupal\node\NodeTranslationHandler",

Primer kompletnih handlera:
Drupal jezgro pruža handler-e koje možete koristiti "odmah", ali često ćete želeti da ih proširite sopstvenim klasama radi većeg nadzora i prilagođavanja entiteta. Sledeći primer prikazuje punu anotaciju handlera koristeći osnovne klase koje možete proširiti.

handlers = {
  "view_builder" = "Drupal\Core\Entity\EntityViewBuilder",
  "list_builder" = "Drupal\Core\Entity\EntityListBuilder",
  "access" = "Drupal\Core\Entity\EntityAccessControlHandler",
  "views_data" = "Drupal\views\EntityViewsData",
  "storage" = "Drupal\Core\Entity\Sql\SqlContentEntityStorage",
  "storage_schema" = "Drupal\Core\Entity\Sql\SqlContentEntityStorageSchema",
  "translation" = "Drupal\content_translation\ContentTranslationHandler",
  "form" = {
    "default" = "Drupal\Core\Entity\ContentEntityForm",
    "add" = "Drupal\Core\Entity\ContentEntityForm",
    "edit" = "Drupal\Core\Entity\ContentEntityForm",
    "delete" = "Drupal\Core\Entity\ContentEntityDeleteForm",
  },
  "route_provider" = {
    "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider",
  },
},

Linkovi

Linkovi se definišu u anotaciji entiteta kao niz. Linkovi imaju određeni skup ključeva čije su vrednosti URI adrese na kojima se može upravljati tipom entiteta ili pojedinačnim entitetima tog tipa. Ovi linkovi mogu biti definisani kako za content, tako i za config entitete.

Primer:

id = "node",
handlers = {
  "route_provider" = {
    "html" = "Drupal\Core\Entity\Routing\AdminHtmlRouteProvider"
  }
},
links = {
  "canonical" = "/node/{node}",
  "add-page" = "/node/add",
  "add-form" = "/node/add/{node_type}",
  "edit-form" = "/node/{node}/edit",
  "delete-form" = "/node/{node}/delete",
  "collection" = "/admin/content",
},

Imajte na umu da ovo nije doslovno iz modula Node, već samo primer.

Kreiranje ovih linkova automatski ne pravi rute za te URI adrese. Da biste te linkove učinili dostupnim, vaš modul mora imati routing.yml fajl ili koristiti route_provider handler u anotaciji entiteta.

Linkovi i provider ruta

Gore navedeni linkovi, u kombinaciji sa "route_provider", omogućiće sledeće imenovane rute u Drupalu.

Korišćenje linkova
Ovi linkovi su dostupni kroz metod toUrl() objekta:

$view_url_object = $entity->toUrl();  // Podrazumevano je 'canonical'
$edit_url_string = $entity->toUrl('edit-form')->toString();

Linkovi:

• Entity API - Generisana dokumentacija.
• Kreiranje korisničkog content entiteta - Veoma jednostavan primer korisničkog entiteta.
• Kreiranje tipa content entiteta u Drupalu 8 - Napredniji primer sa handlerima, permisijama, rutiranjem i linkovima.
• Kreiranje tipa konfiguracionog entiteta u Drupalu 8 - Napredniji primer sa handlerima, rutiranjem i šemom.
• [Spoljno] Entity Type Walkthrough - Dokumentacija za opšti tip entiteta u praksi.