Używanie rozszerzeń

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

1. Pobranie rozszerzenia z repozytorium rozszerzeń Yii.
2. Rozpakowania rozszerzenia do katalogu extensions/xyz będącego podkatalogiem głównego folderu aplikacji, 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.

1. Rozszerzenie Zii ¶

Zanim rozpoczniemy opisywanie 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:

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

2. Komponent aplikacji ¶

Aby używać komponentu aplikacji musimy najpierw zmienić konfigurację aplikacji poprzez dodawanie nowego wpisu do jej właściwości components, w następujący sposób:

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.

3. Zachowanie (ang. Behavior) ¶

Zachowanie 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:

// $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, powinniśmy użyć następującej konfiguracji aplikacji:

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:

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

4. Widżet ¶

Widżety są głownie używane w widokach. Biorąc pod uwagę widżet klasy XyzClass należący do rozszerzenia xyz, możemy go używać w następujący sposób,

// 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(); ?>

5. Akcja ¶

Akcje są używane przez kontroler 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:

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ę test/xyz.

6. Filtr ¶

Filtry są również używane w kontrolerze. Przetwarzają głównie żądania użytkownika na początku (ang. pre) i na końcu (ang. post), kiedy jest ono obsługiwane przez akcje. 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:

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.

7. Kontroler ¶

Kontroler 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:

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 xyz/a.

8. Walidator ¶

Walidator jest głównie stosowany w klasie modelu (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:

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
        );
    }
}

9. Konsola poleceń ¶

Rozszerzenie konsoli poleceń 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:

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.

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.

10. Moduł ¶

Proszę zobacz sekcję dotyczącą modułów aby zobaczyć jak używać modułów.

11. Komponenty generyczne ¶

Aby używać generycznych komponentów, 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.