Tvorba custom modulu s formulářem 1. část

programming in progress

 

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říjmá 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 konce 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.