ConditionalMarkup
The directive allows portions of a page to be included or excluded from rendering.
Using the (:if:) Directive
The generic forms of the directive are
body body body body body body body body |
where "cond" names a condition to be tested, and "param" is a parameter or other argument to the condition.
Note that without parameters and
are identical. Also note that
automatically closes a previous conditional. For nested multiple levels, see Nested conditionals.
Built-in Conditions
The built-in conditions include:
| - | current page is named "PAGENAME " or "GROUPNAME.PAGENAME "
|
| - | current group is named "GROUPNAME "
|
| - | viewer is authorized - meaning "what they are allowed to do" - matches a "LEVEL " where LEVEL can be: read , edit , upload , attr or admin ; PAGENAME is optional.
This is mostly used to hide and show portions of the interface only useful to editors or admins.
|
| - | current viewer is authenticated - meaning they have proven who they are via login - to use this the wiki must include recipe AuthUser or others which set the $AuthId variable.
|
| - | username and password not authenticated. To use this the wiki must include recipe Cookbook:AuthUser. |
| - | always include text, case sensitive |
| - | always exclude text (same as a comment, but Page Text Variables ARE set), case sensitive |
| - | PAGENAME has one or more attachments among the specified. A pagename can be omitted, in that case the current page is implied.
|
In the following "if date" examples:
| ||
| - | Evaluates to true if VALUE is within DATE
|
| - | true if VALUE (or current date if omitted) is DATE1 or later (unlimited)
|
| - | true if VALUE (or current date if omitted) is DATE2 or earlier (unlimited)
|
| - | true if VALUE (or current date if omitted) is in range DATE1 to DATE2 (inclusive)
|
| - | true if PHP VAR exists and is not false
|
| - | true if user has entered any password during the current browser session.
- This does not mean the user has entered the correct password, just that they entered one. |
| - | true if STRING1 equals STRING2 , use quotes if the string or string variable contains spaces, eg "MY STRING"
|
| - | true if current page name matches the regular expression |
| - | true if the page "pagename " or "groupname.pagename " exists (case insensitive)Multiple pages can be specified, e.g. is true if at least one among the pages "p1", "p2" or those in the "mygroup" group exist.
|
| - | true if ThisPage is in a list used as a trail on "WikiTrailPage "
|
The name and group conditionals will work even for an included page, as the "name" and "group" conditionals always check the currently displayed page, as opposed to the page that the markup appears in.
Note: Although there is no built-in conditional markup to test ?action=, you can use (:if equal {$Action} ACTION:)
to test what the current action being requested is.
Concatenated conditions
In some cases where built in conditions have a parameter the parameters may be concatenated using a comma, viz:
Negated Conditions
Negated forms of conditions also work:
| - | this page has no attachments |
| - | current page is NOT named "PAGENAME "
|
| ||
| - | group is not named "GROUPNAME1 " or "GROUPNAME2 "
|
Nesting Conditions
Note that (:if cond:)
automatically closes a previous conditional. Thus, the following two examples have identical meaning:
(:if cond1:) cond1 is true (:if cond2:) cond2 is true (:ifend:)
(:if cond1:) cond1 is true (:ifend:)(:if cond2:) cond2 is true (:ifend:)
Conditions can be nested from 2.2.beta 66. To have nested conditionals you need to number the if, and the matching else/ifend:
cond1 is true cond1 and cond2 are true cond1 and cond3 are true, cond2 is not cond1 is true, cond2 and cond3 are not cond1 is false, cond2 testing was ignored |
Spaces were added for better readability.
Using wildcard placeholders
The character *
can be used as a wildcard to represent any character, zero, one, or multiple times.
The character ?
can be used as a wildcard to represent any character exactly once.
Wildcard characters (*
and ?
) can be used with the name and group conditional markups, thus:
| - | current page is in group PmCal and begins with 2005 |
| - | current page is in group PmWiki or a group beginning with PmWiki |
| - | current page is in group Profiles but not Profiles.Profiles
|
Using page text variables, page variables and markup expressions
Page text variables (PTVs), page variables (PVs) and markup expressions can be used in conditional markup. They will be assigned/evaluated before the condition(s).
Combining conditions
Conditions (as previously defined) may be combined into more complex conditional expressions using one of these three equivalent forms:
Conditions are combined into expressions with boolean operators and brackets. In the next table, A and B are either regular conditions or (round-)bracketed sub-expressions of regular conditions:
Expression | Operator | Result |
---|---|---|
A and B | And | TRUE if both A and B are TRUE. |
A or B | Or | TRUE if either A or B is TRUE. |
A xor B | Xor | TRUE if either A or B is TRUE, but not both. |
! A | Not | TRUE if A is not TRUE. |
A && B | And | TRUE if both A and B are TRUE. |
A || B | Or | TRUE if either A or B is TRUE. |
Example
equivalent to |
Important Notes:
- Spaces are required around operators and brackets.
- No specific feedback is given for syntax errors or unbalanced brackets.
- Use round brackets (not square) for nested expressions.
Thus, the following is a valid way of building an expression that shows the following contents only when the user is either the administrator, or is logged in and the time is later than the given date:
Nesting with square brackets will silently fail to work as expected:
NOTE: Doesn't Work!
A common use of these complex tests are for expressions like:
[[Logout -> {*$Name}?action=logout]] |
which provides a logout link only when the browser has admin, attr, or edit permissions.
admins (advanced)
Creating new conditions
See Cookbook:ConditionalMarkupSamples.
See also special references for the use of {*$Variables}
.
This page may have a more recent version on pmwiki.org: PmWiki:ConditionalMarkup, and a talk page: PmWiki:ConditionalMarkup-Talk.