Apache::Wyrd::Interfaces::Setter - Templating Interface for Wyrds
!: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' ));
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.
(format: (returns) name (arguments after self))
_set
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.
_clear_set
Same as _set, but wipes anything remaining that looks like a placemarker.
_clean_set
More perl-ish. If the placemarker is undefined OR false, it is not interpreted.
_text_set
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.
_quote_set
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.
_cgi_quote_set
same as _quote_set, but with the CGI environment option forced and no interpreted hash option.
_escape_set
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.
_cgi_escape_set
same as _escape_set, but with the CGI environment option forced and no interpreted hash option.
_regexp_conditionals
internal method for performing conditional interpretation.
_clear_regexp_conditionals
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.
_setter_replacements
internal method for performing value replacements.
_setter_defaults
internal method for setting default template to BASECLASS::_data and default parameters to null hash.
_cgi_hash
internal method for interpreting the CGI environment into the template data hashref.
_attribute_template
Shortcut method for quickly creating templates of all attributes in a wyrd, given an array of attribute names.
_template_hash
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.
"$:" 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.
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}');
Barry King <wyrd@nospam.wyrdwright.com>
General-purpose HTML-embeddable perl object
Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.
See LICENSE under the documentation for Apache::Wyrd.
Apache::Wyrd
To install Apache::Wyrd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::Wyrd
CPAN shell
perl -MCPAN -e shell install Apache::Wyrd
For more information on module installation, please visit the detailed CPAN module installation guide.