Rozdział 1 - Tworzenie formularzy

Formularz składa się np. z takich pól jak hidden, text, select czy pola wyboru (checkboxes). Niniejszy rozdział stanowi wprowadzenie do tworzenia formularzy i zarządzania polami formularza za pomocą symfony form framework.

Symfony 1.1 wymaga zastosowania się do rozdziałów tej książki. Będziesz również potrzebował stworzyć projekt i frontend projektu. W celu uzyskania więcej informacji na temat tworzenia projektu symfony proszę odnieść się do dokumentacji głównej.

Zanim zaczniemy

Zaczniemy dodając formularz kontaktowy do aplikacji symfony.

Rysunek 1-1 pokazuje formularz kontaktowy z punktu widzenia użytkowników, którzy chcą wysłać wiadomość.

Rysunek 1-1 - formularz kontaktowy

Stworzymy trzy pola na potrzeby tego formularza: nazwa użytkownika, adres email użytkownika i wiadomość, którą użytkownik chce wysłać. Będziemy po prostu wyświetlać informacje przesłane w formularzu dla celów tego ćwiczenia, tak jak pokazano na rys. 1-2.

Rysunek 1-2 - Strona z podziękowaniem

Rysunek 1-3 - Interakcje między aplikacją a użytkownikiem

Widżety

Klasy SfForm i sfWidget

Użytkownicy wpisują dane w celu wypełnienia formularza. W Symfony, formularz jest obiektem dziedziczącym z klasy sfForm. W naszym przykładzie, stworzymy Formularz kontaktowy dziedziczący z klasy sfForm.

Możesz zacząć konfigurować Twój formularz dodając widżety za pomocą metody configure().

Widżet reprezentuje pole formularza. W naszym przykładzie, musimy dodać trzy widżety reprezentujące nasze trzy pola: Imię, email oraz wiadomość. Listing 1-1 przedstawia pierwszą implementację klasy ContactForm.

Listing 1-1 - Klasa ContactForm z trzema polami

// lib/form/ContactForm.class.php
class ContactForm extends sfForm
{
  public function configure()
  {
    $this->setWidgets(array(
      'name'    => new sfWidgetFormInput(),
      'email'   => new sfWidgetFormInput(),
      'message' => new sfWidgetFormTextarea(),
    ));
  }
}

Widżety są zdefiniowane w metodzie configure(). Metoda ta jest wywoływana automatycznie przez konstruktora klasy sfForm.

Metoda setWidgets() jest stosowana do definiowania widżetów zastosowanych w formularzu. Metoda setWidgets() akceptuje tablicę asocjacyjną, gdzie kluczami są nazwy pól, a wartościami obiekty widżetu. Każdy widżet jest obiektem dziedziczącym po klasie sfWidget. W tym przykładzie użyliśmy dwóch typów widżetów:

• sfWidgetFormInput: Ten widżet reprezentuje pole input
• sfWidgetFormTextarea: Ten widżet reprezentuje pole textarea

Wyświetlanie formularza

Nasz formularz jest teraz gotowy do użycia. Możemy teraz utworzyć moduł symfony do wyświetlania formularza:

$ cd ~/PATH/TO/THE/PROJECT
$ php symfony generate:module frontend contact

W module contact, zmieńmy akcję index tak aby przejść do template'ki formularza tak jak pokazano na Listingu 1-2.

Listing 1-2 - Klasa Actions Modułu contact

// apps/frontend/modules/contact/actions/actions.class.php
class contactActions extends sfActions
{
  public function executeIndex()
  {
    $this->form = new ContactForm();
  }
}

Przy tworzeniu formularza, metoda configure(), zdefiniowana wcześniej, będzie wywoływana automatycznie.

My po prostu musimy teraz stworzyć template, aby wyświetlić formularz w sposób pokazany na listingu 1-3.

Listing 1-3 - Template do wyświetlania formularza

// apps/frontend/modules/contact/templates/indexSuccess.php
<form action="<?php echo url_for('contact/submit') ?>" method="POST">
  <table>
    <?php echo $form ?>
    <tr>
      <td colspan="2">
        <input type="submit" />
      </td>
    </tr>
  </table>
</form>

Formularz Symfony za pomocą widżetów wyświetla jedynie informacje dla użytkowników. W template indexSuccess linia <?php echo $form?> wyświetla jedynie trzy pola. Inne elementy, takie jak tagi formularza oraz przycisk zatwierdzający wysłanie, będą musiały być dodawane przez developera. To może nie jest zbyt oczywiste na początku, ale zobaczymy później, jak przydatne i proste jest zarządzanie formularzami.

Korzystanie z konstrukcji <?php echo $form?> jest bardzo przydatne przy tworzeniu prototypów i definiowaniu formularzy. To pozwala programistom skupić się na logice biznesowej, nie martwiąc się o aspekty wizualne. Rozdział trzeci wyjaśni, jak personalizować template i layout formularza.

Możemy teraz zobaczyć formularz w przeglądarce (rys. 1-4) i sprawdzić wynik, wywołując akcję contact/index (/frontend_dev.php/contact).

Rysunek 1-4 - Wygenerowany formularz kontaktowy

Listing 1-4 Pokazuje kod wygenerowany przez template.

<form action="/frontend_dev.php/contact/submit" method="POST">
  <table>
 
    <!-- Beginning of generated code by <?php echo $form ?>
 -->
    <tr>
      <th><label for="name">Name</label></th>
      <td><input type="text" name="name" id="name" /></td>
    </tr>
    <tr>
      <th><label for="email">Email</label></th>
      <td><input type="text" name="email" id="email" /></td>
    </tr>
    <tr>
      <th><label for="message">Message</label></th>
      <td><textarea rows="4" cols="30" name="message" id="message"></textarea></td>
    </tr>
    <!-- End of generated code by <?php echo $form ?>
 -->
 
    <tr>
      <td colspan="2">
        <input type="submit" />
      </td>
    </tr>
  </table>
</form>

Widzimy, że formularz jest wyświetlany z trzema liniami <tr> tabeli HTML. Dlatego trzeba było umieścić go w tagu <table>. Każda linia zawiera tag <label> oraz tagi formularza (<input> lub <textarea>).

Etykiety

Etykiety każdego pola są generowane automatycznie. Domyślnie etykiety są transformacją nazwy pola zgodnie z obowiązującymi zasadami: pierwsza litera duża i podkreślenia zastępuje spację. Przykład:

$this->setWidgets(array(
  'first_name' => new sfWidgetFormInput(), // wygenerowana etykieta: "First name"
  'last_name'  => new sfWidgetFormInput(), // wygenerowana etykieta: "Last name"
));

Nawet jeśli automatyczne generowanie etykiet jest bardzo przydatne, framework pozwala na zdefiniowanie spersonalizowanych etykiet za pomocą metody setLabels() :

$this->widgetSchema->setLabels(array(
  'name'    => 'Your name',
  'email'   => 'Your email address',
  'message' => 'Your message',
));

Możesz również zmodyfikować pojedynczą etykietę przy użyciu metody setLabel():

$this->widgetSchema->setLabel('email', 'Your email address');

Na koniec zobaczymy w Rozdziale trzecim, że można rozszerzyć etykiety z template w celu dalszego dostosowania formularza.

$this->setWidgetSchema(new sfWidgetFormSchema(array(
  'name'    => new sfWidgetFormInput(),
  'email'   => new sfWidgetFormInput(),
  'message' => new sfWidgetFormTextarea(),
)));
 
// almost equivalent to :
 
$this->widgetSchema = new sfWidgetFormSchema(array(
  'name'    => new sfWidgetFormInput(),
  'email'   => new sfWidgetFormInput(),
  'message' => new sfWidgetFormTextarea(),
));

Poza wygenerowanymi tabelami

Nawet jeśli formularz tabeli wyświetla domyślnie format tabeli w HTML, to layout może ulec zmianie. Te różne rodzaje formatów layout'u są zdefiniowane w klasach dziedziczących z sfWidgetFormSchemaFormatter. Domyślnie formularz używa formatu table tak jak jest zdefiniowane w klasie sfWidgetFormSchemaFormatterTable. Możesz też użyć formatu list:

class ContactForm extends sfForm
{
  public function configure()
  {
    $this->setWidgets(array(
      'name'    => new sfWidgetFormInput(),
      'email'   => new sfWidgetFormInput(),
      'message' => new sfWidgetFormTextarea(),
    ));
 
    $this->widgetSchema->setFormFormatterName('list');
  }
}

Te dwa formaty są domyślne, a w rozdziale 5 będziesz mógł zobaczyć, w jaki sposób tworzyć własne klasy formatów. Teraz, gdy wiemy, w jaki sposób wyświetlić formularz, zobaczmy jak przesłać formularz.

Przesyłanie formularzy

Kiedy tworzyliśmy template do wyświetlania formularza, użyliśmy wewnętrznych URL contact/submit w tagu formularza aby wysłać formularz. Teraz musimy dodać akcją submit w module contact. Listing 1-5 pokazuje, jak akcja może otrzymać informacje od użytkowników i przekierować do strony thank you, na której wyświetlona zostanie informacja zwrotna dla użytkownika.

Listing 1-5 - Użycie akcji submit w module contact

public function executeSubmit($request)
{
  $this->forward404Unless($request->isMethod('post'));
 
  $params = array(
    'name'    => $request->getParameter('name'),
    'email'   => $request->getParameter('email'),
    'message' => $request->getParameter('message'),
  );
 
  $this->redirect('contact/thankyou?'.http_build_query($params));
}
 
public function executeThankyou()
{
}
 
// apps/frontend/modules/contact/templates/thankyouSuccess.php
<ul>
  <li>Name:    <?php echo $sf_params->get('name') ?></li>
  <li>Email:   <?php echo $sf_params->get('email') ?></li>
  <li>Message: <?php echo $sf_params->get('message') ?></li>
</ul>

metoda executeSubmit() realizuje trzy akcje:

* Ze względów bezpieczeństwa sprawdzamy, czy strona została przesłana za pomocą HTTP metody `POST`. Jeśli nie jest przesyłana za pomocą metody `POST`, użytkownik zostaje przekierowany na stronę 404. W template `indexSuccess`, zadeklarowaliśmy metodę jako `POST` (`<form ... method="POST">`):

    [php]
    $this->forward404Unless($request->isMethod('post'));

• Następnie otrzymujemy wartości z pól wypełnionych przez użytkownika, aby przechować je w tablicy params:

  $params = array(
    'name'    => $request->getParameter('name'),
    'email'   => $request->getParameter('email'),
    'message' => $request->getParameter('message'),
  );

• Na koniec, przekierowujemy użytkownika do strony Thank you (contact/thankyou), aby wyświetlić jego informacje:

  $this->redirect('contact/thankyou?'.http_build_query($params));

Zamiast przekierowywać użytkownika do innej strony, możemy stworzyć template submitSuccess.php. O ile to możliwe, lepszą praktyką jest zawsze przekierować użytkownika po żądaniu metodą POST:

• To zapobiega przed powtórnym zatwierdzeniem formularza, jeżeli użytkownik przeładuje stronę Thank you.

• Użytkownik może również kliknąć na przycisku "Wstecz", bez uzyskiwania pop-up, aby wysłać formularz ponownie.

Rysunek 1-5 pokazuje, metodę działania podczas interakcji z użytkownikiem.

Figure 1-5 - Metody działania

Po wysłaniu formularza powinieneś teraz zobaczyć stronę z Rysunku 1-6.

Figure 1-6 - Strona wyświetlona po przesłaniu formularza

Zamiast tworzyć tablicę params, łatwiej będzie uzyskać informacje od użytkownika bezpośrednio w tablicy. Listing 1-6 modyfikuje atrybut HTML name z widżetów, tak aby przechowywać wartości z pól w tablicy contact.

Listing 1-6 - Modyfikacja atrybutu HTML name z widżetów

class ContactForm extends sfForm
{
  public function configure()
  {
    $this->setWidgets(array(
      'name'    => new sfWidgetFormInput(),
      'email'   => new sfWidgetFormInput(),
      'message' => new sfWidgetFormTextarea(),
    ));
 
    $this->widgetSchema->setNameFormat('contact[%s]');
  }
}

Wywołanie setNameFormat(), pozwala nam zmodyfikować atrybut HTML name dla wszystkich widżetów. %s zostanie automatycznie zastąpiony przez nazwę pola, podczas generowania formularza. Na przykład, atrybut name zostanie zmieniony contact[email] dla pola email. PHP automatycznie tworzy tablicę z wartościami żądania zawierając format contact[email]. W ten sposób wartości pól będą dostępne w tablicy contact.

Teraz możemy bezpośrednio otrzymać tablicę contact z obiektu request, jak pokazano na Listingu 1-7.

Listing 1-7 - Nowy format atrybutu name w akcji widżetów

public function executeSubmit($request)
{
  $this->forward404Unless($request->isMethod('post'));
 
  $this->redirect('contact/thankyou?'.http_build_query($request->getParameter('contact')));
}

Podczas wyświetlania źródła HTML formularza, możesz dostrzec, że symfony wygenerowało atrybut name zależny nie tylko od nazwy pola i formatu, ale także od atrybutu id. Atrybut Id jest tworzony automatycznie z atrybutu name poprzez umieszczenie podkreślenia (_):

Inne rozwiązanie

W tym przykładzie użyliśmy dwóch akcji do zarządzania formularzem: index do wyświetlania, submit w celu przesłania. Ze względu na to, że formularz wyświetlany przy pomocy GET i przesłany metodą POST, możemy połączyć dwie metody w jedną index, jak pokazano na Listingu 1-8.

Listing 1-8 - Merging of the two actions used in the form

class contactActions extends sfActions
{
  public function executeIndex($request)
  {
    $this->form = new ContactForm();
 
    if ($request->isMethod('post'))
    {
      $this->redirect('contact/thankyou?'.http_build_query($request->getParameter('contact')));
    }
  }
}

Potrzebujesz również zmienić atrybut w action formularza w template indexSuccess.php:

<form action="<?php echo url_for('contact/index') ?>" method="POST">

Jak zobaczymy później, wolimy używać tej składni, ponieważ jest krótsza i czyni kod bardziej spójnym i zrozumiałym.

Konfiguracja Widżetów

Opcje widżetów

Jeśli strona jest zarządzana przez wielu webmasterów, to my na pewno chcemy dodać rozwijaną listę tematów w celu przekierowania wiadomości zgodnie z tym co jest wybrane (rys. 1-7). Listing 1-9 dodaje subject z listą rozwijaną przy użyciu widżetu sfWidgetFormSelect.

Rysunek 1-7 - Dodanie pola subject do formularza

Listing 1-9 - Dodanie pola subject do formularza

class ContactForm extends sfForm
{
  protected static $subjects = array('Subject A', 'Subject B', 'Subject C');
 
  public function configure()
  {
    $this->setWidgets(array(
      'name'    => new sfWidgetFormInput(),
      'email'   => new sfWidgetFormInput(),
      'subject' => new sfWidgetFormSelect(array('choices' => self::$subjects)),
      'message' => new sfWidgetFormTextarea(),
    ));
 
    $this->widgetSchema->setNameFormat('contact[%s]');
  }
}

$subjects = array(0 => 'Subject A', 1 => 'Subject B', 2 => 'Subject C');

<select name="contact[subject]" id="contact_subject">
  <option value="0">Subject A</option>
  <option value="1">Subject B</option>
  <option value="2">Subject C</option>
</select>

$subjects = array('A' => 'Subject A', 'B' => 'Subject B', 'C' => 'Subject C');

<select name="contact[subject]" id="contact_subject">
  <option value="A">Subject A</option>
  <option value="B">Subject B</option>
  <option value="C">Subject C</option>
</select>

Widget sfWidgetFormSelect, tak jak wszystkie widżety, posiada listę opcji jako pierwszy argument. Opcja ta może być obowiązkowa lub nieobowiązkowa. Widget sfWidgetFormSelect ma obowiązkową opcję choices. Oto dostępne opcje widżetów użytych do tej pory:

Atrybuty HTML widżetów

Każdy widget pobiera listę atrybutów HTML jako drugi opcjonalny argument. Jest to bardzo pomocne do określenia domyślnych atrybutów HTML dla wygenerowanych tagów formularza. Listing 1-10 pokazuje jak dodać atrybut class do pola email.

Listing 1-10 - Definiowanie atrybutów do widgetu

$emailWidget = new sfWidgetFormInput(array(), array('class' => 'email'));
 
// Generated HTML
<input type="text" name="contact[email]" class="email" id="contact_email" />

Atrybuty HTML także pozwalają nam zastąpić automatycznie wygenerowany identyfikator, jak pokazano na listingu 1-11.

Listing 1-11 - Nadpisywanie atrybutu id

$emailWidget = new sfWidgetFormInput(array(), array('class' => 'email', 'id' => 'email'));
 
// Generated HTML
<input type="text" name="contact[email]" class="email" id="email" />

Jest możliwość ustawienia domyślnych wartości pól za pomocą atrybutu value, pokazuje to Listing 1-12.

Listing 1-12 - Domyślne wartości widżetów za pomocą atrybutów HTML

$emailWidget = new sfWidgetFormInput(array(), array('value' => 'Your Email Here'));
 
// Generated HTML
<input type="text" name="contact[email]" value="Your Email Here" id="contact_email" />

Ta opcja działa dla widżetów input, trudno jest użyć dla widżetów checkbox lub radio, a nawet niemożliwe w widżecie textarea. Klasa SfForm oferuje konkretne metody w celu określenia wartości domyślnych dla każdego pola w jednolity sposób dla każdego typu widżetów.

Definiowanie wartości domyślnych pól

Często przydatne jest określenie wartości domyślnej dla każdego pola. Na przykład, gdy wyświetlamy komunikat pomocy pola, który znika, gdy użytkownik klika na polu. Listing 1-13 pokazuje jak zdefiniować wartości domyślne za pomocą metod setDefault() i setDefaults().

Listing 1-13 - Wartości domyślne widżetów poprzez metody setDefault() i setDefaults()

class ContactForm extends sfForm
{
  public function configure()
  {
    // ...
 
    $this->setDefault('email', 'Your Email Here');
 
    $this->setDefaults(array('email' => 'Your Email Here', 'name' => 'Your Name Here'));
  }
}

Metody SetDefault() i setDefaults() są bardzo pomocne do określenia identycznych wartości domyślnych dla każdej instancji tej samej klasy formularza. Jeśli chcemy zmodyfikować istniejący obiekt przy użyciu formularza, wartości domyślne zależą od instancji, w związku z tym muszą być dynamiczne. Listing 1-14 pokazuje konstruktor sfForm, którego pierwszy argument ustawia wartości domyślne dynamicznie.

Listing 1-14 - Wartości domyślne widżetów poprzez konstruktor sfForm

public function executeIndex($request)
{
  $this->form = new ContactForm(array('email' => 'Your Email Here', 'name' => 'Your Name Here'));
 
  // ...
}

$emailWidget = new sfWidgetFormInput(array(), array(
  'value' => 'Hello "World!"',
  'class' => '<script>alert("foo")</script>',
));
 
// Generated HTML
<input
  value="Hello &quot;World!&quot;"
  class="&lt;script&gt;alert(&quot;foo&quot;)&lt;/script&gt;"
  type="text" name="contact[email]" id="contact_email"
/>