yii/docs/guide/pl/extension.use.txt

Używanie rozszerzeń
================

Używanie rozszerzeń zwykle obejmuje następujące trzy kroki:

  1. Pobranie rozszerzenia z [repozytorium rozszerzeń Yii](http://www.yiiframework.com/extensions/).
  2. Rozpakowania rozszerzenia do katalogu `extensions/xyz` będącego podkatalogiem 
     [głównego folderu aplikacji](/doc/guide/basics.application#application-base-directory),
     gdzie `xyz` jest nazwą rozszerzenia.
  3. Import, konfiguracja i używanie rozszerzenia.


Każde rozszerzenie posiada nazwę, która jednoznacznie identyfikuje ją spośród 
wszystkich rozszerzeń. Biorąc pod uwagę rozszerzenie nazwane `xyz`, możemy zawsze 
użyć aliasu ścieżki `ext.xyz` by zlokalizować jego główny katalog, 
który zawiera wszystkie pliki z `xyz`.

Różne rozszerzenia posiadają różne wymagania dotyczące importowania, konfiguracji
oraz użycia. W dalszej części, podsumujemy najczęściej używane scenariusze dotyczące
rozszerzeń, zgodnie z kategoriami opisanymi w [przeglądzie](/doc/guide/extension.overview).

Rozszerzenie Zii
--------------

Zanim rozpoczniemy opisuywanie jak używać rozszerzenia firm trzecich, chcielibyśmy przedstawić
bibliotekę rozszerzeń Zii, która jest zestawem rozszerzeń oprogranowanych przez zespół  
programistów Yii. Jest ona dołączana do każdego wydania.

Podczas używanie rozszerzenia Zii, należy odnosić się do odpowiednich klas używając aliasu ścieżki
w formacie `zii.ścieżka.do.NazwyKlasy`. Główny alias  `zii` został zdefiniowany w Yii. Wskazuje on na 
główny katalog biblioteki Zii. Na przykład, aby używać klasy [CGridView], będziemy używali 
następującego kodu w skrypcie widoku gdy będziemy odnosić się do rozszerzenia:

~~~
[php]
$this->widget('zii.widgets.grid.CGridView', array(
	'dataProvider'=>$dataProvider,
));
~~~



Komponent aplikacji
---------------------

Aby używać [komponentu aplikacji](/doc/guide/basics.application#application-component)
musimy najpierw zmienić [konfigurację aplikacji](/doc/guide/basics.application#application-configuration)
poprzez dodawanie nowego wpisu do jej właściwości `components`, w następujący sposób:

~~~
[php]
return array(
    // 'preload'=>array('xyz',...),
    'components'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // pozostałe konfiguracje komponentów
    ),
);
~~~

Następnie możemy uzyskać dostęp do komponentu w każdym miejscu używając `Yii::app()->xyz`.
Komponent zostanie leniwie stworzony (to znaczy, będzie utworzony wtedy gdy zażądamy
dostępu do niego po raz pierwszy) chyba, że wpiszemy go do właściwości `preload`.

Zachowanie (ang. Behavior)
--------

[Zachowanie](/doc/guide/basics.component#component-behavior) może być używane w różnego
rodzaju komponentach. Jego użycie obejmuje dwa kroki. W Pierwszym kroku zachowanie jest 
dołączane do komponentu docelowego. W drugim kroku metoda zachowania wywoływana jest 
poprzez komponent docelowy. Na przykład:

~~~
[php]
// $name jednoznacznie identyfikuje zachowanie w komponencie
$component->attachBehavior($name,$behavior);
// test() jest metodą zachowanie $behavior
$component->test();
~~~

Częściej zachowanie jest dołączane do komponentu w sposób configurowalny zamiast wywoływania
metody `attachBehavior`. Na przykład aby dołączyć zachowanie do 
[komponentu aplikacji](/doc/guide/basics.application#application-component), powinniśmy
użyć następującej [konfiguracji aplikacji](/doc/guide/basics.application#application-configuration):

~~~
[php]
return array(
  'components'=>array(
    'db'=>array(
      'class'=>'CDbConnection',
      'behaviors'=>array(
        'xyz'=>array(
          'class'=>'ext.xyz.XyzBehavior',
          'property1'=>'value1',
          'property2'=>'value2',
        ),
      ),
    ),
    //....
  ),
);
~~~

Powyższy kod załącza zachowanie `xyz` do komponentu aplikacji `db`. Możemy tak 
zrobić ze wzdlędu na to, że [CApplicationComponent] definiuje właściwość o nazwie `behaviors`.
Poprzez przypisanie tej właściwości listy zawierającej konfigurację zachowań, komponent 
dołączy odpowiednie zachowanie w momencie inicjalizacji komponentu.

Dla klas [CController], [CFormModel] oraz [CActiveRecord], które zazwyczaj są rozszerzane dołączanie zachowań może odbywać się poprzez nadpisanie ich metody `behaviors()`. Klasy automatycznie dołączą każde zachowanie zadeklarowane w tej metodzie podczas inicjalizacji. Na przukład:

~~~
[php]
public function behaviors()
{
  return array(
    'xyz'=>array(
      'class'=>'ext.xyz.XyzBehavior',
      'property1'=>'value1',
      'property2'=>'value2',
    ),
  );
}
~~~


Widżet
------

[Widżety](/doc/guide/basics.view#widget) są głownie używane w [widokach](/doc/guide/basics.view).
Biorąc pod uwagę widżet klasy `XyzClass` należący do rozszerzenia `xyz`, możemy go używać 
w następujący sposób,

~~~
[php]
// widżet który nie potrzebuje zawartości 
<?php $this->widget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>

// widżet, który posiada zawartość 
<?php $this->beginWidget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>

...zawartość widżetu...

<?php $this->endWidget(); ?>
~~~

Akcja
------

[Akcje](/doc/guide/basics.controller#action) są używane przez [kontroler](/doc/guide/basics.controller)
aby odpowiadać na konkretne żądania użytkownika. Biorąc pod uwagę klasę akcji `XyzClass` należącą do rozszerzenia 
`xyz`, możemy ją używać poprzez nadpisanie metody [CController::actions] w klasie naszego
kontrolera:

~~~
[php]
class TestController extends CController
{
	public function actions()
	{
		return array(
			'xyz'=>array(
				'class'=>'ext.xyz.XyzClass',
				'property1'=>'value1',
				'property2'=>'value2',
			),
			// other actions
		);
	}
}
~~~

Następnie, możemy uzyskać dostęp do akcji poprzez [trasę](/doc/guide/basics.controller#route)
`test/xyz`.

Filtr
------
[Filtry](/doc/guide/basics.controller#filter) są również używane w [kontrolerze](/doc/guide/basics.controller).
Przetwarzają głównie żądania użytkownika na początku (ang. pre) i na końcu (ang. post), kiedy 
jest ono obsługiwane przez [akcje](/doc/guide/basics.controller#action).
Biorąc pod uwagę klasę `XyzClass` należącą do rozszerzenie `xyz`, możemy jej użyć
poprzez nadpisanie metody [CController::filters] w klasie naszego kontrolera:

~~~
[php]
class TestController extends CController
{
	public function filters()
	{
		return array(
			array(
				'ext.xyz.XyzClass',
				'property1'=>'value1',
				'property2'=>'value2',
			),
			// pozostałe filtry
		);
	}
}
~~~

Powyżej, możemy użyć operatorów dodawania i odejmowania w pierwszym elemencie tablicy,
aby zastosować filtr tylko do pewnych akcji. Aby uzyskać więcej szczegółów, zobacz
dokumentację klasy kontrolera [CController].

Kontroler
----------
[Kontroler](/doc/guide/basics.controller) dostarcza zbioru akcji, które mogą być 
żądane przez użytkowników. W celu użycia rozszerzenia kontrolera, potrzebujemy
skonfigurować właściwość [CWebApplication::controllerMap] w [konfiguracji 
aplikacji](/doc/guide/basics.application#application-configuration):

~~~
[php]
return array(
	'controllerMap'=>array(
		'xyz'=>array(
			'class'=>'ext.xyz.XyzClass',
			'property1'=>'value1',
			'property2'=>'value2',
		),
		// other controllers
	),
);
~~~

Następnie możemy uzyskać dostęp do akcji `a` w kontrolerze za pomocą 
[trasy](/doc/guide/basics.controller#route) `xyz/a`.

Walidator
---------
Walidator jest głównie stosowany w klasie [modelu](/doc/guide/basics.model) 
(które rozszerzają zarówno [CFormModel] jak i [CActiveRecord]).
Biorąc pod uwagę klasę walidatora `XyzClass` należącego do rozszerzenia `xyz`, 
możemy użyć go poprzez nadpisanie metody [CModel::rules] w klasie naszego modelu:

~~~
[php]
class MyModel extends CActiveRecord // lub CFormModel
{
	public function rules()
	{
		return array(
			array(
				'attr1, attr2',
				'ext.xyz.XyzClass',
				'property1'=>'value1',
				'property2'=>'value2',
			),
			// pozostałe reguły walidacji
		);
	}
}
~~~

Konsola poleceń
---------------
Rozszerzenie [konsoli poleceń](/doc/guide/topics.console) zazwyczaj wyposaża narzędzie 
`yiic` w dodatkowe polecenie. Biorąc pod uwagę polecenie konsoli `XyzClass` 
należące do rozszerzenia `xyz`, możemy użyć go poprzez skonfigurowanie konfiguracji
dla aplikacji konsolowej:

~~~
[php]
return array(
	'commandMap'=>array(
		'xyz'=>array(
			'class'=>'ext.xyz.XyzClass',
			'property1'=>'value1',
			'property2'=>'value2',
		),
		// pozostałe polecenia
	),
);
~~~

Teraz możemy użyć narzędzia `yiic` wyposażonego w dodatkowe polecenie `xyz`.

> Note|Uwaga: Aplikacja konsolowa zazwyczaj używa pliku konfiguracyjnego, 
który różni się od tego używanego w aplikacji sieciowej. Jeśli aplikacja została 
utworzona przy użyciu polecenia `yiic webapp`, wtedy plikiem konfiguracji dla aplikacji
konsolowej `protected/yiic` jest `protected/config/console.php`,
natomiast plikiem konfiguracyjnym aplikacji sieciowej jest `protected/config/main.php`.


Moduł
------
Proszę zobacz sekcję dotyczącą [modułów](/doc/guide/basics.module#using-module) 
aby zobaczyć jak używać modułów.


Komponenty generyczne
-----------------
Aby używać generycznych [komponentów](/doc/guide/basics.component), najpierw musimy 
dołączyć ich plik klasy używając

~~~
Yii::import('ext.xyz.XyzClass');
~~~

Następnie, możemy utworzyć instancję tej klasy, skonfigurować jej właściwości
oraz zawołać jej metody. Możemy również rozszerzyć go do tworzenia nowych
klas potomnych.

<div class="revision">$Id: extension.use.txt 2890 2011-01-18 15:58:34Z qiang.xue $</div>