Barry King > Apache-Wyrd > Apache::Wyrd::Interfaces::Setter

Download:
Apache-Wyrd-0.98.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.98   Source  

NAME ^

Apache::Wyrd::Interfaces::Setter - Templating Interface for Wyrds

SYNOPSIS ^

    !:information {<tr><td colspan="2">No information</td></tr>}
    ?:information {
      ?:phone{<tr><th>Phone:</th><td>$:phone</td></tr>}
      ?:fax{<tr><th>Fax:</th><td>$:fax</td></tr>}
      ?:email{<tr><th>Email:</th>
        <td><a href="mailto:$:email">$:email</a></td></tr>}
      ?:www{<tr><th>WWW:</th>
        <td><a href="$:www" target="external">$:www</a></td></tr>}
    }

    #interpret enclosed text and set enclosed text to result.
    $wyrd->_data($wyrd->_set());

    #interpret enclosed text and set the item placemarker.
    $wyrd->_data($wyrd->_set({item => 'this is the item'}));

    #interpret given template and set enclosed text to the result.
    $wyrd->_data($wyrd->_set(
      {item => 'this is the item'},
      'This is the item: $:item'
    ));

DESCRIPTION ^

The Setter interface give Wyrds a small templating "language" for placing variables into HTML: In short summary, there are two kinds of tokens interpreted by the Setter: a placemarker and a conditional. For placemarkers, any valid perl variable name preceded by dollar-colon ("$:") is replaced by the value of that variable. For conditionals, any valid perl variable name preceded by an exclamation or question mark and followed by curly braces enclosing text shows the enclosed text conditionally if the variable is true ("?:") or false ("!:"). These conditionals can be nested.

The Setter interface provides several "flavors" of Set-ting functions depending on their purpose. In general, however, they all accept two optional variables, one being the hashref of variables to set with, the second being the text which will be interpreted. If the second variable is not provided, it is assumed that the enclosed text is the text to be processed. If neither the first or the second is provided, it is also assumed the CGI environment is the source for the variable substitution.

If the CGI environment is used, the Setter will use the minimum necessary, only using the items it can clearly find in placemarkers.

METHODS ^

(format: (returns) name (arguments after self))

(scalar) _set ([hashref], [scalar])

Simplest flavor. If a place-marked variable doesn't exist as a key in the hashref which is the first argument (or in the CGI environment if the hashref is not provided), then the placemarker is not interpreted, and remains untouched.

(scalar) _clear_set ([hashref], [scalar])

Same as _set, but wipes anything remaining that looks like a placemarker.

(scalar) _clean_set ([hashref], [scalar])

More perl-ish. If the placemarker is undefined OR false, it is not interpreted.

(scalar) _text_set ([hashref], [scalar])

More text-ish and perl-ish. If the placemarker is undefined OR false, it is not interpreted. Anything else that looks like a placemarker after interpretation is finished is wiped out. Generally safe for output directly to web pages.

(scalar) _quote_set ([hashref], [scalar])

More SQL-ish, but not CGI-ish. A blank hashref is used in place of the CGI environment when passed no parameters. Placemarkers are replaced with the quote function of DBI via the Wyrd->dbl->quote function so as to be used in SQL queries.

(scalar) _cgi_quote_set ([scalar])

same as _quote_set, but with the CGI environment option forced and no interpreted hash option.

(scalar) _escape_set ([hashref], [scalar])

More HTML-form-ish but not CGI-ish. A blank hashref is used in place of the CGI environment when passed no parameters. Values are HTML escaped so they can be used within <input type="text"> tags in HTML.

(scalar) _cgi_escape_set ([scalar])

same as _escape_set, but with the CGI environment option forced and no interpreted hash option.

(scalar) _regexp_conditionals (hashref, scalar)

internal method for performing conditional interpretation.

(scalar) _clear_regexp_conditionals (hashref, scalar)

internal method for performing conditional interpretation. Unlike _interpret_conditionals, this method considers the non-existence of a condition to mean a negative value for the condition.

(scalar) _setter_replacements (hashref, scalar)

internal method for performing value replacements.

(scalar) _setter_defaults (hashref, scalar)

internal method for setting default template to BASECLASS::_data and default parameters to null hash.

(scalar) _cgi_hash (hashref, scalar)

internal method for interpreting the CGI environment into the template data hashref.

(scalar) _attribute_template (array)

Shortcut method for quickly creating templates of all attributes in a wyrd, given an array of attribute names.

(scalar) _template_hash (string, [hashref])

Shortcut method for quickly creating a hash from a template. If the template is not provided, the object's _data attribute is used. If a hashref is supplied as the second value, values for the returned hashref are based on that. Otherwise, the calling object itself provides the values. By default, template items that are not defined by the attributes of the object or provided hashref are ignored.

BUGS/CAVEATS/RESERVED METHODS ^

Interpolation Bug

"$:" is a variable in perl, so be sure to escape or single-quote your in-code templates. If you start seeing -variablename in your pages, you'll know why.

Defined Null Conditional Bug

There's some un-perlish behavior in the setting of conditionals. Conditional statements are set (?) or unset (!) depending on whether the item is defined, not whether it is true. An eq operator, for example, returns '' (the null string) when the arguments are not equivalent strings, so a template with a conditional that should be false, and therefore unset, is actually considered true, since the result is defined and exists. For example

    $result = $self->_set({'a' => 'a' eq 'b'}, '?:a{wrong}');

returns "wrong", not ''. To prevent this, it should be written:

    $result = $self->_set({'a' => ('a' eq 'b') || undef}, '?:a{wrong}');

AUTHOR ^

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO ^

Apache::Wyrd

General-purpose HTML-embeddable perl object

LICENSE ^

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.

syntax highlighting: