Changes between Version 7 and Version 8 of S3/S3ResourceFilter

Timestamp:

01/31/12 13:48:08 (13 years ago)

Author:

Dominic König

Comment:

--

S3/S3ResourceFilter

@@ -85 +85 @@
 }}}
 
-The '''value''' can be a single value, a comma-separated list of values. NONE specifies a null-value (undefined, Python None). Values in quotes are treated as strings, i.e.
+The '''value''' can be a single value, a comma-separated list of values.
+
+Date-time-values must be specified as YYYY-MM-DDThh:mm:ss, dates as YYYY-MM-DD and times as hh:mm:ss. Other types use their standard Python notation. NONE specifies a null-value (undefined, Python None). Values in quotes are treated as strings, i.e.
 
 {{{
@@ -101 +103 @@
 It is currently not possible to escape quotation marks in order to enclose them in strings - thus strings must not contain quotation marks.
 
-For all operators except __belongs, any comma-separated lists of values are treated as alternatives (OR) ''unless'' the field contains a list as well. All operators except __like are case-sensitive.
+For all operators except !__belongs, any comma-separated lists of values are treated as alternatives (OR) ''unless'' the field contains a list as well. All operators except !__like are case-sensitive.
 
 == Extending filters at the back-end ==
 
+S3QueryField instances can also be generated at the back-end, simply by:
+
+{{{
+selector = S3QueryField(<field selector>)
+}}}
+
+Such selectors can then be used to create filter queries, using a syntax very similar to web2py queries:
+
+{{{
+afilter = S3QueryField("person.first_name") == "Dominic"
+bfilter = ~(S3QueryField("person.first_name").like("Dominic"))  # negation by ~ operator
+}}}
+
+The equivalent query operators are:
+
+||'''Python Operator'''||'''URL Operator'''||
+||{{{<}}}||!__lt||
+||{{{<=}}}||!__le||
+||{{{==}}}||!__eq||
+||{{{!=}}}||!__ne||
+||{{{>=}}}||!__ge||
+||{{{>}}}||!__gt||
+||{{{.like()}}}||!__like||
+||{{{.contains()}}}||!__contains||
+||{{{.belongs()}}}||!__belongs||
+
+These filter queries can also be joined together by {{{&}}} and {{{|}}} operators:
+
+{{{
+cfilter = (S3QueryField("person.first_name") == "Dominic") & (S3QueryField("contact.value") == "dominic@nursix.org")
+}}}
+
+Note: be diligent with brackets here ({{{&}}} and {{{|}}} operators take precedence).
+
+To add a filter to a resource is as simple as:
+
+{{{
+myfilter = S3QueryField("person.first_name") == "Dominic"
+resource.add_filter(myfilter)
+}}}
+
+Note that filters (S3ResourceQuery instances) are resource-agnostic, so they can be re-used across resources (provided the same field selector applies in all of them).
+
+Filters for fields which are not defined in a resource will be ignored quietly when retrieving records from the resource.