TWiki/IfStatements.mdwn

   1 The `%IF%` construct gives TWiki the power to include content in topics based on the value of simple expressions.
   2
   3 `%IF{"CONDITION" then="THEN" else="ELSE"}%`
   4
   5 In the example above, if CONDITION evaluates to TRUE, then THEN will be included in the topic; otherwise ELSE will be included.
   6
   7 What can be included in the THEN and ELSE parameters is obviously limited by standard TWiki syntax for parameters.
   8
   9 The basic syntax of a condition is as follows:
  10
  11     expr ::= '(' expr ')' ;
  12     expr ::= andexpr | andexpr 'or' expr ;
  13     andexpr ::= notexpr | notexpr 'and' andexpr ;
  14     notexpr ::= basexpr | 'not' baseexpr ;
  15     basexpr ::= atom | uop atom | atom bop basexpr ;
  16     uop ::= 'context' | 'defined' | '$' ;
  17     bop ::= '=' | '!=' | '>' | '<' | '>=' | '<=' ;
  18     atom ::= context identifier, TWiki variable name, single-quoted string, or configuration item
  19 <table border="1" cellpadding="0" cellspacing="0">
  20   <tr>
  21     <th bgcolor="#99CCCC" colspan="2"><strong> Operators </strong></th>
  22   </tr>
  23   <tr>
  24     <td> and </td>
  25     <td> True if both sides are true </td>
  26   </tr>
  27   <tr>
  28     <td> or </td>
  29     <td> True if one or other side is true </td>
  30   </tr>
  31   <tr>
  32     <td> not </td>
  33     <td> negate the following expression </td>
  34   </tr>
  35   <tr>
  36     <td> =, != </td>
  37     <td> String comparison </td>
  38   </tr>
  39   <tr>
  40     <td> &lt;, &gt;, &lt;=, &gt;= </td>
  41     <td> Number comparison (there is no explicit numeric =) </td>
  42   </tr>
  43   <tr>
  44     <td> context </td>
  45     <td> True if the current context is set (see below) </td>
  46   </tr>
  47   <tr>
  48     <td> defined </td>
  49     <td> True if a preference variable or url parameter of this name is defined. </td>
  50   </tr>
  51   <tr>
  52     <td> $ </td>
  53     <td> expands a URL parameter or [[Main/TWikiVariables]]. Plugin handlers <strong>are not called</strong>. Built-in variables and user-defined preferences are supported. You can pass a limited subset of parameters to TWiki variables by enclosing the variable name in single quotes; for example, <code>$ 'VARIABLE{value}'</code>. The <code>'VARIABLE{value}'</code> string may <strong>not</strong> contain quotes (' or "). </td>
  54   </tr>
  55 </table>
  56
  57 examples:
  58
  59     TWiki variable defined or not
  60     %IF{"defined WIKINAME" then="WIKINAME is defined" else="WIKINAME is not defined"}%
  61
  62     You are %IF{ "$ WIKINAME='TWikiGuest' and not defined OPEN_DAY" then="not" }% allowed to
  63     %IF{ "context view" then="view" else="edit"}% this TWiki today.
  64
  65     URL parameter
  66     %IF{ "defined search" then="Search: %URLPARAM{search}%" else="No search passed in"}%
  67
  68     Configuration item set or not
  69     %IF{ "{AntiSpam}{HideUserDetails}" then="User details are hidden" }%
  70
  71     url param t is %IF{ "0 < $ t and $ t < 1000" then="in" else="out of"}% range.
  72
  73     Text comparison
  74     %IF{ "$'URLPARAM{scope}'='text'" then="Plain text search" }%
  75
  76 **Configuration items** are defined in `configure`. You cannot see the value of a configuration item, you can only see if the item is set or not.
  77
  78 **Context identifiers** are used in TWiki to label various stages of the rendering process. They are especially useful for [[skin|Main/TWikiSkins]] authors to find out where they are in the rendering process. The following context identifiers are available:
  79
  80 <table border="1" cellpadding="0" cellspacing="0">
  81   <tr>
  82     <th bgcolor="#99CCCC"><strong> id </strong></th>
  83     <th bgcolor="#99CCCC"><strong> context </strong></th>
  84   </tr>
  85   <tr>
  86     <td> absolute_urls </td>
  87     <td> Set if absolute URLs are required </td>
  88   </tr>
  89   <tr>
  90     <td> authenticated </td>
  91     <td> a user is authenticated </td>
  92   </tr>
  93   <tr>
  94     <td> body_text </td>
  95     <td> when the body text is being processed in a view (useful in plugin handlers) </td>
  96   </tr>
  97   <tr>
  98     <td> can_login </td>
  99     <td> current environment supports login </td>
 100   </tr>
 101   <tr>
 102     <td> changes </td>
 103     <td> in changes script (see [[Main/TWikiScripts]]) </td>
 104   </tr>
 105   <tr>
 106     <td> command_line </td>
 107     <td> the running script was run from the command line, and not from CGI </td>
 108   </tr>
 109   <tr>
 110     <td> diff </td>
 111     <td> in rdiff script (see [[Main/TWikiScripts]]) </td>
 112   </tr>
 113   <tr>
 114     <td> edit </td>
 115     <td> in edit script (see [[Main/TWikiScripts]]) </td>
 116   </tr>
 117   <tr>
 118     <td> footer_text </td>
 119     <td> when the footer text is being processed in a view (useful in plugin handlers) </td>
 120   </tr>
 121   <tr>
 122     <td> header_text </td>
 123     <td> when the header text is being processed in a view (useful in plugin handlers) </td>
 124   </tr>
 125   <tr>
 126     <td> i18n_enabled </td>
 127     <td> when user interface [[Main/I18N]] support is enabled (i.e., user can choose the language for UI) </td>
 128   </tr>
 129   <tr>
 130     <td> inactive </td>
 131     <td> if active links such as 'edit' and 'attach' should be disabled </td>
 132   </tr>
 133   <tr>
 134     <td> mirror </td>
 135     <td> if this is a mirror </td>
 136   </tr>
 137   <tr>
 138     <td> new_topic </td>
 139     <td> if the topic doesn't already exist </td>
 140   </tr>
 141   <tr>
 142     <td> oops </td>
 143     <td> in oops script (see [[Main/TWikiScripts]]) </td>
 144   </tr>
 145   <tr>
 146     <td> preview </td>
 147     <td> in preview script (see [[Main/TWikiScripts]]) </td>
 148   </tr>
 149   <tr>
 150     <td> rss </td>
 151     <td> if this is an RSS skin rendering </td>
 152   </tr>
 153   <tr>
 154     <td> save </td>
 155     <td> in save script (see [[Main/TWikiScripts]]) </td>
 156   </tr>
 157   <tr>
 158     <td> search </td>
 159     <td> in search script (see [[Main/TWikiScripts]]) </td>
 160   </tr>
 161   <tr>
 162     <td> view </td>
 163     <td> in view script (see [[Main/TWikiScripts]]) </td>
 164   </tr>
 165   <tr>
 166     <td> rest </td>
 167     <td> in rest script (see [[Main/TWikiScripts]]) </td>
 168   </tr>
 169 </table>
 170
 171 In addition there is a context identifier for each enabled plugin; for example, if `GallousBreeksPlugin` is installed **and enabled**, then the context ID `GallousBreeksPluginEnabled` will be set. Other extensions may set additional context identifiers.
 172
 173 The `%IF%` statement is deliberately kept simple. In particular, note that there is no way to conditionally execute a Set statement. If you need more sophisticated control over formatting, then consider using the [[SpreadSheetPlugin]].