Přejít k hlavnímu obsahu

 

Dnes se v Drupalu podíváme na základní programování custom modulu. Pokud se snažíme na stránku přidat nějakou novou funkcionalitu, téměř vždy nalezneme nějaký korespondující modul vytvořený a udržovaný Drupal komunitou (tj. contrib modul). Občas se však stane, že klient vyžaduje řešení, které nám žádný contrib modul neposkytuje a my ho tak musíme naprogramovat (tj. custom modul). Custom modul může mít mnoho funkcí a využití. Jedná se o část kódu, která reaguje s Drupalem jako celkem a v předem definovaných fázích přidává další funkcionalitu.

Modul, kterým se budeme zabývat, bude námi vytvořený formulář s odkazem v menu. Formulář bude mít několik polí, která se budou validovat a odesílat. Pro validaci a odeslání využijeme tzv. hook. Hook nám umožňuje interakci mezi jádrem Drupalu a samotným modulem. V první části si vystačíme s následujícímu hooky:

  • hook_form – umožňuje definovat formulář,
  • hook_form_validate – umožňuje provést validaci konkrétního formuláře,
  • hook_form_submit – spouští konkrétní funkce v době odeslání formuláře,
  • hook_menu – umožňuje přidat položky do konkrétního menu.

Základním definováním a nastavením těchto hooků bude končit první část návodu. Druhá část návodu dále naváže přidáním Javascriptových funkcí pro větší uživatelskou přívětivost.

 

VYTVOŘENÍ SOUBORŮ PRO MODUL

Abychom mohli náš modul využívat v naší Drupal instalaci, musím pro něj nejdřív definovat složku a vytvořit soubory s příponami .info a .module. Proto si nejprve v naší instalaci na cestě sites/all/modules/custom vytvoříme složku s názvem my_form a uvnitř složky vytvoříme zmíněné soubory. Nejprve je nutné definovat .info soubor a to následovně:

custom modul info

Do položky jméno napíšeme název našeho modulu, do popisu specifikujeme, co by zhruba měl náš modul dělat, package nastavíme na Custom a verzi na 1.0. Core je nastavení, pro jakou verzi jádra Drupalu by měl modul fungovat, v našem případě verze 7.

Pokud jsme vše udělali správně měl by se náš modul objevit na url /admin/modules v administraci, kde je možné ho povolit.

administrace modulu

 

VYTVOŘENÍ ODKAZU V MENU

Nyní konečně přejdeme k samotnému programování modulu. Nejprve přidáme popis modulu a všech implementovaných hooků, a to tak, abychom dodržovali coding standards.  (V tomto ukázkovém modulu nebudou coding standards dodržovány úplně přesně, protože se snažím komentáři popisovat jednotlivé funkce pro větší přehlednost).

Dále vytvoříme odkaz v menu, na kterém bude náš formulář přístupný. Definujeme si již zmíněný hook_menu a nastavíme ho podle dokumentace na Drupal.org. V našem případě chceme, aby se na odkazu zobrazil námi definovaný formulář my_form. Je konvencí, že pokud chceme využít hook, musíme ho pojmenovat ve formátu název_modulu_název_hooku. Pokud se můj modul bude jmenovat branding, pak bude název hooku pro menu branding_menu.

Hook menu

 

VYTVOŘENÍ FORMULÁŘE

Dále je nutné implementovat samotný formulář. Toho docílíme pomocí funkce hook_form. Můžeme si všimnout, že hook příjímá parametry $form a $form_state. V proměnné form je uložena definice formuláře a $form_state nám umožňuje použít hodnoty vyplněné uživatelem. Této funkce využijeme při validaci. Dalším krokem je definice formulářových prvků. Náš formulář bude obsahovat textové pole a checkbox. Součástí každého formuláře je i tlačítko, které celý formulář odešle ke zpracování. Po vyplnění příslušných polí podle Drupal form api máme základní definici formulářových prvků hotovou.

Hook form

 

VALIDACE A ODESLÁNÍ FORMULÁŘE

Posledním krokem je přidání validační a submit funkce. Validace v tomto případě kontroluje, zda je vyplněno textové pole a zároveň je checkbox nastaven na „zaškrtnuto“. Je to z toho důvodu, že v další části návodu budeme „schovávat“ textfield a zobrazovat ho pouze pokud bude checkbox zaškrtlý.

Pokud checkbox zaškrtneme, ale zároveň nevyplníme textové pole, tak nám Drupal odpoví chybovou hláškou „musíte vyplnit jméno“ a funkce hook_form_submit se nezavolá, protože formulář zůstane ve stavu „neodeslán“. Jakmile validační funkce žádnou chybu neobjeví, tak se submit funkce zavolá a formulář je v pořádku odeslán.

Hook form validate

 

Zde máme již hotový formulář ve stavu chybné validace:

error message

 

Tím jsme se dostali na konec první části našeho malého seriálu o tvorbě custom modulu. V další části si do formuláře přidáme Javascript a formuláři přidáme konkrétní funkci. Již hotový modul si můžete stáhnout v přiloženém souboru.

Jak známo, Drupal kromě kvalitního CMS poskytuje také možnosti využít jeho bohatého frameworku. „Bastlit“ vlastní moduly není žádný problém, ale pokud budete chtít programovat na úrovni, případně pracovat ve větším teamu vývojářů, neobejdete se bez znalosti Drupal coding standards.

Coding Standards Drupalu definují všechny zásady formátování kódu (odřádkování, počty mezer u jednotlivých operátorů, …). Komunita Drupalu vyžaduje Coding Standards u všech contribute modulů (moduly poskytnuté komunitě) a je to zcela pochopitelné – v momentu, kdy verzujete kód (např. v GITu), chcete sledovat pouze změny logiky kódu, nikoli formátování. Ve chvíli, kdy 2 programátoři používají jiné formátování kódu, je log změn zcela zmatený a většinu času strávíte pouze luštěním změn místo porozumění kódu.

Pochopitelně je dosti náročné pamatovat si přesně Coding Standards a psát každý řádek podle nich. Naštěstí nám komunita poskytuje podporu coding standards do běžně používaných vývojových prostředí jako jsou NetBeans, PhpStorm,... (pozn. pro české vývojáře – PSPad a poznámkový blok nejsou Drupalem podporovaná vývojová prostředí :-). Tento článek zaměřím na volně dostupné NetBeans, nicméně níže bude pár odkazů i pro konkurenční vývojová prostředí.

Formátování kódu v NetBeans

NetBeans umožňují formátovat bloky kódu nebo celé soubory pomocí klávesové zkratky CTRL+F. Proto, aby kód naformátovala dle Drupal coding standards, stačí jen vše nastavit dle podrobného návodu plného screenshotů, který je na Drupal.org. Po nastavení, které zabere sotva 15 min, můžete vesele formátovat.

Formátování NetBeans ale nezaručí 100% dodržování Coding Standards. Např. správný formát komentáře hooku,… formátování neřeší. Proto se hodí další nástroj – Code Sniffer. Jedná se o nástroj, který umožňuje kontrolovat zejména právě Coding Standards. Drupal podporuje PHP_CodeSniffer. Pro tento nástroj definuje všechna důležitá nastavení pomocí Drupal „modulu“ Coder. PHP_CodeSniffer se stará o kontrolu coding standards, zatímco Coder definuje Drupal Coding Standards pro Sniffer. Vlastní výstup z PHP_CodeSnifferu pak v příkazové řádce vypadá takto:

FILE: C:\Data\WWW\sources\index.php ---------------------------------------------------------------------- FOUND 2 ERRORS AFFECTING 2 LINES ---------------------------------------------------------------------- 12 | ERROR | [ ] There must be exactly one blank line after the file | | comment 24 | ERROR | [x] Doc comment short description must end with a full | | stop ---------------------------------------------------------------------- PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY ---------------------------------------------------------------------- Time: 232ms; Memory: 3.25Mb

Takový výstup je pěkný pro kontrolu, ale pro rychlý vývoj je pomalý. Naštěstí pro PHP_CodeSniffer existují pluginy i do NetBeans, který všechna upozornění pěkně vizualizuje a zdokonaluje tak vývoj dle Coding Standards. Konkrétně se jedná o pluginy phpcsmd a phpMD / PHP. phpMD / PHP je bohužel pouze pro NetBeans 7.x, ale phpcsmd podporuje NetBeans 7.x i 8.0.

Vizualizace pomocí phpcsmd vypadá pak takto:

NebBeans screenshot

Instalace CodeSnifferu do NetBeans

Instalace výše uvedených nástrojů a pluginů není úplně přímočará, proto uvádím STEP-BY-STEP návod, abyste zbytečně netrávili čas nad nastavením a mohli se vesele pustit do Drupal Coding Standard vývoje. Návod je konkrétně pro Windows 8 a NetBeans 8.0:

  • Pokud nemáte instalované PHP (v příkazové řádce zkuste php -v).
    • Stáhněte si PHP 5.4 z php.net (stahuj: VC9 x86 thread safe zip) na https://windows.php.net/download/#php-5.4
    • Unzipněte si, kam chcete instalovat. Např. C:\www\php (! Cesta nesmí obsahovat mezery jako např.: "C:\Program Files (x86)", jinak nebude fungovat CodeSniffer v NetBeans.)
    • Stáhněte si pear 
    • Přesuňte soubor go-pear.phar do C:\www\php
    • Přejmenujte php.ini-development na php.ini ve složce C:\www\php
    • Běžte do: Ovládací panely, najděte a otevřete "Upravit proměnné prostředí systému", dole klikněte na "Proměnné prostředí...", ve spodní části najděte proměnnou "Path" a na její konec přidejte ";C:\www\php"
    • Spusťte si příkazovou řádku jako administrátor
      • Zadejte: cd C:\www\php
    • Nainstalujte pear: php go-pear.phar
      • Bude to po vás chtít vybrat typ instalace, chcete "system". Tzn. stačí jen enter
      • V dalším kroku to kontroluje, zda má správně vyplněné cesty. Je třeba změnit cestu k pear.ini. Tzn. zadejte 10, enter, a zadejte cestu C:\www\php\pear.ini
    • Nakonec z průzkumníku spusťte C:\www\php\PEAR_ENV.reg
  • Instalace PHP CodeSnifferu
    • Otevřete příkazovou řádku
      • cd C:\www\php
      • pear install PHP_CodeSniffer
      • otestujte, že se podařilo přes: phpcs --version
    • Stáhněte si coder modul, poslední verzi 8.x (verze 8.x je určena pro Drupal 6,7 i 8. Verzování modulu může být matoucí…)
    • Coder modul rozbalte např. do C:\www\Coder
    • Otestujte, že Code Sniffer s Drupal Coding Standards funguje přes příkazovou řádku: phpcs --standard="C:\www\Coder\coder_sniffer\Drupal" "[cesta k testovanému souboru]"
    • Mělo by to vrátit něco jako:

FILE: C:\Data\WWW\sources\index.php ---------------------------------------------------------------------- FOUND 2 ERRORS AFFECTING 2 LINES ---------------------------------------------------------------------- 12 | ERROR | [ ] There must be exactly one blank line after the file | | comment 24 | ERROR | [x] Doc comment short description must end with a full | | stop ---------------------------------------------------------------------- PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY ---------------------------------------------------------------------- Time: 232ms; Memory: 3.25Mb

  • Instalace do NetBeans
    • Nainstalujte si do NetBeans plugin "phpcsmd" (V NetBeans: Tools->Plugins->Available plugins nebo Downloaded , pokud si ho ručně stáhnete na https://plugins.netbeans.org/plugin/42434/phpcsmd)
    • Nastavte si ho v NetBeans přes Tools->Options->PHP->PHPCSMD:
      • script location=C:\www\php\phpcs.bat
        • Cesta nesmí obsahovat mezery. Pokud v cestě mezery máte, vytvořte si link pomocí příkazové řádky a příkazu mklink tak, aby linkovaná cesta mezery neobsahovala)
      • standard=C:\www\Coder\coder_sniffer\Drupal    
      • extensions=php, module, inc, install, test, profile, theme, js, css, info, txt
      • A nahoře v sekci General je možné zaškrtnout: update on save, aby vám to projelo kód po každém uložení

To je vše.

Trocha zklamání na závěr

Práce s tímto pluginem ukázala, že nefunguje stoprocentně správně a některé chyby PHPCS nevypíše. Pokud si chcete být jisti, že váš kód splňuje Drupal Coding Standards, je třeba před ukončením práce zkontrolovat svůj kód přes příkazovou řádku. (Jak bylo zmíněno výše, test provedete příkazem phpcs --standard="C:\www\Coder\coder_sniffer\Drupal" "[cesta k testovanému souboru]").

I tak vám NetBeans plugin výrazně usnadní dodržování Coding Standards.

Příjemné kódění!

Další odkazy, které se mohou hodit:

Zdroje: