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. The best way to use this feature is to define two [[TWikiVariables]], one for the THEN case and the other for the ELSE case. For example:
   8
   9     <!--
  10        * Set LI = Fred is here!
  11        * Set LO = Fred is there!
  12     -->
  13     %IF{"context authenticated and defined WIKINAME and $ WIKINAME='FredBloggs'" then="%LI%" else="%LO%"}%
  14
  15 The basic syntax of a condition is as follows:
  16
  17     expr ::= '(' expr ')' ;
  18     expr ::= andexpr | andexpr 'or' expr ;
  19     andexpr ::= notexpr | notexpr 'and' andexpr ;
  20     notexpr ::= basexpr | 'not' baseexpr ;
  21     basexpr ::= atom | uop atom | atom bop basexpr ;
  22     uop ::= 'context' | 'defined' | '$' ;
  23     bop ::= '=' | '!=' | '>' | '<' | '>=' | '<=' ;
  24     atom ::= context identifier, TWiki variable name, single-quoted string
  25 <table border="1" cellpadding="0" cellspacing="0">
  26   <tr>
  27     <th bgcolor="#99CCCC" colspan="2"><strong> Operators </strong></th>
  28   </tr>
  29   <tr>
  30     <td> and </td>
  31     <td> True if both sides are true </td>
  32   </tr>
  33   <tr>
  34     <td> or </td>
  35     <td> True if one or other side is true </td>
  36   </tr>
  37   <tr>
  38     <td> not </td>
  39     <td> negate the following expression </td>
  40   </tr>
  41   <tr>
  42     <td> =, != </td>
  43     <td> String comparison </td>
  44   </tr>
  45   <tr>
  46     <td> &lt;, &gt;, &lt;=, &gt;= </td>
  47     <td> Number comparison (there is no explicit numeric =) </td>
  48   </tr>
  49   <tr>
  50     <td> context </td>
  51     <td> True if the current context is set (see below) </td>
  52   </tr>
  53   <tr>
  54     <td> defined </td>
  55     <td> True if a preference variable or url parameter of this name is defined. </td>
  56   </tr>
  57   <tr>
  58     <td> $ </td>
  59     <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 quoted string may <strong>not</strong> contain quotes (' or "). </td>
  60   </tr>
  61 </table>
  62
  63 examples:
  64
  65     %IF{"defined WIKINAME" then="WIKINAME is defined" else="WIKINAME is not defined"}%
  66
  67     You are %IF{ "$ WIKINAME='TWikiGuest' and not defined OPEN_DAY" then="not" }% allowed to
  68     %IF{ "context view" then="view" else="edit"}% this TWiki today.
  69
  70     %IF{ "defined search" then="Search: %URLPARAM{search}%" else="No search passed in"}%
  71
  72     url param t is %IF{ "0 < $ t and $ t < 1000" then="in" else="out of"}% range.
  73
  74     %IF{ "$'URLPARAM{scope}'='text'" then="Plain text search" }%
  75
  76 Given
  77
  78 - Set OPEN\_DAY = yes
  79
  80 this expands to:
  81
  82 You are allowed to edit this TWiki today.
  83
  84 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:
  85
  86 <table border="1" cellpadding="0" cellspacing="0">
  87   <tr>
  88     <th bgcolor="#99CCCC"><strong> id </strong></th>
  89     <th bgcolor="#99CCCC"><strong> context </strong></th>
  90   </tr>
  91   <tr>
  92     <td> absolute_urls </td>
  93     <td> Set if absolute URLs are required </td>
  94   </tr>
  95   <tr>
  96     <td> authenticated </td>
  97     <td> a user is authenticated </td>
  98   </tr>
  99   <tr>
 100     <td> body_text </td>
 101     <td> when the body text is being processed in a view (useful in plugin handlers) </td>
 102   </tr>
 103   <tr>
 104     <td> can_login </td>
 105     <td> current environment supports login </td>
 106   </tr>
 107   <tr>
 108     <td> changes </td>
 109     <td> in changes script (see [[Main/TWikiScripts]]) </td>
 110   </tr>
 111   <tr>
 112     <td> command_line </td>
 113     <td> the running script was run from the command line, and not from CGI </td>
 114   </tr>
 115   <tr>
 116     <td> diff </td>
 117     <td> in rdiff script (see [[Main/TWikiScripts]]) </td>
 118   </tr>
 119   <tr>
 120     <td> edit </td>
 121     <td> in edit script (see [[Main/TWikiScripts]]) </td>
 122   </tr>
 123   <tr>
 124     <td> footer_text </td>
 125     <td> when the footer text is being processed in a view (useful in plugin handlers) </td>
 126   </tr>
 127   <tr>
 128     <td> header_text </td>
 129     <td> when the header text is being processed in a view (useful in plugin handlers) </td>
 130   </tr>
 131   <tr>
 132     <td> i18n_enabled </td>
 133     <td> when user interface [[Main/I18N]] support is enabled (i.e., user can choose the language for UI) </td>
 134   </tr>
 135   <tr>
 136     <td> inactive </td>
 137     <td> if active links such as 'edit' and 'attach' should be disabled </td>
 138   </tr>
 139   <tr>
 140     <td> mirror </td>
 141     <td> if this is a mirror </td>
 142   </tr>
 143   <tr>
 144     <td> new_topic </td>
 145     <td> if the topic doesn't already exist </td>
 146   </tr>
 147   <tr>
 148     <td> oops </td>
 149     <td> in oops script (see [[Main/TWikiScripts]]) </td>
 150   </tr>
 151   <tr>
 152     <td> preview </td>
 153     <td> in preview script (see [[Main/TWikiScripts]]) </td>
 154   </tr>
 155   <tr>
 156     <td> rss </td>
 157     <td> if this is an RSS skin rendering </td>
 158   </tr>
 159   <tr>
 160     <td> save </td>
 161     <td> in save script (see [[Main/TWikiScripts]]) </td>
 162   </tr>
 163   <tr>
 164     <td> search </td>
 165     <td> in search script (see [[Main/TWikiScripts]]) </td>
 166   </tr>
 167   <tr>
 168     <td> view </td>
 169     <td> in view script (see [[Main/TWikiScripts]]) </td>
 170   </tr>
 171   <tr>
 172     <td> rest </td>
 173     <td> in rest script (see [[Main/TWikiScripts]]) </td>
 174   </tr>
 175 </table>
 176
 177 In addition there is an identifier for each enabled plugin; for example, if `GallousBreeksPlugin` is installed **and enabled**, then the context ID `GallousBreeksPluginEnabled` will be set.
 178
 179 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]].