Standard Template Properties
nav_first.pngFirst: thread:131
HTML Block
Edited: 11 Oct 2012 12:06 by: James Kanjo
Comments: 0
Tags:
nav_prev.pngPrevious: thread:120
ListPages Improvements
Edited: 19 Feb 2010 14:54 by: pieterh
Comments: 2
Tags:
Last: thread:112
Image Module
Edited: 12 Nov 2009 12:22 by: pieterh
Comments: 0
Tags:
nav_last.png
Next: thread:275
InfoBox button
Edited: 04 Feb 2010 07:50 by: leiger
Comments: 0
Tags:
nav_next.png

pieterhpieterh wrote on 08 Jan 2010 11:42

Standard template properties

This design sketch defines a single standardized syntax for all templating, using the concept of a tree of "objects" that you can access in various ways. This proposed design replaces the current templating code of ListPages, ListUsers, and live templates.

The general syntax for inserting a property is:

%%object.property|filter%%

Where the object. and |filter are optional and in some cases the .property is also optional.

Syntax rules

  • All object names and property names are case-insensitive. Writing %%Page.Name%% is identical to writing %%page.name%%.
  • Object and property names never contain spaces or periods or any other punctuation except hyphens and underscores.
  • Property names use the same syntax rules as data form field names (which can be used as property names in the Form object).

The Default object

All templating code has a default object. For live templates and ListPages this is the page object. For ListUsers this is the user object. For other modules still to be written this will be the same pattern, e.g. site object for ListSites, etc.

Thus you can write code like this:

[[module ListPages]]
* %%name%% - %%title_linked%%
[[/module]]

Which is equivalent to:

[[module ListPages]]
* %%page.name%% - %%page.title_linked%%
[[/module]]

Containing objects

All pages have containing objects that are available irrespective of whether you're in a module. These containing objects are: the current page, site, user, and system. You can explicitly refer to these by sticking ':' in front of the object name.

For example:

[[module ListPages]]
* %%page.name%% - %%page.title_linked%% (not the same as %%:page.name%%)
[[/module]]

Current user object

The current user object ('user' in _template, or ':user' in a module) is currently not accessible and will return null (empty) values for all properties.

Object hierarchy

Objects can contain other objects. For example, a page contains several user objects (creator, last editor, etc.). For each of these child objects you have the full set of properties for that object type. So we can do things like:

[[module ListPages]]
* %%name%% - %%title_linked%% (Created by %%created_by%%, who is %%created_by.status%% on this site)
[[/module]]

This is the object hierarchy:

  • Page (type = page)
    • Created_by (type = user)
    • Updated_by (type = user)
    • Commented_by (type = user)
    • Parent (type = page)
    • Form (type = form)
  • Site (type = site)
    • Owner (type = user)
  • User (type = user)
  • System (type = system)
  • Item (type = item)

Default properties

Each objects has a default property that you can access by using the object name alone. The default property is always a printable name. So, we can write code like this:

[[module ListPages]]
* Page name is %%page%%, the same as %%page.name%%, the same as %%name%%.
* Author of the page is %%created_by%%, the same as %%created_by.name%%.
[[/module]]

Using defaults can be a little confusing at first. But it does let you write more 'natural' code. It works because object names never overlap with properties, so any name you type is unambiguous.

Object properties

These are the properties for each object type:

Property Meaning
Page object type
name Page name without category (default property)
category Page category if any
fullname Page name with category if any
title Page title
title_linked Link to page showing title as text
link URL pointing to page
content Page content
content{n} Numbered content section
preview First 200 characters of the page
preview(n) First n characters of the page
summary Summary of content
first_paragraph The first paragraph of the page
tags Page visible tags (not starting with underscore)
tags_linked Page visible tags linked to system:page-tags/tag/{tag}
tags_linked|link_prefix Page visible tags linked to link_prefix{tag}
_tags Page hidden tags (starting with underscore)
_tags_linked Page hidden tags linked to system:page-tags/tag/{tag}
_tags_linked|link_prefix Page hidden tags linked to link_prefix{tag}
created_at Date page was created
created_by User who created page (as user object)
updated_at Date page was updated (edited, tagged, parented)
updated_by User who updated page (as user object)
commented_at Date of last comment
commented_by User who made last comment (as user object)
children Number of child pages
comments Number of comments on page
size Number of characters in page
rating Page rating value
revisions Number of revisions made to page
index Page index in ListPages output + offset (1 to total)
total Total number of pages in ListPages output (highest index%)
views Number of times page has been viewed
watchers Number of watchers on page
history Summary of last edits to page
hidden True if page is hidden (Boolean)
locked True if page is locked (Boolean)
url Current relative URL including all arguments
parent Page parent (as page object)
form Page form (as form object), if any
Form object type
<fieldname>.data Field value from page data form
<fieldname>.raw For select fields, the internal value, for pagepath fields, the category:pagename, and for other fields the field value
<fieldname>.label The label of the field as defined in the form
<fieldname>.hint The hint of the field as defined in the form
User object type
name User name encoded into a single string (default property)
number User id number
title User title including spaces
title_linked Link to user in form [[user name]]
link URL pointing to user profile page
status Returns anonymous, member, moderator, administrator or master-administrator
created_at Date user profile was created
edits Total number of pages created or update
edit_at Date of most recent page create or update
comments Total number of posted comments
comment_at Date of most recent comment
activity Total number of edits and comments
activity_at Date of most recent edit or comment
Site object type
title Title of current site
name Wikidot Unix name for site
domain Active domain name of current site
owner Site owner (as user object)
date Current date and time taking into account site timezone settings
System object type
date Current date and time in UTC
Item object type
parity "odd" or "even", used to generate CSS classes

Text field filters

A filter takes the string value of a property and does something with it, producing a new string. We allow these filters on text fields:

  • |upper - converts value to upper case
  • |lower - converts value to lower case
  • |title - converts value to title case (first letter of each word is capitalized)
  • |nnn - truncates value to nnn characters
  • |?value - if the value is empty, substitutes with 'value'
  • |??truevalue:falsevalue - if property is non-zero or true, show trueval, else show falseval. Applies to all numeric and Boolean properties.
  • |url - format value as valid URL (e.g. replacing spaces by %20).

Date field filters

Date fields have a specific filter that formats a date and produces a string value. Most tokens from PHP's strftime are accepted. You may find the howto contributed by community useful.

Filter chains

You can chain filters by appending them, e.g.

%%name|upper|10%%

Start a new sub-thread

Parsing order for field filters By scottplan 0 Comments 18 Apr 2010 13:34
Nested contexts / scopes By michal-frackowiak 1 Comments 05 Feb 2010 09:30
Why not in simple pages By Steven Heynderickx 4 Comments 11 Jan 2010 10:12

We discourage direct comments on this thread: to discuss it, please start a sub-thread.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License