Showing source for Property Substitutions

<b>Previous:</b> [[Defining Properties]]

The real power of properties comes in the ability to stick queries into pages. That is, pages don't have to be entirely static text: they can also have generated text, based on the properties on this page or others. There are two major types of queries. This page will cover Property Substitutions, and the next will cover Page Queries.

<h3>Property Substitutions</h3>

Property substitutions are queries that basically say, "insert the values of the specified properties in this text". They currently come in three major flavors: *variable substitution*, *property lists* and *property checks*.

<h3>Variable Substitution</h3>

Variable substitution is the simplest of all queries, and underlies all of them. It just says, "stick the value of a named property here". The syntax looks like this:

&#37;%propname&#37;%

So say that we have the following property definition:

{{ExamplePageAbstract=Describes the basic ways to put properties in pages.}}

Then this variable substitution:

&#37;%ExamplePageAbstract&#37;%

would render like this:

%%ExamplePageAbstract%%

This may seem like a minor feature -- after all, the value is right there on the page! But it will become far more useful when combined with more sophisticated queries, and with display templates.

<h3>PAGENAME</h3>

Each page has an implicit property called PAGENAME, which gives the actual name of the page. You don't define this explicitly -- it's always there. You can access it like any other property:

&#37;%PAGENAME&#37;%

Rendering that on this page produces:

%%PAGENAME%%

Note that PAGENAME references are always displayed as links -- if you click on the reference, it will take you to the specified page.

<h3>Property Lists</h3>

The first serious type of query is the property list. Its syntax looks like this:

&#123;* *propname* : *pattern* *}

Roughly speaking, this means "for each *propname* property on this page, substitute in the given *pattern*".

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

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

&#123;* ExampleItem : &#60;b&#62;&#37;%ExampleItem&#37;%&#60;/b&#62;&#60;br&#62; *}

When displayed, it looks like this:

{* ExampleItem : <b>%%ExampleItem%%</b><br>*}

Do you see what this is doing? The above query says, "For each ExampleItem, display it on a separate line, in bold".

That still 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:

&#123;* ExampleItem : &#60;b&#62;&#37;%ExampleItem.ItemName&#37;%&#60;/b&#62; (&#60;i&#62;&#37;%ExampleItem.PAGENAME&#37;%&#60;/i&#62;) -- &#37;%ExampleItem.ItemDescription&#37;%&#60;br&#62; *}

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:

{* ExampleItem : <b>%%ExampleItem.ItemName%%</b> (<i>%%ExampleItem.PAGENAME%%</i>) -- %%ExampleItem.ItemDescription%%<br> *}

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.

<h3>Property Checks</h3>

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:

&#123;+ExampleItem : &#60;h4&#62;Example Items&#60;/h4&#62;+}

renders like this:

{+ExampleItem : <h4>Example Items</h4>+}

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.

<b>Next:</b> [[Page Queries]]

ProWiki | RecentChanges | Preferences
Search: