= S3 FilterForms =
[[TOC]]

Filter forms allow the user to apply filters to interactive views (e.g. data tables, data lists, reports etc.).

== Framework ==

The framework for filter forms consists of 4 core elements:

'''Client-side:'''
  - '''filter widgets''' to facilitate user input of filter criteria
  - a '''filter script''' to collect all values from filter widgets and convert them into a URL query

'''Server-side:'''
  - the '''REST interface''' to interpret and apply the URL query as resource filter
  - a '''filter form builder''' to render the filter widgets and populate them with the values from the URL query

[[Image(filterforms.png)]]

== URL Queries ==

  * see [wiki:S3XRC/RESTfulAPI/URLFormat#BasicQueryFormat Query Format]

== Filter Widgets ==

  * ''tbw''

== Filter Forms ==

=== Configuration of Filter Forms in S3CRUD ===

S3CRUD has filter forms integrated in the /datatable and /datalist pages (these methods are temporary until replaced by a new resource view page).

For these pages, the filter widgets are configured per resource with the "filter_widgets"-setting like:

{{{
s3db.configure(tablename,
               filter_widgets=[
                 S3TextFilter(["name", "email", "comments"],
                              label=T("Search"),
                              comment=T("Search for office by text.")),
                 S3OptionsFilter("organisation_id",
                                 label=messages.ORGANISATION,
                                 comment=T("Search for office by organization."),
                                 represent="%(name)s",
                                 widget="multiselect"),
                 S3OptionsFilter("location_id$L1",
                                 location_level="L1",
                                 widget="multiselect")
               ])
}}}

The widgets appear in the form in list order.

Additionally, there are a number of controller options for the s3_rest_controller call:

{{{
output = s3_rest_controller(prefix, resourcename,
                            filter_submit_url = submit_url,
                            filter_ajax_url = ajax_url,
                            filter_formstyle = formstyle,
                            filter_submit = submit
                           )
}}}

||'''Option'''||'''Type'''||'''Function'''||'''Default'''||
||filter_submit_url||URL string||where to request filtered data from||URL of the current call||
||filter_ajax_url||URL string||where to request updated filter options from||URL of the current call with /filter method||
||filter_formstyle||Formstyle function||Alternative formstyle for the filter form||built-in formstyle||
||filter_submit||String||Label for the submit button or tupel of (label, class) to also specify a CSS class for the button||T("Search")||
== Development ==

=== Components ===

  * ''tbw''

=== Python Classes ===

  * ''tbw''

=== !JavaScript Methods ===

  * ''tbw''

=== Implementing Filter Widgets ===

  * ''tbw''

=== Using Filter Forms in REST Method Handlers ===

  * ''tbw''

=== Using Filter Forms in Custom Controllers ===

  * ''tbw''

----
- [wiki:S3 S3 API Guide]
- DeveloperGuidelines