/ 
Apache-Wyrd-0.85
River stage zero No dependents
/ Apache::Wyrd::Interfaces::Setter

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 palacemarker and a conditional. For placemarkers, any valid perl variable name preceeded by dollar-colon ("$:") is replaced by the value of that variable. For conditionals, any valid perl variable name preceeded by an exclamation or question mark and follwed by curly braces enclosing text shows the enclosed text conditionally if the variable is true ("?:") or false ("!:"). These conditionals can be nested.

Note that despite the flavor of Set-ting, conditionals are always interpreted and are considered false on non-existent, undefined, zero, or '' values, and true on anything else.

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 first argument (or in the CGI environment if missing), 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.

(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) _cgi_hash (hashref, scalar)

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

BUGS/CAVEATS/RESERVED METHODS

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

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

LICENSE

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

See LICENSE under the documentation for Apache::Wyrd.