Podstawową biblioteką Javascript dostępną w Zend Framework jest Dojo. Wybór ten został przyjęty co najmniej chłodno i był szeroko komentowany przez programistów. Zend nie czekał długo z wydaniem nowego komponentu – ZendX_JQuery. Wybrano jQuery, ponieważ biblioteka ta była wymieniana jako ta, która powinna zostać wybrana zamiast Dojo.

ZendX_JQuery nie jest tak rozbudowany jak Zend_Dojo, co nie zmienia faktu, że i tak oferuje szereg bardzo pomocnych funkcjonalności. Zanim jednak do nich przejdziemy, musimy dodać obsługę jQuery do naszego projektu.

Wymagane pliki

Oczywistym jest, że będziemy potrzebować samej biblioteki, którą można pobrać ze strony producenta. Warto również pobrać jQuery UI, ponieważ też się przyda. Proponuję pobrać całą paczkę oraz dowolny temat graficzny. Pobrane pliki rozpakowujemy do katalogu jquery w publicznym katalogu naszego projektu.

Następnie musimy do katalogu z bibliotekami skopiować ZendX z katalogu extras, który znajduje się w archiwum z plikami Zend Frameworka.

Po tym wszystkim drzewo plików i katalogów powinno wyglądać w następujący sposób:

 Struktura katalogow

Inicjalizacja

Inicjalizacja jest banalnie prosta i sprowadza się do czterech kroków:

  1. Dodanie ścieżki do helpera widoku 
    W pliku application.ini dodajemy nowy wiesz:

    resources.view.helperPath.ZendX_JQuery_View_Helper = "ZendX/JQuery/View/Helper"

    Jeśli stosujecie inny sposób dodawania helperów widoku, możecie bez obaw z niego skorzystać.

  2. Modyfikacja pliku index.php w celu dodania nowego zasobu

    W pliku index.php musimy zmienić sposób w jaki wczytywane są zasoby (resources). Zmiana ta polega na zmianie drugiego atrybutu przekazywanego do konstruktora Zend_Application.

    // Create application, bootstrap, and run
    $application = new Zend_Application(
        APPLICATION_ENV, 
        array(
    		'pluginPaths' => array(
    			'ZendX_Application_Resource' => 'ZendX/Application/Resource'
    		),
    		'config' => APPLICATION_PATH . '/configs/application.ini'
    	)
    );

  3. Konfiguracja zasobu

    Zasób konfigurujemy w pliku application.ini. Kompletny i co najważniejsze – aktualny opis konfiguracji można znaleźć w pliku ZendX/Application/Resource/JQuery.php.

    W wersji 1.10 konfiguracja ta wygląda w następujący sposób:

    • resources.Jquery.noconflictmode = false

      Ustawienie trybu kompatybilności z innymi bibliotekami Javascript 
    • resources.Jquery.version = 1.4.1

      Ustawienie wersji biblioteki, która zostanie dołączona ze zdalnego serwera

    • resources.Jquery.localpath = "/foo/bar"

      Ustawienie ścieżki do lokalnej wersji biblioteki

    • resources.Jquery.uienable = true (resources.Jquery.ui_enable = true)

      Włączenie/wyłączenie jQuery UI

    • resources.Jquery.uiversion = 0.7.7 (resources.Jquery.ui_version = 0.7.7)

      Ustawienie wersji UI

    • resources.Jquery.uilocalpath = "/bar/foo" (resources.Jquery.ui_localpath = "/bar/foo")

      Ustawienie ścieżki do lokalnego wersji biblioteki UI

    • resources.Jquery.cdn_ssl = false

      Czy zdalny plik ma być dołączony po http, czy po https.

    • resources.Jquery.render_mode = 255 (resources.Jquery.rendermode = 255)

      Ustawienie sposobu renderowania biblioteki. Spis opcji można znaleźć w dokumentacji.

    • resources.Jquery.javascriptfile = "/some/file.js"

      Jeśli chcemy dołączyć dodatkowy skrypt, powinniśmy użyć tej opcji.

    • resources.Jquery.javascriptfiles.0 = "/some/file.js"

      Jeśli chcemy dołączyć więcej niż jeden skrypt, wystarczy, że dodamy koleją opcję z numerem o 1 większym od poprzedniego.

    • resources.Jquery.stylesheet = "/some/file.css"
    • resources.Jquery.stylesheets.0 = "/some/file.css"

      Obie opcje działają tak samo jak opcje dotyczące skryptów, z tym wyjątkiem, że dołączają dodatkowe pliki css.

    Do poprawnego działania jQuery wystarczy zastosować następujące ustawienia:

    resources.Jquery.localpath = "/jquery/jquery-1.4.1.min.js"

    resources.Jquery.uilocalpath = "/jquery/jquery-ui-1.7.2.min.custom.js"

    resources.Jquery.stylesheet = "/jquery/css/smoothness/jquery-ui-1.7.2.custom.css"

    Nie zapomnijcie ustawić poprawnych ścieżek.

  4. Modyfikacja layoutu

    W pliku layoutu (np layout.phtml) musimy dodać jeden wiesz (w sekcji head)

    echo $this->jQuery();

Użycie

Po tym nieco przydługim wstępie przyszła pora na konkrety. Zaczniemy od czegoś prostego – zaktualizowanie zawartości elementu div po kliknięciu w link.

W tym celu zastosujemy helper ajaxLink.

<?php echo $this->ajaxLink('treść linka', 
						   '/index/ajax', 
						   array(
						   		'update' => '#content'
						   ),
						   array(
						   		'param1' => 'value1',
						   		'param2' => 'value2'
						   )
			);
?>

<div id="content">
	jakiś tekst
</div>

Powyższy przykład wyświetli link z tekstem “Treść linka”, pod którym wyświetlony został “jakiś tekst”.

Helper ajaxLink przyjmuje 4 parametry. Pierwszym jest tekst, jaki się wyświetli jako link, drugim jest adres, pod jaki zostanie wysłane żądanie, trzecim są opcje, a ostatnim lista parametrów, które zostaną wysłane na serwer. Spis wszystkich opcji, jakie można przekazać w trzecim parametrze, można znaleźć w dokumentacji. Opcje te są dobrze opisane, więc nie będę tego opisu powielał.

Dzięki tym opcjom mamy możliwość wysłania danych POST-em lub GET-em, czy wywołania funkcji zwrotnej.

Innym pomocnym helperem jest datepicker, z którego można skorzystać na dwa sposoby. Pierwszym jest bezpośrednie wykorzystanie helpera.

<?php echo $this->datePicker('data', 
				 null,
				 array(
				 	'minDate' => 'new Date()',
				 	'dateFormat' => 'yy-mm-dd'
				 ),
				 array(
				 	'class' => 'some-class',
				 	'readonly' => 'readonly'
				 )
			);
?>

Helper przyjmuje cztery argumenty. Pierwszym jest jego nazwa, drugim domyślna wartość, trzecim lista opcji datepicker-a, ostatnim atrybuty HTML, które zostaną dodane do znacznika. Lista opcji, które możemy zastosować jest identyczna z tymi, które  można znaleźć w dokumentacji jQuery.

Drugim sposobem użycie datepicker-a, jako elementu formularza. Dodaje się go identycznie jak pozostałe elementy formularza, można dodać do niego filtry i walidatory. Jedyną różnicą, ale za to bardzo ważną jest to, że zamiast helpera ViewRenderer, musimy zastosować helper UiWidgetElement. Poza tym nasz formularz powinien dziedziczyć po ZendX_JQuery_Form, chociaż nie jest to wymagane. Poniżej znajduje się w pełni działający przykład formularza z datepicker-em.

<?php
class Form_DatepickerExample extends ZendX_JQuery_Form
{
	public function init()
	{
		$jQueryParams = array('jQueryParams' => array(
			'dateFormat' => 'yy-mm-dd',
			'minDate' => 'new Date()'
		));
		
		$dp = new ZendX_JQuery_Form_Element_DatePicker('data', $jQueryParams);
		$dp->setLabel('Wybierz datę')
		   ->setRequired(true)
		   ->addValidator(new Zend_Validate_NotEmpty(), true)
		   ->addValidator(new Zend_Validate_Date(array('format' => 'Y-m-d')), true)
		   ->addFilter(new Zend_Filter_StringTrim());

		$this->addElement($dp);
	}
}

Jeśli modyfikowaliśmy dekoratory i ustawiliśmy, by helper ViewRederer był dodawany automatycznie do wszystkich elementów formularza, wówczas musimy pamiętać, by usunąć ten dekorator i dodać UiWidgetElement.

Opisane powyżej helpery nie są jedynymi dostępnymi w ZendX_JQuery. Pozostałe opiszę w kolejnych częściach ZendX_JQuery w praktyce.