While most widgets will have the necessary args to match the items you wish to list, the filter arg may be able to cover any cases for which an arg does not already exist. This functionality will be difficult for basic users to grasp, but savvy users or admins may help provide assistance where needed using this feature.
The filter arg allows you to create custom content matching rules. For example, “match all events whose title contains the word ‘President’”.
The format for a filter arg is as follows:
<arg id=”filter” name=”FIELD” action=”TYPE”>VALUE</arg>
For “FIELD”, use the name of the database field this filter is being applied to.
For “TYPE”, choose the type of filter rule desired. This can be one of the following: equals, contains, matches, before, less_than, after, greater_than, not_equals, range, has.
For “VALUE”, choose the value the filter is comparing to the database field (if applicable).
For example, for the rule “match all events whose title contains the word ‘President’”, you would use:
<arg id=”filter” name=”title” action=”matches”>*President*</arg>
This would perform a wildcard match against the “title” field using the wildcard pattern “*President*”.
In terms of database queries, the available filter types have the following correspondences:
equals: FIELD = VALUE
matches: FIELD LIKE VALUE
before (for dates/times): FIELD < VALUE
less_than (for numbers): FIELD < VALUE
after: FIELD > VALUE
greater_than: FIELD > VALUE
not_equals: FIELD != VALUE
range (for dates/times or numbers): BETWEEN x AND y (format VALUE as: “x to y”)
has: FIELD IS NOT NULL (VALUE not considered)
If your widget contains multiple filter args, you may use the “filter_mode” arg exactly as you would use “tag_mode”. Set “filter_mode” to “all” to match all filters (default) or “any” to match any of the filters.
Note: Keep in mind that filters take effect regardless of whether or not a database field has an index available. We recommend using filters in conjunction with other args which will allow the widget query to take advantage of indexes in order to avoid slow queries.
The filter arg can be added to your widget in the widget editor.