~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The most current WQL documentation is at CQL Syntax.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here are some examples of wql at work. Each shows the wql for a search, then includes a Search card actually implementing that wql. Note that these cards are all included in line view:
/* { {cardname|view:line} } */
...but they could just as easily be done without the "|view:line", which would then include them without the surrounding card interface.
The card named "Lewis Hoffman":
/* {"name": "Lewis Hoffman"} */
view (line) not supported for search for exact name
All the cards with "Matt" in the name (note that it only finds entire words, for example it doesn't find MattisManzel):
/* {"name": ["match", "Matt"] } */
view (line) not supported for search within name
Bug filed.
/* {"id": 21} */
Rename to search for ID
Cards with content of exactly 30:
/* {"content": 30} */
view (line) not supported for search for exact content
All the cards which mention Hooze:
/* {"content": ["match", "Matt"] } */
/* {"match": "Hooze" } */
view (line) not supported for search within content shorthand
Cards with content greater than 5:
/* {"content": [">", 5] } */
view (line) not supported for search for relative value
Another test:
/* {"type": "Number", "content": [">", 5] } */
view (line) not supported for search for Numbers of relative value
Could the 5 be replaced with the value of another card? Feature idea if not...
/* {"type": "User"} */
view (line) not supported for search by type
My non-working stab at translating from
/* :type => [:in, 'Person', :Company] */
to:
/* {"type": [ "in", "Person", "Company"] } */
view (line) not supported for search test
But this way works:
/* {"or": {"type": "Number", "right": "favorite fruit"} } */
view (line) not supported for search by more than one thing
But if you use the same parameter more than once it only gets the last one.
/* {"or": {"right": "e-mail", "right": "website"} } */
view (line) not supported for search twice by same parameter
/* {"member_of": "GC Staff"} */
view (line) not supported for users with GC Staff role
/* {"member": "Lewis Hoffman"} */
/* {"edited_by": "John Abbe"} */
/* {"edited": "Wiki on Wheels"} */
view (line) not supported for users editing Wiki on Wheels
/* {"plus": "website"} */
Finds cards website is plussed to and which are plussed to website:
view (line) not supported for search by what connected to
/* {"right_plus": "email"} */
Only finds cards plussed to email (put actual search here)
/* {"left_plus": "email"} */
Only finds cards that email is plussed to (put actual search here)
For example, cards that are plussed to tag in which that plus card refers to wql:
/* {"plus": ["taglist", {"refer_to": "wql"} ] } */
view (line) not supported for search by connection with given value
/* {"part": "website"} */
view (line) not supported for search by part
/* {"right": "email"} */
view (line) not supported for search by right
/* {"left": "Ethan McCutchen"} */
view (line) not supported for search by left
Cards can link to and include other cards. We use the word reference to encompass both of these, so refer_to combines link_to and include, and referred_to_by combines linked_to_by and referred_to_by.
/* {"refer_to": "Sandbox"} */
view (line) not supported for search by reference
/* {"referred_to_by": "wql+example"} */
view (line) not supported for search by referrer
/* {"refer_to": "_none"} */
view (line) not supported for search for broken references
/* {"link_to": "John Abbe"} */
view (line) not supported for search by links to
/* {"linked_to_by": "Ethan McCutchen+what I love"} */
view (line) not supported for search by linker
/* {"link_to": "_none"} */
view (line) not supported for search for broken links
/* {"include": "Bugs+inbox"} */
view (line) not supported for search by inclusion of
/* {"included_by": "Features"} */
view (line) not supported for search by includer
/* {"include": "_none"} */
view (line) not supported for search for broken inclusions
In a search card that is a connection card (which is quite often the case), there are several terms you can use to refer to all of, or parts of, the left side of the connection. These are often used in Virtual cards.
"_self" will be replaced with the name of the left side of connection card.
If the left side of the connection card is itself a connection card:
"_left" will be replaced with the name of the left side of it.
"_right" will be replaced with the name of the right side of it.
/* {"plus": "_self"} */
/* {"referred_to_by": "_self"} */
/* {"plus": "_left"} */
/* {"plus": "_right"} */
If you want any card of a certain cardtype to automatically display all the cards of another cardtype to which it is connected
e.g. you want all user cards to display all of the company cards to which they are connected
/* {"plus": "_self", "type": "company"} */
you must add the query to search card+*template, and then add the search card to user+*template
You can sort search results by adding a sort clause (is "clause" right here?):
You can also reverse the sort order of any of these by adding "dir": "desc"
/* {"left": "John Abbe", "sort": "alpha"} */
/* {"type": "User", "sort": "alpha", "dir:", "desc"} */
Nope:
/* {"type:" "Number", "sort": "alpha"} */
view (line) not supported for search by numerical value
/* {"left": "John Abbe", "sort": "update"} */
/* {"left": "John Abbe", "sort": "create"} */
/* {"type": "User", "sort": "plusses"} */
You can limit the number of search results shown at once to a given number, and specify where in the results to start from
Show 7 at a time (default is 10)
/* {"type": "User", "sort": "name", "limit": 7} */
By default, Wagn returns a list of closed cards. You can also have it return the cards open, or just links to them, or just their name. You can even have it return a simple count of how many cards it found.
/* {"type": "User", "return": "list"} */
You can set the default view of the cards that a search will return right in the WQL, choosing among the same views available for item: in nesting. Here's an example with Users listed as links:
/* {"type": "User", "view": "link"} */
=================
Working through WQL+Design+braindump