version=pmwiki-2.2.5 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/532.0 (KHTML, like Gecko) Chrome/3.0.195.21 Safari/532.0
author=simon
charset=ISO-8859-1
csum=attachments apply to main page
host=203.97.214.12
name=PmWiki.ConditionalMarkup
rev=148
targets=PmWiki.ReleaseNotes,PmWiki.ChangeLog,PmWiki.AuthUser,PmWiki.WikiTrails,PmWiki.PageTextVariables,PmWiki.PageVariables,PmWiki.MarkupExpressions,PmWiki.PageListTemplates,Site.PageListTemplates
text=(:Summary:The if directive allows portions of a page to be included or excluded from rendering:)%0a%25define=indent block margin-left=2em%25%0a(:Audience: authors, admins (advanced) :)%0a!! Using the [=(:if:)=] Directive%0aThe [@(:if:)@] directive allows portions of a page to be included or %0aexcluded from rendering.  The generic forms of the [@(:if:)@] directive are%0a%0a-> [@(:if cond param:) body (:ifend:)@]%0a-> [@(:if cond param:) body (:else:) body (:ifend:)@]%0a-> [@(:if cond param:) body (:elseif cond param:) body (:ifend:)@] '^see [[PmWiki/ReleaseNotes#elseifelse|#]] [[PmWiki/ChangeLog#beta32|#]]^'%0a%0awhere "cond" names a [[#built-in-conditions | condition to be tested]], and "param" is a parameter or other argument to the condition.%0a%0a!! Markup Shortcut%0aYou can also use an abbreviated form of [@(:ifend:)@], [@(:if:)@] for brevity:%0a-> [@(:if cond1:) cond1 is true (:if:)@]%0a-> [@(:if cond1:) cond1 is true (:if cond2:) cond2 is true (:if:)@]%0aThe latter is identical to :%0a-> [@(:if cond1:) cond1 is true (:ifend:)(:if cond2:) cond2 is true (:ifend:)@]%0a%0a!! Built-in Conditions [[#built-in-conditions]]%0aThe built-in conditions include:%0a%0a(:table class='indent' border=0 cellpadding=0 cellspacing=0 valign=top:)%0a(:cellnr:)[@(:if name PAGENAME:)@]%0a(:cell:) - %0a(:cell:)current page is named "[@PAGENAME@]"%0a(:cellnr:)[@(:if group GROUPNAME:)@]%0a(:cell:) - %0a(:cell:)current group is named "[@GROUPNAME@]"%0a(:cellnr:)[@(:if auth LEVEL PAGENAME:)@]%0a(:cell:) - %0a(:cell:)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.%0a(:cellnr:)[@(:if authid:)@]%0a(:cell:) - %0a(:cell:)current viewer is authenticated - meaning they have proven who they are via login - to use this the wiki must include recipe [[PmWiki/AuthUser|AuthUser]] or others which set the [@$AuthId@] variable.%0a(:cellnr:)[@(:if enabled InvalidLogin:)@]%0a(:cell:) - %0a(:cell:)username and password not authenticated. To use this the wiki must include recipe AuthUser.%0a(:cellnr:)[@(:if true:)@]%0a(:cell:) - %0a(:cell:)always include text%0a(:cellnr:)[@(:if false:)@]%0a(:cell:) - %0a(:cell:)always exclude text (same as a comment)%0a(:cellnr:)[@(:if attachments:)@]%0a(:cell:) - %0a(:cell:)current page has one or more attachments%0aIf used in a sidebar, header, or footer the condition applies to the main page.%0a(:cellnr:)[@(:if date DATE VALUE:)@]%0a(:cell:) - %0a(:cell:)[@DATE@] may be year-month.  year-month-day is optional.  %0aEvaluates to true if [@VALUE@] is within [@DATE@] ("now" or "today" is assumed for VALUE. VALUE may be omitted, as in the following examples.)  (Note that [@VALUE@] can be a recognizable date via strtotime() whereas DATE [or DATE1 and DATE2 below] have a more fixed format which explicitly must exclude spaces.  Any spaces in DATE1 or DATE2 cause unpredictable results.)%0a(:cellnr:)[@(:if date DATE..:)@]%0a(:cell:) - %0a(:cell:)true if current date is [@DATE@] or later (unlimited)%0a(:cellnr:)[@(:if date DATE1..DATE2:)@]%0a(:cell:) - %0a(:cell:)true if current date is in range [@DATE1@] to [@DATE2@] (inclusive) %0a%25green newwin%25[-''dates are in [[http://w3.org/QA/Tips/iso-date|standard]] format yyyy-mm-dd or yyyymmdd or yyyymmddThhmm (note the "T" between the date and the hour, and also see comment above on format of VALUE).-]''%0a[[%3c%3c]][-Note the ".." cannot have leading or trailing spaces.-]%0a(:cellnr:)[@(:if enabled VAR:)@]%0a(:cell:) - %0a(:cell:)true if PHP VAR is true%0a(:cellnr:)[@(:if enabled AuthPw:)@]%0a(:cell:) - %0a(:cell:)true if user has entered any password during the current browser session.%0a- This does not mean the user has entered the correct password, just that they entered one.%0a(:cellnr:)[@(:if equal STRING1 STRING2:)@]%0a(:cell:) - %0a(:cell:)true if [@STRING1@] equals [@STRING2@], use quotes if the string or string variable contains spaces, eg [@"MY STRING"@]%0a(:cellnr:)[@(:if match REG_EXPRESSION:)@]%0a(:cell:) - %0a(:cell:)true if current page name matches the regular expression%0a(:cellnr:)[@(:if exists PAGENAME:)@]%0a(:cell:) - %0a(:cell:)true if the page ''pagename'' exists%0a(:cellnr:)[@(:if action ACTION:)@]%0a(:cell:) - %0a(:cell:)true if the action ?action=ACTION (edit, print, ...) is currently permitted. To test what the current action being requested is, use [@(:if equal {$Action} ACTION:)@].%0a(:cellnr:)[@(:if ontrail WikiTrailPage ThisPage:)@]%0a(:cell:) - %0a(:cell:)true if ThisPage is in a list used as a [[wiki trails | trail]] on WikiTrailPage%0a(:tableend:)%0a%0aThe 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.%0a%0a!! Negated Conditions%0aNegated forms of conditions also work:%0a%0a(:table class='indent' border=0 cellpadding=0 cellspacing=0 valign=top:)%0a(:cellnr:)[@(:if !attachments:)@]%0a(:cell:) - %0a(:cell:)this page has no attachments%0a(:cellnr colspan=3:) %0a(:cellnr:)[@(:if ! name PAGENAME:)@]%0a(:cell rowspan=3:)%0a(:cell rowspan=3 valign=middle:)current page is NOT named "[@PAGENAME@]"%0a(:cellnr:)[@(:if name -PAGENAME :)@]%0a(:cell:)%0a(:cellnr:)[@(:if name !PAGENAME :)@]%0a(:tableend:)%0a%0a!! Nesting Conditions [[#nested-conditions]]%0aConditions may be nested (from 2.2.beta 66).%0a%0aNested [@(:if:)@] works the same way as nested [@(:div:)@]. To have nested conditionals you need to number the if, and the matching else/ifend:%0a->[@%0a(:if cond1:)%0a  cond1 is true%0a  (:if2 cond2:)%0a     cond1 and cond2 are true%0a  (:else2:)%0a     cond1 is true, cond2 is not%0a  (:if2end:)%0a(:else:)%0a  cond1 is false, cond2 testing was skipped%0a(:ifend:)%0a@]%0a[-''Spaces were added for better readability.''-]%0a%0a!! Using wildcard placeholders(:if false:)%25green%25[-(new for pmwiki 2.1.beta21)-]:(:ifend:)%0aThe character [@*@] can be used as a wildcard to represent any character, zero, one, or multiple times.\\%0aThe character [@?@] can be used as a wildcard to represent any character exactly once.\\%0aWildcard characters ([@*@] and [@?@]) can be used with the ''name'' and ''group'' conditional markups, thus:%0a%0a(:table class='indent' border=0 cellpadding=0 cellspacing=0 valign=top:)%0a(:cellnr:)[@(:if name PmCal.2005* :)@]%0a(:cell:) - %0a(:cell:)current page is in group PmCal and begins with 2005%0a(:cellnr:)[@(:if group PmWiki* :)@]%0a(:cell:) - %0a(:cell:)current page is in group PmWiki or a group beginning with PmWiki%0a(:cellnr:)[@(:if name Profiles.*,-Profiles.Profiles :)@]%0a(:cell:) - %0a(:cell:)current page is in group [@Profiles@] but not [@Profiles.Profiles@]%0a(:tableend:)%0a%0a!!Using [[PmWiki/page text variables]], [[PmWiki/page variables]] and [[PmWiki/markup expressions]]%0aPage text variables (PTVs), page variables (PVs) and markup expressions can be used in conditional markup. They will be assigned/evaluated before the condition(s). %0a%0a!! Use with [[PmWiki/page list templates]]%0aConditional markup is used extensively with [[Site/page list templates]].%0a%0aUse with page variables:%0a-> =   current item%0a-> %3c   previous item%0a-> >   next item%0a%0aConditionals used to structure pagelist output:%0a  [@(:if equal {%3c$Group}:)@] deprecated in favour of [@(:template first:)@] At beginning of list%0a  [@(:if equal {>$Group}:)@] deprecated in favour of [@(:template last:)@] At end of list%0a  [@(:if ! equal {=$Group} {%3c$Group}:)@] deprecated in favour of [@(:template first {=$Group}:)@] First item in group%0a  [@(:if ! equal {=$Group} {>$Group}:)@] deprecated in favour of  [@(:template last {=$Group}:)@] Last item in group%0a%0a!! Combining conditions%0aConditions (as previously defined) may be combined into more complex conditional expressions using one of these three equivalent forms:%0a%0a->[@%0a(:if expr EXPRESSION :)%0a(:if [ EXPRESSION ] :)%0a(:if ( EXPRESSION ) :)@]%0a%0aConditions 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:%0a%0a>>indent%3c%3c%0a|| border=1 cellpadding=2 cellspacing=0%0a||! Expression ||! Operator ||! Result ||%0a|| [@A and B@] || And ||TRUE if both A and B are TRUE.||%0a|| [@A or B@] || Or ||TRUE if either A or B is TRUE.||%0a|| [@A xor B@] || Xor ||TRUE if either A or B is TRUE, but not both.||%0a|| [@! A@] || Not ||TRUE if A is not TRUE.||%0a|| [@A && B@] || And ||TRUE if both A and B are TRUE.||%0a|| [@A || B@] || Or ||TRUE if either A or B is TRUE.||%0a>>%3c%3c%0a%0aExample%0a->[@%0a(:if [ name SomePage and group SomeGroup ]:)    equivalent to (:if name SomeGroup.SomePage:)@]%0a%0aNote:%0a* Spaces around operators and brackets are required.%0a* No specific feedback is given for syntax errors or unbalanced brackets.%0a* Use round brackets (not square) for nested expressions.%0a%0aThus, 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:%0a%0a->[@(:if [ auth admin || ( authid && date 2006-06-01.. ) ] :)@]%0a%0aNesting with square brackets will silently fail to work as expected:%0a%0a->[@(:if [ auth admin || [ authid && date 2006-06-01 ] ] :) @]   %25red%25NOTE: Doesn't Work!%0a%0aA common use of these complex tests are for expressions like:%0a%0a->[@(:if expr auth admin || auth attr || auth edit :)@]%0a->[@[[Logout -> {$Name}?action=logout]]@]%0a->[@(:ifend:)@]%0a%0awhich provides a ''logout'' link only when the browser has admin, attr, or edit permissions.%0a%0a%25audience%25 admins (advanced)%0a!! Creating new conditions%0aSee [[Cookbook:ConditionalMarkupSamples]].%0a%0aSee also [[PmWiki/PageVariables#specialreferences|special references]] for the use of [={*$Variables}=].%0a%0a>>faq%3c%3c [[#faq]]
time=1253412612