35.4. Klasy pomocników

W skryptach widoków często potrzebne jest przeprowadzanie złożonych funkcji: na przykład formatowanie daty, generowanie elementów formularzy, czy wyświetlanie odnośnikow akcji. Możesz użyć klas pomocników w tym celu.

Klasa pomocnika jets prostą klasą. Powiedzmy, że potrzebujemy klasę pomocnika o nazwie 'fooBar'. Domyślnie nazwa klasy jest poprzedzona przedrostkiem 'Zend_View_Helper_' (możesz określić własny przedrostek podczas ustawiania ścieżki do klas pomocników), a ostatni segment nazwy klasy jest nazwą klasy pomocnika; ten segment powinien być w postaci TitleCapped; pełna nazwa klasy wygląda więc tak: Zend_View_Helper_FooBar. Ta klasa powinna zawierać przynajmniej jedną metodę, nazwaną tak jak klasa pomocnika, ale już w postaci camelCased: fooBar().

[Notatka] Notatka

Nazwy klas pomocników są zawsze w postaci camelCased, czyli nigdy nie zaczynają się wielką literą.

Aby użyć pomocnika w swoim skrypcie widoku, wywołaj go za pomocą $this->nazwaPomocnika(). Obiekt Zend_View załaduje klasę Zend_View_Helper_NazwaPomocnika, utworzy obiekt tej klasy i wywoła metodę nazwaPomocnika(). Instancja obiektu istnieje teraz w instancji Zend_View i będzie ona ponownie używana przy następnych wywołaniach $this->nazwaPomocnika().

35.4.1. Wbudowane klasy pomocników

Zend_View posiada wbudowany zbiór klas pomocników, z których większość odnosi się do generowania formularzy, a każda z nich autmatycznie filtruje dane wyjściowe. Dodatkowo dostępne są klasy pomocników służące do tworzenia adresów URL na podstawie tras, do tworzenia list HTML oraz do deklarowania zmiennych. Obecnie dostępne klasy pomocników to:

  • declareVars(): Głównie używana gdy używamy metody strictVars(), ta klasa pomocnika może być użyta do zadeklarowania zmiennych szablonu, które zostały ustawione lub nie, w obiekcie widoku. Możemy też użyć jej do ustawienia domyślnych wartości. Tablice przekazane do metody jako argumenty zostaną użyte do ustawienia domyślnych wartości; w przeciwnym razie, gdy zmienna nie istnieje, zostanie ustawiona jako pusty łańcuch znaków.

  • formButton($name, $value, $attribs): Tworzy element <input type="button" />.

  • formCheckbox($name, $value, $attribs, $options): Tworzy element <input type="checkbox" />. Parametr $options jest tablicą w której pierwszy element jest wartością dla pola zaznaczonego ("checked"), a drugi wartością dla niezaznaczonego ("unchecked") (domyślnie są to wartości '1' i '0'). Jeśli wartość $value odpowiada wartości pola zaznaczonego ("checked"), to pole zostanie zaznaczone.

  • formFile($name, $value, $attribs): Tworzy element <input type="file" />.

  • formHidden($name, $value, $attribs): Tworzy element <input type="hidden" />.

  • formLabel($name, $value, $attribs): Creates a <label> element, setting the for attribute to $name, and the actual label text to $value. If disable is passed in attribs, nothing will be returned.

  • formPassword($name, $value, $attribs): Tworzy element <input type="password" />.

  • formRadio($name, $value, $attribs, $options): Tworzy serię elementów <input type="radio" />, po jednym dla każdego elementu tablicy $options. W tablicy $options, klucz jest wartością przycisku radio, a wartość elementu tablicy jest etykietą przycisku radio. Zmienna $value określa wartość przycisku, który ma być początkowo zaznaczony.

  • formReset($name, $value, $attribs): Tworzy element <input type="reset" />.

  • formSelect($name, $value, $attribs, $options): Tworzy blok <select>...</select>, z elementami <option> po jednym dla każdego elementu tablicy $options. W tablicy $options klucz jest wartościa elementu, a wartość jest etykietą. Zmienna $value określa wartośc elementu (lub elementów), który ma być początkowo zaznaczony.

  • formSubmit($name, $value, $attribs): Tworzy element <input type="submit" />.

  • formText($name, $value, $attribs): Tworzy element <input type="text" />.

  • formTextarea($name, $value, $attribs): Tworzy element <textarea>...</textarea>.

  • url($urlOptions, $name, $reset): Tworzy adres URL na podstawie nazwy trasy. Parametr $urlOptions powinien być tablicą asocjacyjną zawierającą pary klucz/wartość używane przez daną trasę.

  • htmlList($items, $ordered, $attribs): generuje uporządkowane oraz nieuporządkowane listy na podstawie przekazanego do niej parametru $items. Jeśli parametr $items jest wielowymiarową tablicą, zostanie zbudowana lista zagnieżdżona.

Użycie tych metod w Twoim skrypcie jest bardzo łatwe, poniżej znajduje się przykład. Zauważ, że wszystko czego potrzebujesz to wywołanie tych metod; załadowanie ich i utworzenie instancji odbędzie się automatycznie.

<?php
// wewnątrz skryptu widoku, $this odnosi się do instancji Zend_View.
// 
// załóżmy, że już przypisałeś serię elementów opcji jako tablicę
// o nazwie $countries = array('us' => 'United States', 'il' =>
// 'Israel', 'de' => 'Germany').
?>
<form action="action.php" method="post">
    <p><label>Adres Email:
        <?php echo $this->formText('email', 'you@example.com', array('size' => 32)) ?>
    </label></p>
    <p><label>Kraj:
        <?php echo $this->formSelect('country', 'us', null, $this->countries) ?>
    </label></p>
    <p><label>Czy zgadzasz się?
        <?php echo $this->formCheckbox('opt_in', 'yes', null, array('yes', 'no')) ?>
    </label></p>
</form>
        

Rezultat wyglądałby w ten sposób:

<form action="action.php" method="post">
    <p><label>Adres Email:
        <input type="text" name="email" value="you@example.com" size="32" />
    </label></p>
    <p><label>Kraj:
        <select name="country">
            <option value="us" selected="selected">United States</option>
            <option value="il">Israel</option>
            <option value="de">Germany</option>
        </select>
    </label></p>
    <p><label>Czy zgadzasz się?
        <input type="hidden" name="opt_in" value="no" />
        <input type="checkbox" name="opt_in" value="yes" checked="checked" />
    </label></p>
</form>
        

35.4.2. Ścieżki klas pomocników

Tak jak ze skryptami widoków, kontroler może określić stos ścieżek, w których Zend_View ma szukać klas pomocników. Domyślnie Zend_View szuka klas pomocników w katalogu "Zend/View/Helper/*". Możesz wybrać inny katalog używając metod setHelperPath() oraz addHelperPath(). Dodatkowo możesz określić przedrostek klas pomocników znajdujących się w podanej ścieżce aby utworzyć przestrzenie nazw dla klas pomocników. Domyślnie, gdy żaden przedrostek nie zostanie określony, przyjęty zostanie przedrostek 'Zend_View_Helper_'.

<?php
$view = new Zend_View();
// Ustaw ścieżkę na /path/to/more/helpers, z przedrostkiem 'My_View_Helper'
$view->setHelperPath('/path/to/more/helpers', 'My_View_Helper');
?>
        

Oczywiście możesz dodawać ścieżki na stos używająć metody addHelperPath(). Gdy dodajesz ścieżki na stos, Zend_View będzie szukać klasy pomocnika począwszy od ostatnio dodanej ścieżki. To pozwala na dodanie (lub nawet nadpisanie) podstawowego pakietu klas pomocników swoimi własnymi klasami.

<?php
$view = new Zend_View();
// Add /path/to/some/helpers with class prefix 'My_View_Helper'
$view->addHelperPath('/path/to/some/helpers');
// Add /other/path/to/helpers with class prefix 'Your_View_Helper'
$view->addHelperPath('/other/path/to/helpers');

// teraz kiedy wywołasz $this->helperName(), Zend_View będzie wpierw szukał w
// "/other/path/to/helpers/HelperName.php" używając nazwy klasy "My_View_Helper_HelperName", 
// następnie w "/path/to/some/helpers/HelperName" używając nazwy klasy "Your_View_Helper_HelperName", 
// i ostatecznie w "Zend/View/Helper/HelperName.php" używając nazwy klasy "Zend_View_Helper_HelperName".
?>
        

35.4.3. Pisanie własnych klas pomocników

Pisanie własnych klas pomocników jest łatwe; po prostu pisz według poniższych zasad:

  • Minimalna nazwa klasy musi kończyć się nazwą pomocnika przy użyciu CamelCaps. Przykładowo, jeśli piszesz klasę pomocnika zwaną "specialPurpose", minimalną nazwą klasy musi być "SpecialPurpose". Możesz, a nawet powinieneś nadać nazwie klasy przedrostek i jest zalecane, abyś użył 'View_Helper' jako części przedrostka: "My_View_Helper_SpecialPurpose". (Przedrostek będziesz musiał przekazać wraz z końcowym znakiem podkreślenia lub bez niego, do metod addHelperPath() oraz setHelperPath()).

  • Klasa musi posiadać publiczną metodę która jest taka jak nazwa pomocnika; jest to metoda która zostanie wywołana gdy skrypt widoku wywoła "$this->twojPomocnik()". W przykładzie pomocnika "twojPomocnik", wymaganą deklaracją metody powinno być "public function twojPomocnik()".

  • Klasa nie powinna wyświetlać ani w inny sposób generować danych wyjściowych. Zamiast tego powinna zwrócić dane do wyświetlenia. Zwracane wartości powinny być odpowiednio przefiltrowane.

  • Klasa musi znajdować się w pliku odpowiednio do nazwy metody pomocnika. Przykładowo dla pomocnika o nazwie "twojPomocnik", plik powinien nazywać się "TwojPomocnik.php".

Umieść plik klasy pomocnika w katalogu który był dodany do stosu ścieżek, a Zend_View automatycznie załaduje klasę, utworzy instancję, i uruchomi metodę.

Poniżej przykład kodu naszego przykładowego pomocnika twojPomocnik:

<?php
class My_View_Helper_TwojPomocnik 
{
    protected $_count = 0;
    public function twojPomocnik()
    {
        $this->_count++;
        $output = "I have seen 'The Jerk' {$this->_count} time(s).";
        return htmlspecialchars($output);
    }
}
?>
        

Teraz w skrypcie widoku możesz wywołać pomocnika TwojPomocnik tyle razy ile zechcesz; instancja zostanie utworzona raz i będzie ona istniała przez cały okres istnienia instancji Zend_View.

<?php
// pamiętaj, że w skrypcie widoku $this odnosi się do instancji Zend_View.
echo $this->twojPomocnik();
echo $this->twojPomocnik();
echo $this->twojPomocnik();
?>
        

Dane wyjściowe wyglądałyby w ten sposób:

I have seen 'The Jerk' 1 time(s).
I have seen 'The Jerk' 2 time(s).
I have seen 'The Jerk' 3 time(s).
        

Czasem możesz potrzebować uzyskać dostęp do obiektu Zend_View -- na przykład, jeśli potrzebujesz użyć zarejestrowanego kodowania, lub chcesz zrenderować inny skrypt widoku jako część klasy pomocnika. Aby uzyskać dostęp do obiektu widoku, klasa pomocnika powinna posiadać metodę setView($view), tak jak poniżej:

<?php
class My_View_Helper_ScriptPath
{
    public $view;

    public function setView(Zend_View_Interface $view)
    {
        $this->view = $view;
    }

    public function scriptPath($script)
    {
        return $this->view->getScriptPath($script);
    }
}
?>

Jeśli twoja klasa pomocnika posiada metodę setView(), będzie ona wywołana wtedy, gdy po raz pierwszy zostanie utworzona instancja klasy pomocnika i przekazany zostanie obecny obiekt widoku. Jest to po to, aby przechować obiekt widoku w klasie pomocnika, a także po to, aby określić w jaki sposób powinno się uzyskiwać do tego obiektu dostęp.