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

Использование расширений
========================

Порядок использования расширений, как правило, включает три шага:

  1. Скачать расширение из [репозитория расширений](http://www.yiiframework.com/extensions/) Yii;
  2. Распаковать расширение в поддиректорию `extensions/xyz`
     [базовой директории приложения](/doc/guide/basics.application#application-base-directory),
     где `xyz` — имя расширения;
  3. Подключить, настроить и использовать расширение.

Каждое расширение уникально идентифицируется по имени. Если расширение
называется `xyz`, то, используя псевдоним пути `ext.xyz`, мы всегда можем
определить директорию, в которой хранятся файлы этого расширения.

Разные расширения предъявляют различные требования к подключению, настройке и порядку их
использования. Ниже мы приведём несколько общих вариантов использования
расширений согласно классификации, представленной в
[обзоре](/doc/guide/extension.overview).

Расширения Zii
--------------

Перед тем как рассказать об использовании сторонних расширений, стоит упомянуть
библиотеку расширений Zii — набор расширений, разрабатываемый командой Yii и
включаемый в каждую новую версию.

При использовании расширения Zii необходимо обращаться к соответствующим классам,
используя псевдоним пути вида `zii.path.to.ClassName`. Здесь `zii` — предопределённый
в Yii маршрут, соответствующий корневой директории библиотеки Zii. К примеру, чтобы
воспользоваться [CGridView], необходимо использовать в шаблоне представления следующий код:

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

Компонент приложения
---------------------

Для использования [компонента приложения](/doc/guide/basics.application#application-component)
в первую очередь необходимо изменить
[конфигурацию приложения](/doc/guide/basics.application#application-component),
добавив новый элемент в свойство `components`:

~~~
[php]
return array(
    // 'preload'=>array('xyz',…),
    'components'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // прочие настройки компонентов
    ),
);
~~~

Теперь можно обращаться к компоненту в любом месте приложения через
`Yii::app()->xyz`. Компонент будет создан в момент первого
обращения к нему (т.е. будет произведена отложенная загрузка), если мы не укажем его в свойстве `preload`.

Поведение
---------

[Поведение](/doc/guide/basics.component#component-behavior) может быть
использовано в любом компоненте. Делается это в два шага: присоединение
к компоненту и вызов метода поведения из компонента. Например:

~~~
[php]
// $name уникально идентифицирует поведение внутри компонента
$component->attachBehavior($name,$behavior);
// test() является методом $behavior
$component->test();
~~~

Чаще всего поведение присоединяется к компоненту в ходе его конфигурирования, а
не посредством вызова метода `attachBehavior`. К примеру, чтобы присоединить поведение к
[компоненту приложения](/doc/guide/basics.application#application-component),
мы можем использовать следующую
[конфигурацию приложения](/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',
				),
			),
		),
		//…
	),
);
~~~

Приведённый выше код присоединяет поведение `xyz` к компоненту приложения `db`.
Это возможно, так как [CApplicationComponent] определяет свойство `behaviors`.
При инициализации компонент присоединит перечисленные в нём поведения.

Для классов [CController], [CFormModel] и [CActiveRecord], которые необходимо расширять,
присоединение поведений происходит при помощи переопределения метода `behaviors()`.
При инициализации классы автоматически присоединят поведения, объявленные в этом методе.
Например:

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

Виджет
------

Виджеты в основном используются в представлениях. Виджетом класса `XyzClass`,
входящим в состав расширения `xyz`, можно воспользоваться в представлении следующим образом:

~~~
[php]
// виджет без внутреннего содержимого
<?php $this->widget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>

// виджет, который может иметь внутреннее содержимое
<?php $this->beginWidget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>

…содержимое виджета…

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

Действие
------

[Действия](/doc/guide/basics.controller#action) используются в
[контроллерах](/doc/guide/basics.controller) для обработки запросов
пользователя. Действие класса `XyzClass`, входящее в расширение `xyz`, можно использовать
путём переопределения метода [CController::actions] класса нашего контроллера:

~~~
[php]
class TestController extends CController
{
	public function actions()
	{
		return array(
			'xyz'=>array(
				'class'=>'ext.xyz.XyzClass',
				'property1'=>'value1',
				'property2'=>'value2',
			),
			// прочие действия
		);
	}
}
~~~

Теперь к действию можно обратиться по [маршруту](/doc/guide/basics.controller#route)
`test/xyz`.

Фильтры
------
[Фильтры](/doc/guide/basics.controller#filter) также используются в
[контроллерах](/doc/guide/basics.controller). В основном они используются в
[действиях](/doc/guide/basics.controller#action) для осуществления пред- и
пост-обработки пользовательского запроса. Фильтр класса `XyzClass`, входящий в расширение
`xyz`, можно использовать путём переопределения метода [CController::filters]
в нашем классе контроллера:

~~~
[php]
class TestController extends CController
{
	public function filters()
	{
		return array(
			array(
				'ext.xyz.XyzClass',
				'property1'=>'value1',
				'property2'=>'value2',
			),
			// прочие фильтры
		);
	}
}
~~~

Выше мы можем использовать операторы '+' и '-' в первом элементе массива для
применения фильтра только к определенным действиям. Подробнее ознакомиться с этим можно
в документации к [CController].

Контроллер
----------

[Контроллер](/doc/guide/basics.controller) предоставляет набор действий,
которые могут быть запрошены пользователем. Для использования расширения
контроллера необходимо настроить свойство [CWebApplication::controllerMap] в
[конфигурации приложения](/doc/guide/basics.application#application-configuration):

~~~
[php]
return array(
	'controllerMap'=>array(
		'xyz'=>array(
			'class'=>'ext.xyz.XyzClass',
			'property1'=>'value1',
			'property2'=>'value2',
		),
		// прочие контроллеры
	),
);
~~~

Теперь к действию `a` контроллера можно обратиться через
[маршрут](/doc/guide/basics.controller#route) `xyz/a`.

Валидатор
---------
Валидатор используется в классе [модели](/doc/guide/basics.model), наследующем
[CFormModel] или [CActiveRecord]. Класс валидатора `XyzClass` расширения
`xyz` используется путём переопределения метода [CModel::rules] в нашем классе
модели:

~~~
[php]
class MyModel extends CActiveRecord // или CFormModel
{
	public function rules()
	{
		return array(
			array(
				'attr1, attr2',
				'ext.xyz.XyzClass',
				'property1'=>'value1',
				'property2'=>'value2',
			),
			// прочие правила проверки
		);
	}
}
~~~

Команда консоли
---------------
Расширение [консольной команды](/doc/guide/topics.console), как правило,
используется для добавления новой команды в утилиту `yiic`. Консольную команду
`XyzClass` расширения `xyz` можно использовать, настроив конфигурацию
консольного приложения:

~~~
[php]
return array(
	'commandMap'=>array(
		'xyz'=>array(
			'class'=>'ext.xyz.XyzClass',
			'property1'=>'value1',
			'property2'=>'value2',
		),
		// прочие команды
	),
);
~~~

Теперь в утилите `yiic` доступна ещё одна команда `xyz`.

> Note|Примечание: Консольное приложение, как правило, использует иной файл
конфигурации, нежели веб-приложение. Если приложение было создано командой
консоли `yiic webapp`, то конфигурационный файл для консоли `protected/yiic`
находится в `protected/config/console.php`, а конфигурация веб-приложения — в
`protected/config/main.php`.

Модуль
------
Информация о порядке использования и создания модулей представлена в разделе
[Модуль](/doc/guide/basics.module#using-module).

Компонент общего вида
-----------------
Чтобы использовать [компонент](/doc/guide/basics.component) общего вида,
нужно для начала подключить его класс:

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

Теперь мы можем создать экземпляр этого класса, устанавливать свойства
и вызывать его методы. Кроме того, его можно расширить путём создания дочерних
классов.

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