Průvodce formulářovým API - tvorba a šablonování formulářů

Úvodní strana \ Drupal \ Drupal \ Průvodce formulářovým API - tvorba a šablonování formulářů

Průvodce formulářovým API - tvorba a šablonování formulářů

Neděle, 05 Duben 2009 13:47

API pro formuláře v drupalu je velmi mocný nástroj dovolující návrh, validaci, potvrzování formulářů. Snadno můžete elementy odebírat, přidávat, nebo upravovat. V následujících řádkách si něco o API povíme.
Ještě než se do tvorby pustíme nutno dodat, že následující návod platí pouze pro Drupal verze 6.x

Vytváření formulářů

Veškeré formuláře vytváříme ve formátu polí. Vždy přiřazujeme určitému klíči jednotlivé hodnoty. Raději si to ukažme na příkladu, tento kus kódu zobrazí texotvý formulář:

<?php
     $form['foo'] = array(
  '#type' => 'textfield', 
    '#title' => t('bar'),
   '#default_value' => $object['foo'],
   '#size' => 60,
   '#maxlength' => 64, 
   '#description' => t('baz'),
);
?>

a k němu připojíme potvrzovací tlačítko

<?php
     $form['submit'] = array(
   '#type' => 'submit',
   '#value' => t('Save'),
);
?>

Nyní tedy pár poznámek ke kódu:

Jméno elementu se deklaruje v poli $form, pole může být vícerozměrné, například takto:

 <?php
       $form['nastaveni_uctu']['uzivatelske_jmeno'];?>

Poté je název daného formulářového pole'uzivatelske_jmeno', tento klíč je poté k dispozici pod proměnou $form_state['values']

Typ elementu se nachází pod klíčem #type
Vlastnosti a atributy vždy začínají znakem # a vždy jsou to řetězce (string)
Pořadí jednotlivých atributů a vlastností může být náhodné, a nemusí být vždy uvedeny všechny vlastnosti.
Nepoužívejte vždy #value hodnotu, místo toho lze použít #default_value

Nyní se podíváme na složitější příklad využití formulářů:

<?php
function test_form($form_state) {
   // Access log settings:
   $options = array('1' => t('Enabled'), '0' => t('Disabled'));
   $form['access'] = array(
     '#type' => 'fieldset', 
     '#title' => t('Access log settings'), 
     '#tree' => TRUE,
   );
   $form['access']['log'] = array(
     '#type' => 'radios', 
     '#title' => t('Log'), 
     '#default_value' =>  variable_get('log', 0), 
     '#options' => $options, 
     '#description' => t('The log.'),
   );
   $period = drupal_map_assoc(array(3600, 10800, 21600, 32400, 43200, 86400, 172800, 259200, 604800, 1209600, 2419200, 4838400, 9676800), 'format_interval');
   $form['access']['timer'] = array(
     '#type' => 'select', 
     '#title' => t('Discard logs older than'), 
     '#default_value' => variable_get('timer', 259200), 
     '#options' => $period, 
     '#description' => t('The timer.'),
   );
   // Description
   $form['details'] = array(
     '#type' => 'fieldset', 
     '#title' => t('Details'), 
     '#collapsible' => TRUE, 
     '#collapsed' => TRUE,
   );
   $form['details']['description'] = array(
     '#type' => 'textarea', 
     '#title' => t('Describe it'), 
     '#default_value' =>  variable_get('description', ''), 
     '#cols' => 60, 
     '#rows' => 5, 
     '#description' => t('Log description.'),
   );
   $form['details']['admin'] = array(
     '#type' => 'checkbox', 
     '#title' => t('Only admin can view'), 
     '#default_value' => variable_get('admin', 0),
   );
   $form['name'] = array(
     '#type' => 'textfield', 
     '#title' => t('Name'), 
     '#size' => 30, 
     '#maxlength' => 64, 
     '#description' => t('Enter the name for this group of settings'),
   );
   $form['hidden'] = array('#type' => 'value', '#value' => 'is_it_here');
   $form['submit'] = array('#type' => 'submit', '#value' => t('Save'));
   return $form;
       }

function test_page() {
   return drupal_get_form('test_form');
       }
?>

Tento kus kódu ukazuje, jak mohou být formuláře vytvářeny v hierarchické struktuře rozšiřováním pole. Vidíme dvě funkce. První která vytváří formulář a druhá, která zobrazuje daný formulář pomocí funkce drupal_get_form(). Všimněme si, že první vrstva je ze dvou skupin 'acces' a 'details'. V každé skupine se nacházejí jednotlivé elementy. Pořadí konstrukce je zde důležité. Pořadí elementů v poli odpovídá následnému pořadí zobrazených prvků na stránkách.

U skupin "acces" a "details" je parametr #type nastaven na fieldset

Funkce drupal_get_form() je klíčová ve formulářovém API. Její použití je jednoduché. Má pouze jeden atribut. Je to řetězec, který je shodný s názvem funkce která tvoří jednotlivé prvky formuláře, v našem případě je název atributu test_form.

drupal_get_form() obsluhuje následující věci:

Začíná celý proces vytváření formuláře
Překládá $form['name'] položku do aktuálního formulářového elementu
Odesílá formulář, pokud je je funkce pro odesílání formuláře deklarována
Volá funkce pro šablonování formulářů, pokud byly vytvořeny
Vrací HTML řetězec pro zobrazení formulářů

více informací o funkci drupal_get_form() získáte na oficiálních stránkách stránkách

Šablonování formulářů

Vytvářet vzhled formulářů je možné pomocí dvou základních metod:

První možností je vkládání přímo jednotlivých elementů jako atributy pole
- při vytváření takovýchto formulářů používáme #prefix a #sufix, jak už z názvu vyplývá, jedná se o element před a za formulářem, podívejme se na příklad:
- <?php $form['access'] = array( '#type' => 'fieldset', '#title' => t('Access log settings'), '#prefix' => '<div class="foo">', '#suffix' => '</div>', ); ?>
- Dále je zde typ #markup, který může být umístěn kamkoliv do formuláře, jeho hodnota pak bude rendrována ve specifikované pozici
- ```
<?php
 $form['div_tag'] = array('#type' => 'markup', '#value' => '<div class="foo">');
?>
```
- Tento markup element je přístupný přes jeho jméno v poli (div_tag)
Rozdělení jednotlivých značek do separátních funkcí.To je uděláno vytvořením šablonové funkce přiřazené k ID formuláře. V případě, že chcete jeden styl přiřazovat více formulářům, můžeme použít volitelný argument funkce drupal_get_form(), v tomto případě bude třetí argument funkce řetězec obsahující jméno funkce, která volá kód pro tvorbu formuláře. Zní to možná trochu nepřehledně, proto si raději ukažme příklad, který bude šablonou pro náší funkci test_form uvedenou o něco výše.

<?php
function theme_test_form($form) {
   $output = '';
   $output .= drupal_render($form['name']);
   $output .= '<div class="foo">';
   $output .= drupal_render($form['access']);
   $output .= '<div class="bar">';
   $output .= drupal_render($form['details']);
   $output .= '</div></div>';
   $output .= drupal_render($form);
   return $output;
       }
?>

Pár poznámek ke kódu:

funkce začíná prefixem theme_
Má jeden argument, který je názvem pole, ve kterém je formulář
Vytváříme a vracíme jeden dlouhý řetězec ($output)
Forumláře jsou rendrovány pomocí funkce drupal_render
Pokud pomocí funkce drupal_render vykreslujeme pole nastavené jako fieldset, budou vykresleny všechny elementy v pořadí, jaké je uvedeno ve funkci test_form
Pořadí můžeme měnit voláním funkce drupal_render s argumentem $form['name'] v místě kde chceme prvek s názvem 'name' umístit
Formulář může výt vykreslen pouze jednou.

To je k vytváření a šablonování formulářů vše. Příští článek bude o validování a odesílání formulářů

Článek byl přeložen z oficiálních stránek drupal.org