joomla/joomla-cms — pull request #2035 by phproberto (2013-09-21 10:51:28+00:00)
Title: Stools

## Search tools for Joomla!

This adds to Joomla! a filter system like the uses in google images to filter them. The idea was born in the [JUX Code Sprint in Manchester](http://ux.joomla.org/jux-blog/73-jux-code-sprint-2013-invitation)

The main goal was to avoid the use of the left sidebar in item list managements to allow a full size item list. That will make available more space for columns and use the left side of the screen for the hot content instead of the filters. This PR only removes the sidebar filters but keeps the sidebar menu that is removed in a different JUX pull request. This is to ensure that all JUX contributions are fully independent.

Closed:
![stools_closed](https://f.cloud.github.com/assets/1119272/1185481/1e2cde92-22ab-11e3-9ea6-95be488425f2.png)

Open:
![stools_open](https://f.cloud.github.com/assets/1119272/1185480/0df30d4e-22ab-11e3-828d-8f6a7fcdc15a.png)

## Main features

* The system adds to Joomla! the option to use standard `JForm` forms for item list filtering. That saves us to deal with states & to hardcode selects in HTML.
* It uses `JLayout` so all the system can be easily moved, customised and/or reused.
* It uses standard `JForm` fields so adding and remove filters is as easy as copy 6-10 lines of code in an XML file.
* Filters and list modifiers are received and added automatically so the system is 100% reusable for extension development. In fact 3rd part developers that want to use the system mainly have to remove code.

## Joomla! improvements / fixes
* Adds the option to filter by tag to featured articles.
* Adds the option to filter by `purchase_type` to banner clients. Also adds the missing ordering for some column headings:
![clients](https://f.cloud.github.com/assets/1119272/1185342/8df016b2-229d-11e3-9acc-80f1db717e1c.png)

## New field types available

### JFormFieldPredefinedList
New abstract class to create a select field with a predefined list of values. Fields that extend it basically have to add a list of values like:

```PHP
/**
* Available options
*
* @var array
* @since 3.2
*/
protected $predefinedOptions = array(
'today' => 'COM_USERS_OPTION_RANGE_TODAY',
'past_week' => 'COM_USERS_OPTION_RANGE_PAST_WEEK',
'past_1month' => 'COM_USERS_OPTION_RANGE_PAST_1MONTH',
'past_3month' => 'COM_USERS_OPTION_RANGE_PAST_3MONTH',
'past_6month' => 'COM_USERS_OPTION_RANGE_PAST_6MONTH',
'past_year' => 'COM_USERS_OPTION_RANGE_PAST_YEAR',
'post_year' => 'COM_USERS_OPTION_RANGE_POST_YEAR',
);
```
The field also supports to filter a specific list of the available values adding to the field definition the attribute `filter`. Sample field definition only selecting some of the previous values:

```XML

COM_USERS_OPTION_FILTER_DATE

```
### JFormFieldStatus

Shows a list of content status. Values possible are:

```PHP
/**
* Available statuses
*
* @var array
* @since 3.2
*/
protected $predefinedOptions = array(
'-2' =>	'JTRASHED',
'0' => 'JUNPUBLISHED',
'1' => 'JPUBLISHED',
'2' => 'JARCHIVED',
'*' => 'JALL'
);
```
### JFormFieldUserActive
Shows a list of user account statuses. Values possible:

```PHP
/**
* Available statuses
*
* @var array
* @since 3.2
*/
protected $predefinedOptions = array(
'0' => 'COM_USERS_ACTIVATED',
'1' => 'COM_USERS_UNACTIVATED'
);
```
### JFormFieldUserGroupList

Shows a nested list of user groups available. Sample use:
![usergrouplist](https://f.cloud.github.com/assets/1119272/1185391/f3f9a888-22a2-11e3-9eec-606b3b534879.png)

### JFormFieldLimitbox

Shows a limit box for pagination. It's like the one generated by `JPagination::getLimitBox` method but reusable & customisable outside.

The default use is:

```XML

```
The default values are:

```PHP
/**
* Default options
*
* @var array
*/
protected $defaultLimits = array(5, 10, 15, 20, 25, 30, 50, 100);
```

It supports attributes to modify the list of limits used without creating a new field:
* `limits` : Manually specify the limits shown. Sample:
![limitbox_limits](https://f.cloud.github.com/assets/1119272/1185402/39893732-22a4-11e3-9a70-9c3baa2aa9a6.png)
* `append`: Append extra values to the default list. Sample:
![limitbox_append](https://f.cloud.github.com/assets/1119272/1185418/d96b31a6-22a4-11e3-9c3b-baadf73d98ab.png)
* `remove`: Removes values of the default list. Sample:
![limitbox_remove](https://f.cloud.github.com/assets/1119272/1185419/0a48e282-22a5-11e3-9c92-1f4497171b1c.png)

### JFormFieldRegistrationDateRange
Show a list of registration date ranges. Values possible:

```PHP
/**
* Available options
*
* @var array
* @since 3.2
*/
protected $predefinedOptions = array(
'today' => 'COM_USERS_OPTION_RANGE_TODAY',
'past_week' => 'COM_USERS_OPTION_RANGE_PAST_WEEK',
'past_1month' => 'COM_USERS_OPTION_RANGE_PAST_1MONTH',
'past_3month' => 'COM_USERS_OPTION_RANGE_PAST_3MONTH',
'past_6month' => 'COM_USERS_OPTION_RANGE_PAST_6MONTH',
'past_year' => 'COM_USERS_OPTION_RANGE_PAST_YEAR',
'post_year' => 'COM_USERS_OPTION_RANGE_POST_YEAR',
);
```

## Status
Search tools can be implemented in a lot of places. This is the list of the done/possible managements where it can be/has been implemented:
- [x] Articles
- [x] Banner list
- [x] Banner client list
- [ ] Banner track list
- [x] Categories
- [ ] Contacts
- [ ] Content language manager
- [x] Featured articles
- [ ] Feeds
- [ ] Installer: Discover install
- [ ] Installer: Extension manager
- [ ] Installer: Update
- [x] Menu items
- [ ] Module manager
- [ ] Plugin manager
- [ ] Tags
- [ ] Template manager
- [x] User list
- [ ] User notes
- [ ] Web links

## Future enhacements

The search tools system is in its first stage that means that "it works". In the future we hope:
* Allow to reload items with AJAX using layouts for rows & allowing to add a refresh URL.
* Allow to save custom filters by the user
* Allow to save item count limit to remember the user preferences for each management.
* Convert the select boxes into a more `Google` style list.
* Allow to customise the filters at the template level allowing a fully site customisation (actually it can be done with layouts but it's not the best way to add/change fields).

## Credits
Search tools was possible thanks to:
* Angie Radtke
* Beat
* Brian Teeman
* Peter Van Westen
* Roberto Segura
* Seth Warburton

It was possible also thanks to the great Code Sprints concept created by the [Joomla! PLT team](http://www.joomla.org/about-joomla/the-project/leadership-team.html) & sponsored by [Open Source Matters](http://www.opensourcematters.org/).