Composr Tutorial: Filtering using Selectcode syntax
Written by Chris Graham (ocProducts)Selectcode is a special Composr syntax (language) for writing down what you would like to be matched. Sometimes we have requirements that a page should "only show this" or should "only show except this" – Selectcode makes that possible.
Various areas of Composr support the Selectcode syntax, including the main_multi_content block, and the if_in_group Comcode tag. The blocks and Comcode tags supporting Selectcode usually explicitly say so within the assistants to add them.
Selectcode is not to be confused with Filtercode, which is the language for determining what results to return via property querying.
The syntaxSelectcode is a comma-separated list of match-specifier tokens, where a match-specifier may be:
- entries (or categories if filter directly applied to categories):
- 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+)
- all-acceptable (*)
- an acceptable category (e.g. 3#)
- an acceptable subtree (e.g. 3*)
- an avoiding subtree (e.g. 3~)
- an acceptable set of direct descendents (e.g. 3>)
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.
Full exampleLet's take the first example above and show it in-context for filtering display text.
Here's some Comcode:
In this example, the "Sample text" will only show to members in a usergroup matching the given Selectcode.
We can do the same using Tempcode:
Here's some Comcode:
Subtree matchingThe above examples all work with numeric IDs, and work on lists. In applicable contexts Selectcode 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':
Match anything directly under '3':
Match anything in category '3':
Numeric or not?Selectcode 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?Selectcode 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 or # 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, while 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 "*".
Selectcode 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 Selectcode 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 Selectcode.
Finding IDsYou 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.
- The form field filter system
- Comcode and the attachment system
- Advanced Comcode
- Using blocks
- Filtering using Filtercode syntax
Please rate this tutorial:
Have a suggestion? Report an issue on the tracker.