ocPortal Tutorial: Filtering using ocFilter syntax
Written by Chris Graham, ocProductsocFilter is a special ocPortal syntax (language) for writing filter lists. In other words, it is a way of writing down what you would like to be matched.
Various areas of ocPortal support the ocFilter syntax, including the main_multi_content block, and the if_in_group Comcode tag.
Table of contents
The syntaxAn ocFilter is a comma-separated list of match-specifier tokens, where a match-specifier may be:
- an acceptable-literal (e.g. '1').
- an avoiding-literal (e.g. '!1')
- a bounded acceptable-range (e.g. '1-3')
- a non-bounded acceptable-range (e.g. '3+')
- an acceptable subtree (e.g. '3*')
- an avoiding subtree (e.g. '3~')
- all-acceptable '*'
ExamplesIt's easier than it sounds. Here are some examples…
Match either 1, 3, or 6 and higher.
Match anything except 2, 4, and 5 (which turns out the same as the above example, assuming we are working only with numeric IDs and 1 is the lowest ID).
Match anything within the range 1 to 5, except 3.
Subtree matchingThe above examples all work with numeric IDs, and work on lists. In applicable contexts ocFilter can also be used to write tree structure matches. Here are some examples…
Match anything under a gallery named 'foo':
Match anything under a category (e.g. a gallery) named 'foo', but not 'foo' itself:
Match anything except anything under '3':
Numeric or not?ocFilter does not care whether it is matching against numeric or string IDs. However, of course if you are writing a filter and applying it to something, the choice will be made for you. For example, the gallery system uses string IDs for categories, and the download system uses numeric IDs for categories.
The only caveat is for string ID systems you obviously can't use number range specifiers.
Trees or not?Obviously you can only use the tree match specifiers if you are applying the filter for something that supports tree structures.
Categories or entries?ocFilter is not written specifically to be for matching against category IDs or entry IDs, it again depends what the filter is applied to.
However, if you are using tree match specifiers then these will be written against categories even if you are matching against entries. For example, if you are writing a filter to match against download entries, and you use tree match specifiers, the tree match specifiers would be referring to download categories, whilst the other specifiers would be referring to download entries.
Blank filters, and precedenceA blank filter will match nothing. If you want to match everything you must write a filter as "*".
ocFilter precedence is not based on order, it is based on the rule "pick out what is accepted then remove what is avoided". In other words, the filter first works out what IDs pass (e.g. "*" or "5" or "1-30" or "bar*") and then removes and IDs that have been explicitly marked as 'avoid' (e.g. "!3" or "foo~").
NotIt is important to understand that "!" does not really mean 'not', it means 'avoid' or 'except'. There is no way to use ocFilter to match on a negative, you can only limit what positive matches are accepted.
Let's say we want to match anyone not in usergroup #14 using the Tempcode IS_IN_GROUP symbol, which happens to work via ocFilter.