Composr Tutorial: Filtering using Selectcode syntax

Written by Chris Graham
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.

Table of contents

  1. Composr Tutorial: Filtering using Selectcode syntax
    1. The syntax
    2. Examples
      1. Full example
    3. Subtree matching
    4. Numeric or not?
    5. Trees or not?
    6. Categories or entries?
    7. Blank filters, and precedence
      1. Not
        1. Attempt 1
        2. Attempt 2
        3. Attempt 3
    8. Finding IDs
    9. See also

The syntax

Selectcode 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 (*)
  • categories:
    • 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>)

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

Full example

Let's take the first example above and show it in-context for filtering display text.

Here's some Comcode:

Code

[if_in_group="1,3,6+"]Sample text[/if_in_group]

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:

Code

{+START,IF,{$IS_IN_GROUP,1,3,6+}}Sample text{+END}

Subtree matching

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

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~

Match anything directly under '3':

Code

3>

Match anything in category '3':

Code

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 precedence

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

Not

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

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


See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.