~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

WARNING

This card is no longer being maintained. 

 

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.

 

Searching by name

 

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.

 

Searching by ID

 

/* {"id": 21} */

 

 

Rename to search for ID

 

Searching in content

 

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

 

All cards of a given type

/* {"type": "User"} */

view (line) not supported for search by type

 

Searching by more than one thing

 

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

 

Users and roles

 

Users with a given role

 

/* {"member_of": "GC Staff"} */

 

view (line) not supported for users with GC Staff role

 

Roles a user is a member of

 

/* {"member": "Lewis Hoffman"} */

 

 

Cards edited by a user

 

/* {"edited_by": "John Abbe"} */

 

 

Users that have edited a card

 

/* {"edited": "Wiki on Wheels"} */

 

view (line) not supported for users editing Wiki on Wheels

 

Connections

 

Plus cards made by connecting to a given card

 

/* {"plus": "website"} */

 

Finds cards website is plussed to and which are plussed to website:

 

view (line) not supported for search by what connected to

 

Plus cards made by connecting to a card on the right or left

 

/* {"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)

 

Cards that are part of connections with particular specifications

 

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

 

Cards which a given card is part of

 

/* {"part": "website"} */

 

view (line) not supported for search by part

 

Plus cards which a given card is the right side of

 

/* {"right": "email"} */

 

view (line) not supported for search by right

 

Plus cards which a given card is the left side of

 

/* {"left": "Ethan McCutchen"} */

 

view (line) not supported for search by left

 

References

 

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.

 

Cards that link to or include a given card

 

/* {"refer_to": "Sandbox"} */

 

view (line) not supported for search by reference

 

Cards that a given card links to or includes

 

/* {"referred_to_by": "wql+example"} */

 

view (line) not supported for search by referrer

 

Cards with broken references???

 

/* {"refer_to": "_none"} */

 

view (line) not supported for search for broken references

 

Cards that link to a given card

 

/* {"link_to": "John Abbe"} */

 

view (line) not supported for search by links to

 

Cards that a given card links to

 

/* {"linked_to_by": "Ethan McCutchen+what I love"} */

 

view (line) not supported for search by linker

 

Cards with broken links???

 

/* {"link_to": "_none"} */

 

view (line) not supported for search for broken links

 

Cards that include a given card

 

/* {"include": "Bugs+inbox"} */

 

view (line) not supported for search by inclusion of

 

Cards that a given card includes

 

/* {"included_by": "Features"} */

 

view (line) not supported for search by includer

 

Cards with broken inclusions???

 

/* {"include": "_none"} */

 

view (line) not supported for search for broken inclusions

 

Searching in context

 

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.

 

Cards connected to this card

 

/* {"plus": "_self"} */

 

 

Cards this card links to or includes

 

/* {"referred_to_by": "_self"} */

 

 

Cards connected to the left side of this card

 

/* {"plus": "_left"} */

 

 

Cards connected to the right side of this card

 

/* {"plus": "_right"} */

 

 

Cards of this type connected to cards of another type

 

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

 

Sorting searches

 

You can sort search results by adding a sort clause (is "clause" right here?):

• "sort": "alpha" - sorts in alphabetical order
• "sort": "update" - sorts in order updated (most recent first); this is the default sort order
• "sort": "create" - sorts in order created (earliest created first)
• "sort": "plusses" (what's plusses?)

You can also reverse the sort order of any of these by adding "dir": "desc"

 

Sort by alphabetical

 

/* {"left": "John Abbe", "sort": "alpha"} */

 

 

Reverse sort order

 

/* {"type": "User", "sort": "alpha", "dir:", "desc"} */

 

 

Does it sort numbers by value?

 

Nope:

 

/* {"type:" "Number", "sort": "alpha"} */

 

view (line) not supported for search by numerical value

 

Sort by date last updated

 

/* {"left": "John Abbe", "sort": "update"} */

 

 

Sort by date created

 

/* {"left": "John Abbe", "sort": "create"} */

 

 

Sort by plusses

 

/* {"type": "User", "sort": "plusses"} */

 

 

Range and starting point of search results

 

You can limit the number of search results shown at once to a given number, and specify where in the results to start from

 

How many to show at a time

 

Show 7 at a time (default is 10)

 

/* {"type": "User", "sort": "name", "limit": 7} */

 

 

What to return

 

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.

 

Returning list?

 

/* {"type": "User", "return": "list"} */

 

 

Setting view in WQL

 

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