ProWiki: Page Queries

Previous: Property Queries

First, let's look at the Page Query. This is a simple syntax that lets you show all of the pages matching some given criteria.

Page Query Syntax

All page queries look more or less like this:

{?query : pattern?}

In this, the query part describes the criteria you're looking for, and the pattern says what to print for each page that matches those criteria.

Simple Page Queries

A simple page query just gives the page names and values for each page that includes that property; if you give a property name as the query and omit the pattern, this is what happens. For example, in the previous page, I showed that IndexName pointed to a special page listing all pages that had the IndexName property. What I didn't mention there was that there is actually nothing very special about that page -- it's simply a small page containing a query! That query looks like this:

{?IndexName?}

And when it is displayed, it shows up like this:

You can describe this query as, "For each page that contains the IndexName property, display the IndexName and IndexAbstract? properties on that page, formatted like this". When you display that query, it comes out like this:

Defining New Properties -- This page describes how you can define arbitrary properties on a page.

As you can see, you refer to a property using the syntax . Again, yes, I made it up. Live with it. (Or reimplement using a syntax that suits you better.)

PAGENAME

Each page has an implicit property called PAGENAME. You don't define this explicitly -- it's always there. Notice that the IndexName for the previous page doesn't quite match the actual name of the page. If we wanted to include the real name, we could tweak our query to look like this:

When displayed, this comes out as:

Note that PAGENAME references are always displayed as links.

In-Page Property Lists

The second major type of query is the in-page property list. Whereas a page query says, "for all pages that have this property", a property list says, "apply the following pattern for all properties of this type on this page".

For example, let's give this page several ExampleItem properties:

ExampleItem = A big black book

ExampleItem = Deck of cards

ExampleItem = Some pocket lint

We can now add a query that goes through all of these properties and lists them:

Note the "*" at the start of the query -- that indicates that a property list is desired. When displayed, it looks like this:

That isn't very interesting, is it? But we can make it a heck of a lot more interesting if those items are references to pages themselves, with their own properties. Say that each ExampleItem is actually the name of a page, and that each of those pages has an ItemName? and ItemDescription? property. Now we can do this:

That is, "For each ExampleItem on this page, take the value as a page name, and show the ItemName?, PAGENAME and ItemDescription? properties on that page". That shows up like this:

Neat, huh? I left the Pocket Lint undefined, so that you can see what happens if you use this syntax to refer to a page that isn't there.

In-Page Singleton Property Queries

You can also do queries aimed at single values rather than multiple ones. If you substitute a "+" for the "*" in the query, it will only fetch one value. The particular power of this alternative is that it will walk up the inheritance tree: if the property is defined by an ancestor of this page, the value will be taken from that ancestor. This can be useful if you want a default value.

This variant is also useful as essentially an "if" statement. For example, this line:

renders like this:

{{?+ExampleItem :

ExampleItems?

}}

because there are ExampleItems? on this page. But if there's weren't any, the line would be omitted entirely. This is often useful for headers to lists.

Leaf Queries

Rather different from the above are Leaf Queries. This are specifically aimed at the prototype-oriented inherited nature of ProWiki. They allow you to fetch all of the leaves descending from a particular page -- that is, all of the descendants that do not themselves have children.

The syntax of a leaf query looks like this:

So this says, "for each leaf page that inherits from ParentPage?, show the Name, PAGENAME and Description". Again, this is strictly practical -- it is often useful to get a listing of such leaves, without any intervening parent nodes in the inheritance tree. (A version of this that includes those parent nodes would be easy enough to add, but I haven't needed it yet.)

Next: Display Templates