Tutoriál: Vlastný typ obsahu s vlastnými poliami pre modul do Drupalu

Ako som prišiel k tejto myšlienke? Vyvíjal som modul, ktorý sťahuje obsah zo vzdialenej API a ukladá ho ako obsah do Drupalu. Musel som sa pri tom držať pevne stanovenej štruktúry dát, a preto som si musel vytvoriť vlastný typ obsahu.

Napriek tomu, že tvorba vlastného typu obsahu je dokumentovaná v oficiálnej Drupal dokumentácii, chýbajú v nej mnohé vysvetlenia niektorých nastavení a je postavená iba na jednom špecifickom príklade. Rozhodol som sa preto spísať svoje zistenia z rôznych pokusov a taktiež aj informácie, ktoré som pozbieral z rôznych návodov, videí, dokumentácií, webstránok, atď., kde boli tieto informácie roztrúsené.

Ako začať?

Ako prvé je potrebné vytvoriť modul. Keďže typ obsahu bude nainštalovaný s modulom, všetky projektové YAML konfiguračné súbory musia byť umiestnené do „my_module/config/install“, kde „my_module“ je identifikátor modulu. Obsah je reprezentovaný v kóde ako „node“. Pre jednoduchosť som použil do tohto príkladu názov typu obsahu „foo“.

1 súbor je potrebný ako hlavný konfiguračný súbor, 2 nové súbory a 2 upravené súbory sú potrebné pre každé nové pole. Len správna konfigurácia garantuje, že všetko bude korektne nainštalované aj odinštalované spolu s modulom. Ak nebude dodržaná, vyskytnú sa problémy pri opätovnej inštalácii.

Hlavný konfiguračný súbor (node.type.foo.yml)

langcode: en
dependencies:
  enforced:
    module:
    - my_module
name: 'Foo'
type: foo
description: 'Test content type description.'
help: 'Test help text.'
new_revision: false
preview_mode: 2

Tento súbor popisuje typ obsahu. Zoznam „dependencies/enforced/module“ prepája typ obsahu a modul a tým zabezpečuje korektnú inštaláciu/odinštaláciu.
 

„name“, „description“ – meno a popis zobrazené v UI
„type“ – identifikátor (3. string z názvu súboru)
„help“ – pomocný text zobrazený v UI
„new_revision“ – keď je hodnota „true“, tak nová revízia bude vytvorená s každou úpravou obsahu („Vytvoriť novú revíziu“ bude zakšrtnuté v UI)
„preview_mode“ – 0 odstraňuje možnosť náhľadu pred vytvorením obsahu, 1 je pôvodná hodnota a umožňuje náhľad, 2 vyžaduje najprv náhľad a až potom zobrazí tlačidlo „Uložiť“

Úložisko (field.storage.node.field_foo_id.yml) – nový

langcode: en
dependencies:
  enforced:
    module:
    - my_module
  module:
  - node
id: node.field_foo_id
field_name: field_foo_id
entity_type: node
type: string
settings:
  max_length: 10
module: core
locked: false
cardinality: 1

Tento súbor popisuje úložisko hodnôt poľa. Opäť, pole pod „dependencies/enforced/module“ zabezpečuje správne prepojenie a pole pod „dependencies/module“ sa skladá z „node“ a názvu modulu podľa typu poľa („type“) – napr. „text“, „taxonomy“, „datetime“, „link“, „paragraphs“, „address“, „file“, „image“, ... – tieto 2 polia sa nemusia zhodovať.

„id“ – spojenie 3. a 4. stringu z názvu súboru
„field_name“ – 4. string z názvu súboru
„type“ – dátový typ napr. "text_with_summary", "string", "integer", "datetime", "text_long", "entity_reference", "link", "image", "address", "text", ...
„settings“ – odvíjajú sa od „type“, je to pole nastavení úložiska, ktoré sú dostupné pri vytváraní typu obsahu cez UI, taktiež môže byť prázdne (hodnota „( )“)
„module“ – hodnota zo zoznamu „dependencies/module“ – keď pole nie je závislé od žiadneho modulu (napr. keď je to primitívny dátový typ), táto hodnota bude „core“
„locked“ – povoľuje alebo zakazuje úpravu nastavení pola po inštalácii (keď modul slúži len na sťahovanie špecifických dát, je dobré ich zamknúť)
„cardinality“ – koľko hodnôt môže byť do poľa uložených

Nastavenia poľa (field.field.node.foo.field_foo_id.yml) – nový

langcode: en
dependencies:
  config:
  - field.storage.node.field_foo_id
  - node.type.foo
id: node.foo.field_foo_id
field_name: field_foo_id
entity_type: node
bundle: foo
label: 'Foo ID'
description: 'ID field description'
required: false
default_value: 'example'
settings: { }
field_type: string

Tento súbor pridáva viac nastavení. Zoznam „dependencies/config“ obsahuje 2 predchádzajúce súbory. Taktiež tu môžu byť závislosti na moduloch ako bolo už spomenuté vyššie, no keďže string je v tomto prípade len primitívny dátový typ, závisí len na „core“. V inom prípade sú možné hodnoty zhodné s tými v predchádzajúcom súbore (okrem „node“).

„id“ – spojenie 3.-5. stringu z názvu súboru
„field_name“ – strojový názov, identifikátor (5. string z názvu súboru)
„bundle“ – 4. string z názvu súboru
„label“, „description“ – zobrazené v UI
„required“ – ak je „true“, hodnota musí byť zadaná pred uložením entity
„default_value“ – keď nie je špecifikovaná žiadna hodnota, táto bude použítá (a je taktiež zobrazená v UI vo formulári)
„settings“ – závisia na „type“
„field_type“ – zhodné s „type“ z predchádzajúceho súboru

Zobrazenie (core.entity_view_display.node.foo.default.yml) – úprava

langcode: en
status: true
dependencies:
  config:
  - field.field.node.foo.field_foo_id
  - node.type.foo
id: node.foo.default
targetEntityType: node
bundle: foo
mode: default
content:
  field_foo_id:
    label: hidden
    type: string
    weight: 100
    settings: {  }
    third_party_settings: {  }

Tento súbor popisuje ako bude vyzerať obsah zobrazený na stránke. Zoznam „dependencies/config“ musí obsahovať všetky vytvorené polia. Zoznam „dependencies/module“, ktorý nie je v mojom súbore lebo string nepoužíva žiaden modul, musí obsahovať všetky moduly použité typmi („type“) polí zo zoznamu „content“ („text_default“, ...).

„status“ – povoľuje alebo zakazuje zobrazenie obsahu
„id“ – spojenie 3. - 5. stringu z názvu súboru
„mode“ – posledný string z názvu súboru
„content“ – zoznam všetkých polí, ktoré majú byť zobrazené (kľúce sú strojové názvy polí)
„label“ – keď nie je zadané, popisok poľa bude zobrazený, keď má hodnotu „hidden“, tak nebude
„type“ – môže byť odlišný od predchádzajúcich „type“ – je to identifikátor zobrazovača hodnoty („default_formatter“ v "core/lib/Drupal/Core/Field/Plugin/Field/FieldType/<class_name>.php") - https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Field%21Plugin%21Field%21FieldType%21StringItem.php/8.6.x
„weight“ – musí byť rozdielne pre každé pole – určuje poradie
„settings“, „third_party_settings“ – závisia na „type“

Formulár (core.entity_form_display.node.foo.default.yml) – úprava

langcode: en
status: true
dependencies:
  config:
  - field.field.node.foo.field_foo_id
  - node.type.foo
id: node.foo.default
targetEntityType: node
bundle: foo
mode: default
content:
  field_foo_id:
    type: string_textfield
    weight: 100
    settings:
      size: 30
      placeholder: 'example'
    third_party_settings: {  }
hidden: { }

Tento súbor popisuje ako bude vyzerať formulár na výtváranie a editáciu daného obsahu. Hodnoty sú takmer rovnaké ako v predchádzajúcom súbore „Zobrazenie“ ale „type“ v zozname „content“ určuje iný nástroj, tzv. „widget“ definovaný pod „default_widget“ v „core/lib/Drupal/Core/Field/Plugin/Field/FieldType/<class_name>.php“ - https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Field%21Plugin%21Field%21FieldType%21StringItem.php/8.6.x
„hidden“ – zoznam skrytých elementov

Finálna štruktúra súborov s 1 vlastným poľom

Závery a ako si to uľahčiť

Je dobré vedieť význam a možnosti jednotlivých riadkov v YAML konfiguračných súboroch. Tvorba všetkých polí takto manuálne však môže byť veľmi náročná, takže je dobré si to uľahčiť jednoduchým trikom. Cez UI sa vytvorí nový typ obsahu, ktorý neskôr zmažeme, ale predtým si exportujeme jeho konfiguráciu, ktorú už vieme len skopírovať do YAML súboru a ušetríme tým učenie sa všetkých možností. Export je na ceste "/admin/config/development/configuration/single/export".