Tutorials » Basic Filtering

Ditto allows you to use the &filter parameter to REMOVE UNWANTED DOCUMENTS. That is, any document that meets the criteria of the filter will be REMOVED from the output.

A Filter Clause

A filter is a text string formatted according to the following rules.

The simplest filter is a single clause comprised of three terms separated by the local delimiter in the form:

field,criterion,mode Where:
  • "field" is the name of any MODx document field or TV.
  • "criterion" is a value of the same data type (number, string, date, etc.) as the field.
  • "mode" is a number from 1 to 8 that specifies what kind of comparison to make between the value of the field and the specified criterion.
  • "," (comma) is the "Local Filter Delimiter", i.e. the character that tells Ditto where the division is between the three parts of the clause.

There must be no spaces in the "criteria" term unless you want them used in the comparison.

Example

The filter clause

id,50,2

means "exclude any document whose id field equals 50."

Multiple Filter Clauses

A filter may include multiple clauses, separated by the global delimiter, in the form:

clause|clause|clause|etc. Where:
  • "clause" is any filter clause as defined above.
  • "|" (the pipe symbol) is the Global Filter Delimite, the character that tells Ditto where the division is between clauses.
  • "etc." means there is no fixed limit to the number of clauses you may include.

Multiple clauses have an "OR" relationship. I.e. a document will be excluded if it meets the criterion of any one clause (clause-1 OR clause-2 OR clause-3, etc.).

Example

The filter

id,50,2|id,52,2

means "exclude any document whose id field equals 50 or 52."

Comparison Modes

Mode
Exclude a document if its value in the specified field
1
 is not equal to the criterion (!=)
2
 is equal to the criterion (==)
3
 is less than the criterion (<)
4
 is greater than the criterion (>)
5
 is less than or equal to the criterion (<=)
6
 is greater than or equal to the criterion (>=)
7
 does not contain the text of the criterion
8
 does contain the text of the criterion

 

@EVAL

@EVAL in filters works the same as it does in MODx except it can only be used with basic filtering, not custom filtering (tagging, etc). Make sure that you return the value you wish Ditto to filter by and that the code is valid PHP.

Alternative Delimiters

Ditto provides parameters that let you specify alternative characters to use for both the global and local delimiters -- which will be necessary should you ever wish to use a comma or a pipe symbol as part of a "criterion" term.

Parameters

Parameter Description Value Type Legal Values Default Value
&filter Using this parameter you can tell Ditto to exclude from the output list any documents that meet certain criteria. text string

(see the filter construction rules above)

empty

 
&globalFilterDelimiter If you wish to use a different character than the default "|" to separate clauses in a filter string, then you may specify it with this parameter. a single character Any character not used in the filters the pipe symbol ( "|" )
&localFilterDelimiter If you wish to use a different character than the default "," to separate terms in a filter clause, then you may specify it with this parameter. a single character Any character not used in the filter itself comma
&where A custom MySQL WHERE statement. text string A valid MySQL WHERE statement using only document fields (no TVs) empty

Based on documentation work by Bill Fernandez