IfDefinedPlugin < TWiki

TWiki Web>IfDefinedPlugin (12 Sep 2008, TWikiAdminGroup) (raw view)EditAttach
<!--

   PLEASE DO NOT EDIT THIS TOPIC

   It is automatically generated from the subversion repository, and any changes
   you make will simply be overwritten the next time a release is generated.

   Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author(s).
-->
---+!! <nop>%TOPIC%

%TOC%

---++ Description
<table style="float:right">
<tr>
  <td><img src="%ATTACHURLPATH%/wikiringlogo40x40.png"></td>
  <td><a href="http://wikiring.de" title="Make your Wiki ring!" style="text-decoration:none">
      Powered by <br /> <nop>WikiRing Consultants </a>
  </td>
</tr>
</table>
This plugin adds a couple of tags that allow to render content conditionally.
There are two different ways to do that: either by using the inline 
=%<nop>IFDEFINED{"string" then="..." else="..."}%= tag that returns the 
=then= or =else= argument depending on the =string= being defined, that is non-empty.
There are no other ways to decide the condition but rendering the =test= string 
being a <nop>TWikiML expression, for example by embedding a =%<nop>CALC{}%= expression. This simplifies
this plugin alot and allows a rather flexible way to generate the condition.

The other way is to use blocks of content surrounded by expressions like this:
<verbatim>
%IFDEFINEDTHEN{"test"}%
...
%ELSIFDEFINED{"test"}%
...
%ELSEDEFINED%
...
%FIDEFINED%
</verbatim>
This way the conditioned content is not limited to fit into a the argument
position of a =%<nop>IFDEFINED{...}%= expression.  Blocks can be nested and are
evaluated starting from the outside, contrary to standard <nop>TWikiML being
evaluated left-to-right-inside-out.

---++ Related work
Similar extensions have been done before but are either only available as an integral part of TWiki-4.0 
(see TWiki:TWiki04/IfStatements) or unmaintained (see TWiki:Plugins/ConditionalPlugin).
Especially these two alternatives are rather similar as they defined the same tag (%IF).
The main differences between those and this plugin here is that they have a more elaborated
conditon parser that allows to evaluate more complex boolean expressions. Some of the
expressions in %IF of TWiki-4.0 are specific to that platform and make only sense there
(context). The other difference is that the IFDEFINED tag family allows nested blocks of
conditional content and %IF is an inline tag only.

The advantage of this plugin is that you get a simpler mechanism for checking the condition
which is however more flexible as the string can be generated arbitrarily using <nop>TWikiML.
Furthermore, and possibly more important, this plugin is backwards compatible and may be used
on a TWiki/Beijing, TWiki/Cairo and TWiki/Dakar engine.

This plugin has been externalized from the TWiki:Plugins/NatSkinPlugin.


---++ Syntax Rules
---+++ IFDEFINED
*Syntax*: 
<verbatim>
%IFDEFINED{"test" 
  [action="view,edit,preview,..."]? 
  [as="..."]
  then="..." 
  else="..." 
  glue="on,off"}%
</verbatim>

returns the "then or "else" content depending on the "test"
expression expanding to the emtpy string or matching the string given in "as".
Optionally the current topic action is checked to match the one given in "action".  
Normally, all surrounding whitespaces are removed, that is the resulting content
is glued together in a way. You may switch that off by setting "glue" to "off"
thus preventing all whitespace as it is.

The "then" and "else" strings may contain the following pseudo-variables:
   * =$n=: substituted with a newline character (\n)
   * =$percnt=: substituted with a percent character (%)
   * =$dollar=: substituted with a dollar character ($)
   * =$test= or =$variable=: substituted with the "test" string
   * =$value=: substituted with the "as" string


---+++ IFDEFINEDTHEN, ELSIFDEFINED, ELSEDEFINED, FIDEFINED
*Syntax*:
<verbatim>
%IFDEFINEDTHEN{"test" [action="view,edit,preview,..."]?}% 
  <then content> 
[%ELSIFDEFINED{...}% 
  <elsif content>]* 
[%ELSEDEFINED%
  <else content>]?
%FIDEFINED%
</verbatim>

This is the multi-line version of [[#IFSDEFINED][IFSDEFINED]].
IFDEFINEDTHEN expressions can be nested safely.  Within a single IFDEFINEDTHEN
the ELSIFDEFINED parts can be repeated arbitrarily.  Before rendering the
=&lt;then|elsif|else condition>= any =$nop= string will be removed first.
Thereby nested <nop>TWikiML expressions can be prevented from being expanded in
advance.

---+++ IFACCESS
*Syntax*:
<verbatim>
%IFACCESS%

%IFACCESS{"<webtopic>" 
  [type="view|change"] 
  [user="<WikiName>"] 
  [then="<then-clause>"] 
  [else="<else-clause>"] 
  [glue="on|off"]}%
</verbatim>

This checks the access permissions a user has on a given topic and then renders
the =&lt;then-clause>= if access is granted and =lt;else-clause>= otherwise.
By default, the current user's view access will be checked on the current topic (=%<nop>IFACCESS%=).
The other parameters are:

   * =&lt;webtopic>=: the name of the topic to be checked, defaults to current
   * =user="&lt;WikiName>"=: the name of the user to be checked, defaults to the current user
   * =type="view|change"=: the type of access to be checked, either view access or change/edit access, defaults to "view"
   * =then="&lt;then-clause>"=: the string to be returned on granted access, defaults to "1"
   * =else="&lt;else-clause>"=: the string to be returned if no access is granted, defaults to "0"
   * =glue="on|off"=: apply glue around the IFACCESS tag or not, defaults to "on"

---+++ IFEXISTS
*Syntax*:
<verbatim>
%IFEXISTS{"<webtopic>"
  [then="<then-clause>"] 
  [else="<else-clause>"] 
  [glue="on|off"]}%
</verbatim>

This tag checks if =webtopic= exists and expands =then-clause= or =else-clause= as needed.
A similar functionality is available using 
=%<nop>CALC{"$IF($EXIST(&lt;webtopic>,&lt;then-clause>),&lt;else-clause>)"}%=
of the SpreadSheetPlugin.
This is still preferable if you need more computation based on CALC in the 
then/else branches. The IFEXISTS version however is more lightweigted, comes with a much simpler syntax 
and allows more complex <nop>TWikiMarkup in the then/else branches.

---++ Demo
   * Set FOO = foo
   * FOO is %IFDEFINED{"%FOO%" then=" " else="not" glue="off"}% defined.
   * FOO is %IFDEFINED{"%FOO%" as="bar" then=" " else="not" glue="off"}% defined as "bar".
   * BAR is %IFDEFINED{"%BAR%" then=" " else="not" glue="off"}% defined.
   * %WIKIUSERNAME% has %IFACCESS{type="change" then=" " else=" no "}% write access to %TOPIC%
   * %MAINWEB%.TWikiGuest has %IFACCESS{user="TWikiGuest" type="change" then=" " else=" no "}% write access to %TOPIC%


---++ Plugin Installation Instructions

   * [[http://twiki.org/p/pub/Plugins/%TOPIC%/%TOPIC%.zip][Download]] the ZIP file
   * Unzip it in your twiki installation directory. Content: 
   | *File:* | *Description:* |
   | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
   | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
   * (Dakar) Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section.

---++ Plugin Info
<!-- provided for compatibility only
   * Set SHORTDESCRIPTION = Render content conditionally
-->
|  Plugin Author: | TWiki:Main.MichaelDaum |
|  Copyright &copy;: | 2006-2008, Michael Daum http://michaeldaumconsulting.com |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | v1.02 |
|  Change History: | <!-- specify latest version first -->&nbsp; |
|  03 Jul 2008: | more rookie perl errors | 
|  05 Oct 2007: | fixed a rookie perl error |
|  20 Jun 2007: | added IFEXISTS ;\
                  make use of TWiki-4 APIs for speed improvements |
|  18 Dec 2006: | removed support for cairo and beijing; added IFACCESS tag: checks access of some user on a topic |
|  18 Sep 2006: | allow multinline values to be checked |
|  31 Aug 2006: | added NO_PREFS_IN_TOPIC |
|  15 Aug 2006: | added =$test= and =$value= |
|  07 Aug 2006: | be smarter to detect the cgi action wrt to different apache setups |
|  10 Mar 2006: | added =as= parameter; \
                  added escape parameters and recursive variable expansion to the condition argument \
                  which helps to circumvent problems due to different plugin orders |
|  21 Feb 2006: | Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.8 |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle nn%, %TWIKIWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |


-- TWiki:Main.MichaelDaum - 03 Jul 2008
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	wikiringlogo40x40.png	manage	2.5 K	03 Jul 2008 - 23:18	TWikiAdminGroup	Saved by install script
Topic revision: r2 - 12 Sep 2008 - 20:10:29 - TWikiAdminGroup
TWiki
Webs
DnD
Main
Support
TWiki
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.IfDefinedPlugin