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 aukladá ho ako obsah do Drupalu. Musel som sa pri tomdržať pevne stanovenej štruktúry dát, apreto som si musel vytvoriť vlastný typ obsahu.

Napriek tomu, že tvorba vlastného typu obsahu je dokumentovaná voficiálnej Drupal dokumentácii, chýbajú v nejmnohé vysvetlenia niektorých nastavení aje postavená iba na jednom špecifickom príklade. Rozhodol som sa preto spísať svoje zistenia zrôznych pokusov ataktiež aj informácie, ktoré som pozbieral zrô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ý smodulom, 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ý vkó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 a2 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 smodulom. 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 amodulatým zabezpečuje korektnú inštaláciu/odinštaláciu.

„name“, „description“ – meno apopis zobrazené vUI
„type“ – identifikátor (3. string znázvu súboru)
„help“ – pomocný text zobrazený vUI
„new_revision“ – keď je hodnota „true“, tak nová revízia bude vytvorená skaždou úpravou obsahu („Vytvoriť novú revíziu“ bude zakšrtnuté vUI)
„preview_mode“ – 0 odstraňuje možnosť náhľadu pred vytvorením obsahu, 1 je pôvodná hodnota aumožňuje náhľad, 2 vyžaduje najprv náhľad aaž 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 apole pod „dependencies/module“ sa skladá z „node“ aná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. a4. stringu znázvu súboru
„field_name“ – 4. string zná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 vtomto prípade len primitívny dátový typ, závisí len na „core“. Vinom prípade sú možné hodnoty zhodné stými vpredchádzajúcom súbore (okrem „node“).

„id“ – spojenie 3.-5. stringu znázvu súboru
„field_name“ – strojový názov, identifikátor (5. string znázvu súboru)
„bundle“ – 4. string znázvu súboru
„label“, „description“ – zobrazené vUI
„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á vUI vo formulári)
„settings“ – závisia na „type“
„field_type“ – zhodné s „type“ zpredchá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 vmojom 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 znázvu súboru
„mode“ – posledný string zná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 aeditáciu daného obsahu. Hodnoty sú takmer rovnaké ako vpredchádzajúcom súbore „Zobrazenie“ ale „type“ vzozname „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 s1 vlastným poľom

Závery aako si to uľahčiť

Je dobré vedieť význam amožnosti jednotlivých riadkov vYAML 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 aušetríme tým učenie sa všetkých možností. Export je na ceste "/admin/config/development/configuration/single/export".