Using Extensions

Using an extension usually involves the following three steps:

  1. Download the extension from Yii's extension repository.
  2. Unpack the extension under the extensions/xyz subdirectory of application base directory, where xyz is the name of the extension.
  3. Import, configure and use the extension.

Each extension has a name that uniquely identifies it among all extensions. Given an extension named as xyz, we can always use the path alias ext.xyz to locate its base directory which contains all files of xyz.

Different extensions have different requirements about importing, configuration and usage. In the following, we summarize common usage scenarios about extensions, according to their categorization described in the overview.

Zii Extensions

Before we start describing the usage of third-party extensions, we would like to introduce the Zii extension library, which is a set of extensions developed by the Yii developer team and included in every release.

When using a Zii extension, one must refer to the corresponding class using a path alias in the form of zii.path.to.ClassName. Here the root alias zii is predefined by Yii. It refers to the root directory of the Zii library. For example, to use CGridView, we would use the following code in a view script when referring to the extension:




Application Component



To use an application component,
we first need to change the application configuration
by adding a new entry to its components property, like the following:






Then, we can access the component at any place using Yii::app()->xyz. The component
will be lazily created (that is, created when it is accessed for the first time)
unless we list it the preload property.



Behavior



Behavior can be used in all sorts of components.
Its usage involves two steps. In the first step, a behavior is attached to a target component.
In the second step, a behavior method is called via the target component. For example:






More often, a behavior is attached to a component using a configurative way instead of
calling the attachBehavior method. For example, to attach a behavior to an
application component, we could
use the following
application configuration:






The above code attaches the xyz behavior to the db application component. We can do so
because CApplicationComponent defines a property named behaviors. By setting this property
with a list of behavior configurations, the component will attach the corresponding behaviors
when it is being initialized.



For CController, CFormModel and CActiveRecord classes which usually need to be extended,
attaching behaviors can be done by overriding their behaviors() method. The classes will
automatically attach any behaviors declared in this method during initialization. For example,






Widget



Widgets are mainly used in views.
Given a widget class XyzClass belonging to the xyz extension, we can use it in
a view as follows,






Action



Actions are used by a controller
to respond specific user requests. Given an action class XyzClass belonging to
the xyz extension, we can use it by overriding the CController::actions method
in our controller class:






Then, the action can be accessed via route
test/xyz.



Filter



Filters are also used by a controller.
They mainly pre- and post-process the user request when it is handled by an
action.
Given a filter class XyzClass belonging to
the xyz extension, we can use it by overriding the CController::filters method
in our controller class:






In the above, we can use plus and minus operators in the first array element
to apply the filter to limited actions only. For more details, please refer
to the documentation of CController.



Controller



A controller provides a set of actions that can
be requested by users. In order to use a controller extension, we need to
configure the CWebApplication::controllerMap property in the
application configuration:






Then, an action a in the controller can be accessed via
route xyz/a.



Validator



A validator is mainly used in a model class
(one that extends from either CFormModel or CActiveRecord).
Given a validator class XyzClass belonging to
the xyz extension, we can use it by overriding the CModel::rules method
in our model class:






Console Command



A console command extension usually enhances
the yiic tool with an additional command. Given a console command
XyzClass belonging to the xyz extension, we can use it by configuring
the configuration for the console application:






Then, we can use the yiic tool is equipped with an additional
command xyz.





Note: A console application usually uses a configuration file
  that is different from the one used by a Web application. If an application
  is created using yiic webapp command, then the configuration file
  for the console application protected/yiic is protected/config/console.php,
  while the configuration file for the Web application is protected/config/main.php.





Module



Please refer to the section about modules on how to use a module.



Generic Component



To use a generic component, we first
need to include its class file by using






Then, we can either create an instance of the class, configure its properties,
and call its methods. We may also extend it to create new child classes.



$Id$