datafilter Search and filtration capabilities for data grids

  1. Documentation
  2. Change Log

This extension can be used to add search and filtration capabilities to data grids.



  • Tested on Yii 1.0.8
  • Extract the release file under protected/extensions

Documentation updated for version 0.2. Documentation for version 0.1 can be found in CDataFilter.php.


Inside controller:

public function actionAdmin()

        $criteria=new CDbCriteria;

        //filters group for Group, City, Country, group object created explicitly
        $fromGroup = new CFilterGroup('Filter', array('cssClass'=>'dataFilterBlock'));
        $fromFilterOptions = array('emptyValue'=>'All', 'specialOptions'=>array('null'=>'None'));

        //filters group for Group and City without autosubmit, used custom view
        $filterNoAutoGroup = new CFilterGroup('Filter (no autosubmit)',

        $filters = new CDataFilter(User::model());
        $filters->addFilter(new CFilterSearch('userFieldsSearch'), 'Search');
        $filters->addFilter(new CFilterDropdown('Group', $fromFilterOptions), $fromGroup);
        $filters->addFilter(new CFilterDropdown('Country', $fromFilterOptions), $fromGroup);
        $filters->addFilter(new CFilterDropdown('City', $fromFilterOptions), $fromGroup);

        $filters->addFilter(new CFilterDropdown('activeDropFilter',
            //group is given as name (string), not as object
            //this filter will be joined to 'Filter' group, because group with same name already exists

        // two filters without autosubmit
        // submit button is placed in custom view (see views/user/dataFilterGroupWithSubmit.php)
        $filters->addFilter(new CFilterDropdown('groupFilter2',
                array('displayName'=>'Group', 'emptyValue'=>'All', 'specialOptions'=>array('null'=>'None'),
            ), $filterNoAutoGroup
        $filters->addFilter(new CFilterDropdown('countryFilter2',
                array('displayName'=>'Country', 'emptyValue'=>'All', 'specialOptions'=>array('null'=>'None'),
            ), $filterNoAutoGroup

        // two link filters, all users is a default filter (highlighted if no other filters applied)
        $filters->addFilter(new CFilterLink('activeFilter', 'All Users', 'all', true), 'Show');
        $filters->addFilter(new CFilterLink('activeFilter', 'Active Users', 'active'), 'Show');


        $pages=new CPagination(User::model()->count($criteria));

        $sort=new CSort('User');


            'models', 'pages', 'sort', 'filters'

Model should provide following methods:

  • getDataFilterOptions($filterName) for CFilterDropdown and CFilterLink
  • getDataFilterSearchFields($filterName) for CFilterSearch
  • applyDataFilterCriteria(&$criteria, $filterName, $filterValue) for CFilterDropdown and CFilterLink
  • applyDataSearchCriteria(&$criteria, $filterName, $searchField, $serachValue) for CFilterSearch

Inside model:

// Returns list of searchable fileds for DataFilter widget
    public function getDataFilterSearchFields($filterName)
        switch ($filterName) {
            case 'userFieldsSearch': //filter name
                return array(
                    ''=>'User ID', //field name => display name

    // Applies search criteria enterd using DataFilter widget
    public function applyDataSearchCriteria(&$criteria, $filterName, $searchField, $searchValue)
        if($filterName == 'userFieldsSearch') {
            $localCriteria = new CDbCriteria;
            $localCriteria->condition = ' '.$searchField.' LIKE "%'.$searchValue.'%" ';
            //$localCriteria->condition = ' '.$searchField.' LIKE "%:searchValue%" ';
            //$localCriteria->params = array(':searchValue'=>$searchValue); //"'%1%'" //".$searchValue."

    // Returns options for DataFilter widget
    public function getDataFilterOptions($filterName)
        switch ($filterName) {
            case 'Group':  //filter name
            case 'groupFilter2':
                // data from database
                $groups = Group::model()->findAll();
                return CHtml::listData($groups, 'id', 'name');
            case 'Country':
            case 'countryFilter2':
                $countries = Country::model()->findAll();
                return CHtml::listData($countries, 'id', 'name');
            case 'City':
                $criteria = new CDbCriteria;
                $country = Yii::app()->request->getParam('countryFilter');
                // city filter depends from country filter
                if (isset($country) && !empty($country)) {
                    $criteria->condition = ' countries_id = :country';
                    $criteria->params = array(':country'=>$country);
                $cities = City::model()->findAll($criteria);
                return CHtml::listData($cities, 'id', 'name');
           case 'activeDropFilter':
                // static data (not from database)
                $options = array(
                    array('id'=>'', 'name'=>'All'),
                    array('id'=>0, 'name'=>'Not active'),
                    array('id'=>1, 'name'=>'Active'),
                return CHtml::listData($options, 'id', 'name');

    // Applies filter criteria enterd using DataFilter widget
    public function applyDataFilterCriteria(&$criteria, $filterName, $filterValue)
        if($filterName == 'Group' || $filterName == 'groupFilter2') {
            $localCriteria = new CDbCriteria;
            CDataFilter::setCondition('user_groups_id', $filterValue, $localCriteria);

        if($filterName == 'Country' || $filterName == 'countryFilter2') {
            $localCriteria = new CDbCriteria;
            //'null' value is a spectial option for coutryFilter
            if ($filterValue != 'null') {
                $localCriteria->select = 'df_users.*';
                $localCriteria->join =
                    'INNER JOIN `df_cities` cities
                    ON (`df_users`.`cities_id`=cities.`id`)
                    AND (cities.countries_id = :countryID) ';
                $localCriteria->params = array(':countryID'=>$filterValue);
                //$localCriteria->group = ' ';
            } else {
                $localCriteria->condition = ' cities_id is null ';

        if($filterName == 'City') {
            $localCriteria = new CDbCriteria;
            CDataFilter::setCondition('cities_id', $filterValue, $localCriteria);

        if($filterName == 'activeFilter') {
            if ($filterValue !== 'active') return;
            $localCriteria = new CDbCriteria;
            CDataFilter::setCondition('is_active', 1, $localCriteria);

        if($filterName == 'activeDropFilter') {
            $localCriteria = new CDbCriteria;
            CDataFilter::setCondition('is_active', $filterValue, $localCriteria);


Inside view:

<?php $this->widget('CDataFilterWidget',array('filters'=>$filters)); ?>


// enable ajax filtering / searching - '#updateData' selector will be replaced
<?php $this->widget('CDataFilterWidget',array('filters'=>$filters,
       'ajaxMode'=>true, 'updateSelector'=>'#updateData')); ?>

Change Log

October 17, 2009 (v0.3)
  • fixed bug: wrong CFilterBase::applyCriteria declaration (reported by PHP when E_STRICT is enabled)
September 18, 2009 (v0.3)
  • CDataFilterWidget: options to generate submit and reset buttons
  • CDataFilter: option to store filter state to the session
  • Demo app: added a tab 'Users(no autosubmit)' - demo for Reset / Submit and store to session
  • Demo App: text descriptions for each demo tab
  • Fixed: Did not work on servers where appplication work not in root folder (added normalizeUrl() for form action)
September 4, 2009 (v0.2)
  • Demo application (including demo for ajax mode)
  • Ability to turn of autosubmit (submit after changed) for dropdown filters
  • Filter's form configuration - ability to set action, method and options
  • Filters group can be configured to use custom view
  • Filters can be grouped together
  • New filter type - CFilterLink - outputs a set of links to filter table data
  • Fixed: zero values treated as default and empty. Now zero values can be used as filters values.
  • Refactoring - base class for filter and subclasses for different filter types CFilterDropdown for dropdown filters, CFilterSearch - for search
July 18, 2009
  • Initial release.
4 0
2 707 downloads
Yii Version: 1.1
License: BSD-2-Clause
Category: User Interface
Developed by: seb
Created on: Jul 18, 2009
Last updated: 12 years ago


show all