Changes between Version 38 and Version 39 of S3/FilterForms

Timestamp:

04/02/13 09:27:55 (12 years ago)

Author:

Dominic König

Comment:

--

S3/FilterForms

@@ -215 +215 @@
 === Using Filter Forms in REST Method Handlers ===
 
-  * ''tbw''
+Filter forms can be rendered by any method handler. Since filter forms will never be submitted, the method handler does not need to handle any subsequent POSTs related to the filter form, but just insert the filter form HTML to the page.
+
+'''A filter form can be generated using the S3FilterForm class''':
+
+{{{#!python
+from s3filter import S3FilterForm
+filter_form = S3FilterForm(widgets, **attr)
+}}}
+
+'''Parameters''':
+  ||'''Parameter'''||'''Type'''||'''Explanation'''||
+  ||widgets||list of S3FilterWidget instances||the widgets for the filter form ''(required)''||
+  ||attr|| ||Options and HTML attributes for the filter form||
+
+'''Options and HTML attributes''':
+  ||'''Parameter'''||'''Type'''||'''Explanation'''||'''Default'''||
+  ||formstyle||function||a function to render a widget row, must accept {{{(row_id, label, widget, comment)}}} as parameter list||S3FilterForm._formstyle()||
+  ||submit||boolean or the button label as string/lazyT or a tuple (label, HTML class)||whether to render a submit button in the filter form and how, with {{{False}}} or {{{None}}} no submit button will be rendered||False (if True, then the label defaults to T("Search"))||
+  ||ajax||boolean||whether to Ajax-update the target object (True, also requires the target to be specified in the html() call) or re-load the page (False)||False||
+  ||url||string||where to load the filtered data from||URL of the request||
+  ||ajaxurl||string||where to load option updates for filter widgets from||URL of the request + /filter.json method||
+  ||_class||string||the CSS class for the filter form ''(HTML attribute)''||"filter-form"||
+  ||_id||string||the HTML element ID for the filter form ''(HTML attribute)''||None||
+
+'''The filter form can then be rendered using its .html() method''':
+
+{{{#!python
+html_output = filter_form.html(resource, get_vars, target=None, alias=None)
+}}}
+
+'''Parameters''':
+  ||'''Parameter'''||'''Type'''||'''Explanation'''||
+  ||resource||S3Resource||The resource to render the filter form for. Important: do not just use the {{{r.resource}}} instance here (because it's coming with pre-filtered options), instead create a new instance using {{{s3db.resource(r.resource.tablename)}}} ''(required)''|| - ||
+  ||get_vars||dict||the GET vars (=URL query vars) to populate the filter widgets from ''(required)''|| - ||
+  ||target||string||the HTML element ID of the target object (e.g. a datalist or datatable) ''(required if the form is set to ajax=True)''||None||
+  ||alias||string||the table alias to use in URL queries ''(required if the filtered resource is not the master resource of the request URL, e.g. a component)''||None||
 
 === Using Filter Forms in Custom Controllers ===