Most things at the top level of the plan - META:TOPICPARENT, META:TOPICINFO etc - are structures which are indexed by keys. For example, META:TOPICINFO has 4 entries, which are indexed by the keys author, date, format and version. META:FILEATTACHMENT, META:FIELD and META:PREFERENCE are all arrays, which means they can have any number of records under them. Arrays are indexed by numbers - for example, the first entry in the META:FIELD array is entry 0.

>>

Most things at the top level of the plan - META:TOPICPARENT, META:TOPICINFO etc - are structures which are indexed by keys. For example, META:TOPICINFO has 4 entries, which are indexed by the keys author, date, format and version. META:FILEATTACHMENT, META:FIELD and META:PREFERENCE are all arrays, which means they can have any number of records under them. Arrays are indexed by numbers - for example, the first entry in the META:FIELD array is entry 0. The field specifier arraysize returns the number of items in an array, for example, attachments.arraysize returns the number of attachments.

It's a bit clumsy having to type META:FILEATTACHMENT every time you want to refer to the array of attachments in a topic, so there are some predefined aliases that make it a bit less typing:

where X is an array and N is an integer number >= 0, gets the Nth element of the array X

attachments[3]

X/Y

accesses Y from the topic specified by the value of X. X must evaluate to a topic name

parent.name/(form.name='ExampleForm') will evaluate to true if (1) the topic has a parent, (2) the parent topic has the main form type ExampleForm.

Line: 86 to 90

If X would conflict with the name of an entry or alias (e.g. it's moved or maybe parent), you can prepend the name of the form followed by a dot, as shown in the last example.

Constants

Changed:

<<

You use constants for the values that you compare with fields. Constants are either strings, or numbers. Strings are always delimited by single-quotes (you can escape a quote using backslash). Numbers can be any integer or floating point number.

>>

You use constants for the values that you compare with fields. Constants are either strings, or numbers. Strings are always delimited by single-quotes (you can escape a quote using backslash). Numbers can be any integer or floating point number. Constants can be supplied by TWikiVariables, such as '%TOPIC%' representing the current topic name.

Operators

Line: 115 to 121

A query matches if the query returns one or more values when it is applied to the topic. So if I have a very simple query, such as "attachments", then this will return TRUE for all topics that have one or more attachments. If I write "attachments[size>1024 AND name ~ '*.gif']" then it will return TRUE for all topics that have at least one attachment larger than 1024 bytes with a name ending in .gif.

Gotcha

Changed:

<<

Remember that in the query language, TWiki topic names are constants. You cannot write Main.UserTopic/UserForm.firstName because Main.UserTopic will be interpreted as a form field name. If you want to refer to topics you must enclose the topic name in quotes i.e. 'Main.UserTopic'/UserForm.firstName

>>

Remember that in the query language, TWiki topic names are constants. You cannot write Main.JohnSmith/UserForm.FirstName because Main.JohnSmith will be interpreted as a form field name. If you want to refer to topics you must enclose the topic name in single quotes i.e. 'Main.JohnSmith'/UserForm.FirstName

Examples

Line: 120 to 127

Examples

Query examples

Added:

>>

attachments[name='purdey.gif'] - true if there is an attachment call purdey.gif on the topic

Changed:

<<

(fields[name='Firstname'].value='Emma' OR fields[name=Firstname].value='John') AND fields[name='Lastname'].value='Peel' - true for 'Emma Peel' and 'John Peel' but not 'Robert Peel' or 'Emma Thompson'

>>

attachments[name~'*.gif'].arraysize > 3 - true if there are at least 4 .gif files attached to the topic

(fields[name='Firstname'].value='Emma' OR fields[name='Firstname'].value='John') AND fields[name='Lastname'].value='Peel' - true for 'Emma Peel' and 'John Peel' but not 'Robert Peel' or 'Emma Thompson'

(Firstname='Emma' OR Firstname='John') AND Lastname='Peel' - shortcut form of the previous query

HistoryForm[name='Age'].value>2 - true if the topic has a HistoryForm, and the form has a field called Age with a value > 2

HistoryForm.Age > 2 - shortcut for the previous query

preferences[name='FaveColour' AND value='Tangerine'] - true if the topic has the given preference setting and value

Changed:

<<

Person/(ClothesForm[name='Headgear'].value ~ '*Bowler*' AND attachments[name~'*hat.gif' AND date < d2n('2007-01-01')]) - true if the form attached to the topic has a field called Person that has a value that is the name of a topic, and that topic contains the form ClothesForm, with a field called Headgear, and the value of that field contains the string 'Bowler', and the topic also has at least one attachment that has a name matching *hat.gif and a date before 1st Jan 2007. (Phew!)

>>

Person/(ClothesForm[name='Headgear'].value ~ '*Bowler*' AND attachments[name~'*hat.gif' AND date < d2n('2007-01-01')]) - true if the form attached to the topic has a field called Person that has a value that is the name of a topic, and that topic contains the form ClothesForm, with a field called Headgear, and the value of that field contains the string 'Bowler', and the topic also has at least one attachment that has a name matching *hat.gif and a date before 1st Jan 2007. (Phew!)