HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Tutorial: Filtering using ocFilter syntax

Written by Chris Graham, ocProducts
ocFilter 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_content block, and the if_in_group Comcode tag.


The syntax

An 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 '*'

Examples

It's easier than it sounds. Here are some examples…

Match either 1, 3, or 6 and higher.

Code

1,3,6+

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).

Code

*,!2,!4,!5

Match anything within the range 1 to 5, except 3.

Code

1-5,!3

Subtree matching

The 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':

Code

foo*

Match anything under a category (e.g. a gallery) named 'foo', but not 'foo' itself:

Code

foo*,!foo

Match anything  except anything under '3':

Code

*,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 precedence

A 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~").

Not

It 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.

Attempt 1

Code

{+START,IF,{$IS_IN_GROUP,!14}}...{+END}
This is incorrect, because we haven't defined any positive matches.

Attempt 2

Code

{+START,IF,{$IS_IN_GROUP,*,!14}}...{+END}
This is also incorrect, because it would match if a member happened to be in another group additionally to usergroup #14.

Attempt 3

Code

{+START,IF,{$NOT,{$IS_IN_GROUP,14}}}...{+END}
Finally, this is correct. It negates the ocFilter after it runs, via the Tempcode NOT symbol.

Finding IDs

You may wonder how to find IDs for use in filtering. The best way is to look at the 'edit' URL for the entries. They will contain something like '&id=5', where 5 would be the ID of that particular entry.

Concepts

ocFilter
ocPortal's syntax for concisely specifying things to choose, e.g. 1-4,7

See also