1
2
3
4
5
6
7
8
9
|
version=pmwiki-2.3.33 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum=if action browse,edit (case insensitive) (+78)
name=PmWiki.ConditionalMarkup
rev=206
targets=PmWiki.AvailableActions,PmWiki.Passwords,PmWiki.Security,PITS.01417,PmWiki.AuthUser,Cookbook.AuthUser,PmWiki.PageTextVariables,Cookbook.ConditionalMarkupSamples,PmWiki.WikiTrails,PmWiki.PageVariables,PmWiki.MarkupExpressions
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) :)%0aThe %25pmhlt%25[@(:if:)@] directive allows portions of a page to be included or excluded from rendering. %0a%0a!! Using the %25pmhlt%25[=(:if:)=] Directive%0a%0aThe generic forms of the %25pmhlt%25[@(:if:)@] directive are%0a%0a%0a(:markup class=norender:)%0a(:if cond param:) body (:ifend:)%0a(:if cond param:) body (:else:) body (:ifend:)%0a(:if cond param:) body (:elseif cond param:) body (:ifend:)%0a(:if cond param:) body (:elseif cond param:) body (:else:) body (:ifend:)%0a(:markupend:)%0a%0awhere "cond" names a condition to be tested, and "param" is a parameter or other argument to the condition.%0a%0a''Note that %25pmhlt%25[@(:if:)@] without parameters and [@(:ifend:)@] are identical. Also note that [@(:if cond:)@] automatically closes a previous conditional. For nested multiple levels, see [[#nested-conditions|Nested conditionals]].''%0a%0a!! Built-in Conditions [[#built-in-conditions]]%0aThe built-in conditions include:%0a%0a:[@(:if name PAGENAME:)@]: %25list pmhlt%25 current page is named "''[@PAGENAME@]''" or "''[@GROUPNAME.PAGENAME@]''" (case insensitive)%0a%0a:[@(:if group GROUPNAME:)@]: current group is named "''[@GROUPNAME@]''" (case insensitive)%0a%0a:[@(:if action ACTION:)@]: %25list pmhlt%25 current [[AvailableActions|action]] is "''[@ACTION@]''" (case sensitive), e.g. "browse" or "edit"%0a%0a:[@(:if auth LEVEL PAGENAME:)@]: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.\\%0aThis is mostly used to hide and show portions of the interface only useful to editors or admins.\\%0a%25red%25'''Security warning:''' Neither this nor any other condition is meant to hide ''secrets''. \%0aConditions may easily be circumvented%25%25 in many cases, as described in [[Passwords(#condmarkup-secrets)]]. \%0aSee also: [[Security]], [[PITS:01417]].%0a%0a:[@(:if auth @readers,@editors:)@]:current viewer is member of at least one user group among "@readers" or "@editors". This can be configured with [[PmWiki/AuthUser|AuthUser]] or via custom recipes (from PmWiki 2.3.17).%0a%0a:[@(:if authid:)@]: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%0a:[@(:if enabled InvalidLogin:)@]:username and password not authenticated. To use this the wiki must include recipe [[Cookbook:AuthUser]].%0a%0a:[@(:if true:)@]:always include text, case sensitive%0a%0a:[@(:if false:)@]:always exclude text (same as a comment, but [[Page Text Variables(#conditionals)]] ARE set), case sensitive%0a%0a:[@(:if attachments FILENAMES PAGENAME:)@]:@@PAGENAME@@ has one or more attachments among the specified. A pagename can be omitted, in that case the current page is implied.\\%0a@@FILENAMES@@ specify an attachment like "pic1.jpg" or attachment patterns separated by commas, like "pic*.jpg,*.png" where asterisk (*) means "anything"; if omitted, any attachment (i.e. "*") is implied. \\%0aIf used in a sidebar, header, or footer, and the @@PAGENAME@@ is not specified, the condition applies to the main page. \\%0ae.g. [@(:if attachments *.png,*.gif Groupname.PageName:)@] (FILENAMES must not have quotation marks)%0a%0aIn the following "if date" examples:%0a* [@DATE@] may be year-month. year-month-day is optional. %0a* [@VALUE@] can be a recognizable date via %25newwin%25[[http://php.net/manual/en/function.strtotime.php | strtotime()]]%0a* @@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* "now" or "today" is assumed if @@VALUE@@ is omitted%0a* dates are in %25newwin%25 [[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* the ".." cannot have leading (when used with @@DATE1@@) or trailing spaces (when used with @@DATE2@@)%0a%0a:[@(:if date DATE VALUE:)@]:%25list pmhlt%25Evaluates to true if [@VALUE@] is within [@DATE@] %0a%0a:[@(:if date DATE1.. VALUE:)@]:true if [@VALUE@] (or current date if omitted) is [@DATE1@] or later (unlimited)%0a%0a:[@(:if date ..DATE2 VALUE:)@]:true if [@VALUE@] (or current date if omitted) is [@DATE2@] or earlier (unlimited)%0a%0a:[@(:if date DATE1..DATE2 VALUE:)@]:true if [@VALUE@] (or current date if omitted) is in range [@DATE1@] to [@DATE2@] (inclusive) %0a%0a:[@(:if enabled VAR:)@]:true if PHP @@VAR@@ exists and is not false%0a%0a:[@(:if enabled AuthPw:)@]: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.%0a%0a:[@(:if equal STRING1 STRING2:)@]:true if [@STRING1@] equals [@STRING2@], use quotes if the string or string variable contains spaces, eg [@"MY STRING"@]%0a%0a:[@(:if match REG_EXPRESSION:)@]:true if current page name matches the regular expression%0a%0a:[@(:if exists PAGENAME:)@]:true if the page "''[@pagename@]''" or "''[@groupname.pagename@]''" exists ([[Cookbook:ConditionalMarkupSamples#exists|case insensitive]])\\%0aMultiple pages can be specified, e.g. @@[=(:if exists p1,p2,mygroup.*:)=]@@ is true if at least one among the pages "p1", "p2" or those in the "mygroup" group exist.%0a%0a:[@(:if ontrail WikiTrailPage ThisPage:)@] [[#ontrail]]:true if @@ThisPage@@ is in a list used as a [[wiki trails | trail]] on "''[@WikiTrailPage@]''"%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[[#concatenatedconditions]]%0a!! Concatenated conditions%0aIn some cases where built in conditions have a parameter the parameters may be concatenated using a comma, viz:%0a* @@[=(:=]if name Name1,Name2,-Name3:) @@ %25list pmhlt%25%0a* @@[=(:=]if group -Group1,Group2,Group3:) @@%0a* @@[=(:=]if action browse,edit,diff:) @@%0a* @@[=(:=]if exists Page1,Group.*:) @@%0a%0a!! Negated Conditions%0aNegated forms of conditions also work:%0a%0a:[@(:if !attachments:)@]:%25list pmhlt%25this page has no attachments%0a%0a:[@(:if ! name PAGENAME:)@]: %0a:[@(:if name -PAGENAME :)@]:current page is NOT named "[@PAGENAME@]"%0a%0a:[@(:if group -GROUPNAME1,-GROUPNAME2 :)@]:group is not named "[@GROUPNAME1@]" or "[@GROUPNAME2@]"%0a%0a%0a!! Nesting Conditions [[#nested-conditions]]%0aNote that %25pmhlt%25[@(:if cond:)@] automatically closes a previous conditional. Thus, the following two examples have identical meaning:%0a(:comment careful with %25pmhlt%25 below:)%0a* %25pmhlt%25[@(:if cond1:)@] cond1 is true [@(:if cond2:)@] cond2 is true [@(:ifend:)@]%0a* %25pmhlt%25[@(:if cond1:)@]%25%25 cond1 is true %25bgcolor=#fcc%25'''[@(:ifend:)@]'''%25pmhlt%25[@(:if cond2:)@] cond2 is true [@(:ifend:)@]%0a%0aConditions can be nested from 2.2.beta 66. To have nested conditionals you need to number the if, and the matching else/ifend:%0a%0a(:markup class=norender:)%0a(:if cond1:)%0a cond1 is true%0a (:if2 cond2:)%0a cond1 and cond2 are true%0a (:elseif2 cond3:)%0a cond1 and cond3 are true, cond2 is not%0a (:else2:)%0a cond1 is true, cond2 and cond3 are not%0a (:if2end:)%0a(:else:)%0a cond1 is false, cond2 testing was ignored%0a(:ifend:)%0a(:markupend:)%0a%0a[-''Spaces were added for better readability.''-]%0a%0a!! Using wildcard placeholders%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:[@(:if name PmCal.2005* :)@]:%25list pmhlt%25current page is in group PmCal and begins with 2005%0a%0a:[@(:if group PmWiki* :)@]:current page is in group PmWiki or a group beginning with PmWiki%0a%0a:[@(:if name Profiles.*,-Profiles.Profiles :)@]:current page is in group [@Profiles@] but not [@Profiles.Profiles@]%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[[#combiningconditions]]%0a!! Combining conditions%0aConditions (as previously defined) may be combined into more complex conditional expressions using one of these three equivalent forms:%0a%0a(:markup class=norender:)%0a(:if expr EXPRESSION :)%0a(:if [ EXPRESSION ] :)%0a(:if ( EXPRESSION ) :)%0a(:markupend:)%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(:markup class=norender:)%0a(:if [ name SomePage and group SomeGroup ]:) %0aequivalent to (:if name SomeGroup.SomePage:)%0a(:markupend:)%0a%0a%0a'''Important Notes:'''%0a* Spaces are ''required'' around operators and brackets.%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->%25pmhlt%25[@(:if [ auth admin || ( authid && date 2006-06-01.. ) ] :)@]%0a%0aNesting with square brackets will silently fail to work as expected:%0a%0a->%25pmhlt%25[@(: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%0a(:markup class=norender:)%0a(:if expr auth admin || auth attr || auth edit :)%0a[[Logout -> {*$Name}?action=logout]]%0a(:ifend:)%0a(:markupend:)%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 %25pmhlt%25@@[={*$Variables}=]@@.
time=1714288827
|
