The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Konstrukt-0.5-beta13
River stage zero No dependents
++
/ Konstrukt::Plugin::if

NAME

Konstrukt::Plugin::if - Conditional blocks

SYNOPSIS

Usage:

        <!-- will put out "elsif1" -->
        <& if condition="0" &>
                <$ then $>then<$ / $>
                <$ elsif condition="1" $>elsif1<$ / $>
                <$ elsif condition="1" $>elsif2<$ / $>
                <$ else $>else<$ / $>
        <& / &>

        <!-- shortcut, when only using "then" and no elsif or else -->
        <!-- will put out "The condition is true!" -->
        <& if condition="2 > 1" &>
                The condition is true!
        <& / &>
        
        <!-- dynamic conditions -->
        <!-- non-dynamic conditions will only be checked once and then get cached -->
        <& if condition="int rand 2" dynamic="1" &>
                The condition is true with a chance of 50%!
        <& / &>

Result:

        <!-- will put out "elsif1" -->
        elsif1
        
        <!-- shortcut, when only using "then" and no elsif or else -->
        <!-- will put out "The condition is true!" -->
                The condition is true!

        <!-- dynamic conditions -->
        <!-- non-dynamic conditions will only be checked once and then get cached -->
                The condition is true with a chance of 50%!

DESCRIPTION

Will put out the appropriate content for the conditions. Will delete the block, if no condition matches and no else block is supplied.

The condition will be eval'ed. So if you only want to check if a value is true, you might want to encapsulate it in quotes, so that it won't be interpreted as perl code:

        <& if condition="'some value'" &>true<& / &>

Of course this will lead into problems, when the data between the quotes contains qoutes itself. So you really should be careful with the values that are put into the condition, as they will be executed as perl code. You'd better never pass conditions, that contain any strings entered by a user.

As for the perl plugin you can use these variables in your condition code: $Konstrukt::Handler, $Konstrukt::Settings, $Konstrukt::Lib, $Konstrukt::Debug, $Konstrukt::File, $template_values.

Static vs. dynamic conditions

Usually all conditions will be assumed static. That is that the result of the evaluation of the condition will be the same for every request. Thus the condition will only be evaluated once and then the result will be cached for later usage.

But as the conditions actually are only executed perl code, they may also be dynamic. Consider:

        <& if condition="int rand 2" dynamic="1" &>
                The condition is true with a chance of 50%!
        <& / &>

The definition of the condition is static (it's only text), but the result may vary on every request. So you have to define the dynamic attribute, which will prevent the caching of the result and evaluate the condition on every request.

So in the common case, wher you just use template values as the condition, there is no need to set the dynamic attribute. But when you execute perl code in the condition, it is likely that you want the dynamic behaviour.

METHODS

prepare

Parse for <$ then $> and so on.

If it's not a dynamic condition, it can already be processed in the prepare run.

If the if-tag is preliminary (i.e. when there is a tag inside the tag) this method will be called in the execute run nevertheless.

Parameters:

  • $tag - Reference to the tag (and its children) that shall be handled.

execute

Evaluate the condition and return the appropriate result.

Parameters:

  • $tag - Reference to the tag (and its children) that shall be handled.

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::Plugin, Konstrukt