View source for How to add custom filters to components

{{version/tutor|1.7,2.5}}{{RightTOC}}
== Overview ==
This how-to is intended to give a decent description on how to add dropdown form elements to the backend admin page for a component.  I worked out the steps primarily on my own by dissecting/replicating the Banners component.  In particular, the 'banners' section of com_banners - not! to be confused with 'banner').

In general, the process of adding these fields breaks down into the following steps:
* Creating the class that will generate the form element
* Adapting the view to display the form element 
* Adapting the model to retrieve data from DB & to set submission values in the Joomla 'state'

===== Frontend component note =====
I have followed and tested this approach and it's almost the exact same for the frontend component.<br/>
<span style="color:#555; font-size:smaller">Might want to change and redirect this article's title though (with maybe some changes?).</span><br/>
([[User:E-builds|E-builds]])

== Extend JFormFieldList (models / fields / fieldname.php) ==
Frequently your filter fields will be very basic; probably simply a dropdown list of one of the columns being displayed on the current page.  Regardless, you will need to create your own field element.  This really isn't a big deal - this file will probably be less than 70 lines, including comments.  The code below will generate the dropdown element to filter by companies.  For more information and complex examples on creating this class see [[Creating_a_custom_form_field_type]].

My 'companies' dropdown element:
<source lang="php">
<?php

defined('JPATH_BASE') or die;

jimport('joomla.html.html');
jimport('joomla.form.formfield');
jimport('joomla.form.helper');
JFormHelper::loadFieldClass('list');

/**
 * Custom Field class for the Joomla Framework.
 *
 * @package		Joomla.Administrator
 * @subpackage	        com_my
 * @since		1.6
 */
class JFormFieldMyCompany extends JFormFieldList
{
	/**
	 * The form field type.
	 *
	 * @var		string
	 * @since	1.6
	 */
	protected $type = 'MyCompany';

	/**
	 * Method to get the field options.
	 *
	 * @return	array	The field option objects.
	 * @since	1.6
	 */
	public function getOptions()
	{
		// Initialize variables.
		$options = array();

		$db	= JFactory::getDbo();
		$query	= $db->getQuery(true);

		$query->select('id As value, name As text');
		$query->from('#__my_companies AS a');
		$query->order('a.name');
		$query->where('state = 1');

		// Get the options.
		$db->setQuery($query);

		$options = $db->loadObjectList();

		// Check for a database error.
		if ($db->getErrorNum()) {
			JError::raiseWarning(500, $db->getErrorMsg());
		}

		return $options;
	}
}
</source>

Obviously, there is only one section here that needs to be customized: 

<source lang="php">
		$query->select('id As value, name As text');
		$query->from('#__my_companies AS a');
		$query->order('a.name');
		$query->where('state = 1');
</source>

Change the database name and adjust the sql as necessary.  This will produce the text and values for the select element options.  I highly recommend not changing the value and text names.  Although I did not test this theory, it seems likely that ancestor classes are expecting these names as keys in the resulting array.

== Modify Model (models / zzz.php) ==
In your model you have to include these two functions:
<source lang="php">
protected function getListQuery(){
		$db = JFactory::getDBO();
		$query = $db->getQuery(true);

                //CHANGE THIS QUERY AS YOU NEED...
                $query->select('id As value, name As text');
		$query->from('#__my_companies AS a');
		$query->order('a.name');
		$query->where('state = 1');

		
		// Filter
		$search = $this->getState('filter.search');
		if (!empty($search)) {
			$query->where('(a.name LIKE '.$search.')');
		}
		
		return $query;
	}
	
	/**
	 * Method to auto-populate the model state.
	 *
	 * Note. Calling getState in this method will result in recursion.
	 *
	 * @since	1.6
	 */
	protected function populateState($ordering = null, $direction = null)
	{
		// Initialise variables.
		$app = JFactory::getApplication('administrator');
	
		// Load the filter state.
		$search = $this->getUserStateFromRequest($this->context.'.filter.search', 'filter_search');
		$this->setState('filter.search', $search);
	
		$state = $this->getUserStateFromRequest($this->context.'.filter.state', 'filter_state', '', 'string');
		$this->setState('filter.state', $state);
	
		// List state information.
		parent::populateState('a.name', 'asc');
	}
</source>
=== Extra fields and inside words ===
Here is a small modification to search in multiple fields  in your database ánd to also search inside words.
<source lang="php">
// Filter
		$search = $this->getState('filter.search');
		if (!empty($search)) {
			$query->where('(a.name LIKE "%'.$search.'%" OR a.city LIKE "%'.$search.'%"));
		}
</source>

== Modify View (views / zzz / view.html.php) ==
In you view class, you have to set the state, like this:
<source lang="php>
                $this->items		= $this->get('Items');
		$this->pagination	= $this->get('Pagination');
                //Add the state...
		$this->state		= $this->get('State');
</source>

== Modify Template (views / zzz / tmpl / default.php) ==
In your template file, remember to include the html form to filter.
<source lang="php">
<div class="filter-search fltlft">
	<label class="filter-search-lbl" for="filter_search"><?php echo JText::_('JSEARCH_FILTER_LABEL'); ?></label>
	<input type="text" name="filter_search" id="filter_search" value="<?php echo $this->escape($this->state->get('filter.search')); ?>" title="<?php echo JText::_('COM_MYCOMPANY_SEARCH_IN_TITLE'); ?>" />
	<button type="submit"><?php echo JText::_('JSEARCH_FILTER_SUBMIT'); ?></button>
	<button type="button" onclick="document.id('filter_search').value='';this.form.submit();"><?php echo JText::_('JSEARCH_FILTER_CLEAR'); ?></button>
</div>
</source>

=== Extra: highlighting search terms ===
Here is some extra to visually mark the found search terms in the results page.<br/>
==== Template ====
<u>Add this somewhere at top somehwere:</u> <source lang="php">
$searchterms = $this->state->get('filter.search');

//Highlight search terms with js (if we did a search => more performant and otherwise crash)
if (strlen($searchterms)>1) JHtml::_('behavior.highlighter', explode(' ',$searchterms));
</source>
And further in your template, enclose the specific fields with the default highlighter finder.<br/>
<u>Example:</u><source lang="php">
<span id="highlighter-start"></span>
	<table class="adminlist">
	...
	</table>
<span id="highlighter-end"></span>
</source>
==== CSS ====
If your default admin template doesn't have required css, you should add the class in your component css.
<u>Example in controller:</u><source lang="php">
JHtml::stylesheet('com_peopleactions/admin.css', array(), true);
</source>
<u>In admin.css:</u><source lang="css">
.highlight {   background: none repeat scroll 0 0 #FFFF00; }
</source>

== Contributors ==
[[User:riledhel|Javier Constanzo]]

[[User:Doub1ejack|Doub1ejack]]

[[User:E-builds|E-builds]]

[[Category:Development]]
[[Category:Component Development]]
[[Category:Tutorials]]
[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]