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