S3 FilterForms

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

URL Queries

• see 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

---

• S3 API Guide
• DeveloperGuidelines