This document describes Wendy API. It was last edited on 25 Sep 2007.

Note: not all of listed variables, constants, methods are exported by default. Better specify what symbols you need in use argument. Example:

use Wendy::Util 'meta_get_records';
use Wendy::Config ( 'CONF_NOCACHE', 'CONF_MEMCACHED' );
use Wendy::Hosts qw( get_host_languages all_hosts );

Wendy consists of several modules:

Wendy.pm Wendy::Config Wendy::Db Wendy::DataCache

Wendy::Hosts Wendy::Memcached Wendy::Modules Wendy::Procs

Wendy::Templates Wendy::Users Wendy::Util

See also:

• $WOBJ object
• Output object

Wendy not exports anything. Only one method is available:

• Wendy::__get_wobj() - Returns WOBJ object, which is a hash reference.

Top

Wendy::Config

• CONF_MYPATH - Wendy installation directory. Formed at install time.
• CONF_VARPATH - constant, path to Wendy var directory, which is catdir( <wendy installation directory>, var)
• CONF_DEFHOST - default host name. Specified during installation.
• CONF_DBNAME - database name
• CONF_DBUSER - database user name
• CONF_DBHOST - database host name. Can be array reference, in this case first working server is used.
• CONF_WDBHOST - separate write database host name. Can be array reference, in this case first working server is used.
• CONF_DBPASSWORD - database to run on
• CONF_NOCACHE - completely disables disk cache (not recommended)
• $WENDY_VERSION - string, Wendy version
• CONF_MEMCACHED - specifies is memcached caching enabled. Implemented with Cache::Memcached
• CONF_MC_SERVERS - array reference, memcached servers list
• CONF_MC_THRHOLD - memcached parameter, compress_threshold
• CONF_MC_NORHASH - memcached parameter, norehash

Top

Wendy::Db

Wendy provides support for several read-only and write-only DB servers. Write functions named with 'w' prefix. These functions will automatically work with "write"-server -- or with default (CONF_DBHOST) if CONF_WDBHOST not set.

IMPORTANT: use appropriate functions in your module. Call w-functions for modifying queries! For read queries better call meta_get_records.

• dbconnect() - connects to db specified in Config file. Called on initialization automatically.
• wdbconnect() - connects to WRITE db server specified in Config file. You should call it in your handler yourself.
• dbbegin() - "BEGIN WORK" - starts a transaction (on WRITE server)
• dbcommit() - "COMMIT" - commits a transaction (on WRITE server)
• dbrollback() - "ROLLBACK" - cancels transaction (on WRITE server)
• dbprepare( $sql ) - prepares statement. Returns statement handle ($sth). Do not use this for modifying queries like INSERT, UPDATE, DELETE - use wdbprepare in this cases!
• wdbprepare( $sql ) - prepares statement on write server. Returns statement handle ($sth)
• dbdisconnect() - disconnects from db, called automatically
• wdbdisconnect() - disconnects from write db, called automatically
• dbquote( $arg ) - quotes argument for safe db operating
• dbgeterror() - returns last db error
• wdbgeterror() - returns last write db server error
• dbdo( $sql ) - simple execute query, no data needed. Not exported by default. Do not use this for modifying queries like INSERT, UPDATE, DELETE - use wdbdo in this cases!
• wdbdo( $sql ) - simple execute query (on write server), no data needed
• dbselectrow( $sql ) - selects one row, returns hash reference, (selectrow_hashref)
• seqnext( $name ) - returns next value of sequence $name (queries write server)

Top

Wendy::DataCache

Provides methods to store scalar data. Data stored in memory if CONF_MEMCACHED is set, or in the file <host_dir>/cache/dc_<calculated_id> otherwise.

• datacache_store( Id => $id, TTL => $ttl, Data => $data )
• datacache_retrieve( $id ) returns stored scalar, undef if not found or expired.
• datacache_clear( $id ) deletes record from cache

Top

Wendy::Hosts

• http_host_init( $hostname ) - check and initializes host named $hostname as Wendy host. Returns hash with id, host, and defaultlng fields. If supplied host is bad, returns default host data.
• form_address( $str ) - forms and returns a template, or Wendy handler address from a string. For example /hello/world/ path becomes a hello_world Wendy address. So, hello_world template is processed, or hello_world.pl handler is looked for hello_world::wendy_handler function.
• get_host_languages( $host_id ) - returns hosts languages as hash
• get_host_aliases( $host_id ) - returns array, with aliases for host $host_id
• get_aliases() - returns all aliases. You may pass ( Host => $host_id ) or ( Host => [ $hid1, $hid2, $hid3, ...] ) to get aliases only for specific host(s). Returns hash alias_id => { id, host, alias }
• is_alias( $name ) - checks to see if $name is alias for some host, returns host id or undef
• all_hosts() - pulls out all hosts. Returns hash reference, id => { id, host, defaultlng }

Top

Wendy::Memcached

For arguments on mc_get, mc_set and mc_delete methods, see set, get, and delete methods in Cache::Memcached documentation.

• mc_init() - initialize memcached, parameters taken from Config file
• mc_set - store cache
• mc_get - get cache
• mc_delete - delete cache

Top

Wendy::Modules

• installed_modules( Host => $host_id, Id => $id ) - get installed modules, all arguments are optional, returns hash $installation_id => { $module_name, $host_id }
• register_module( Host => $host_id, Module => $module_name ) - registers a module as installed on host
• unregister_module( Host => $host_id, Module => $module_name ) - un-registers module from host
• is_installed( $module_name ) - looks if module_name is installed, returns hash as installed_modules does

This module is primarily for handling PROC: procedures in templates.

• get_all_proc_names() - just gets all procedures, returns hash reference ( $id => { id, name, body } )
• get_proc( Id => $proc_id, Name => $proc_name ) - same, but with parameters only one of Name od If should be passed.

Top

Wendy::Templates

This is what you will use most. It handles templates, macros contents, etc.

• template_process( $WOBJ or $scalar or undef ) - process a template. If $WOBJ is passed, template name taken from $WOBJ -> { "HPATH" }, If $scalar - that is template name itself, else Wendy::__get_wobj() called. Hash reference returned (if no errors), with all output-specific attributes: data, ctype, code, headers, ttl, expires, etc See Output object part.
• load_macros(HostId => $host, Address => $address, Lng => $language ) - loads a macros from database. Complex method, see it's shortcut:
• sload_macros( $addr or undef ) - loads macros for current host, current language and current addr ( $WOBJ -> { "HPATH" } if unspecified )
• unset_macros( @a ) - unsets macros. Without any arguments, unsets all macros.
• quoter( $str ) - quotes a sting, so it will not match replaces or functional keywords. Currently, this adds a space (or two) so data is simply not matched by Wendy::Templates regexps. Useful when user data gets processed inside template, like:

  add_replace( "FORM_ENTRY", $user_entered_data );

  which is more safe written as

  add_replace( "FORM_ENTRY", quoter( $user_entered_data ) );

• add_replace( %h ) - adds replaces. Argument must contain pairs macros_name => macros_value
• get_replace( $name ) - returns $name macros contents
• kill_replace( @_ ) - same as unset_macros, but safer, as it will not delete all macros in case of empty @a

Top

Wendy::Users

• get_user( Login => $login, Id => $id, Password => $pass) - get user record. Returns hash reference.

Top

Wendy::Util

All stuff goes here.

• build_directory_tree( $path ) - builds directory tree starting at $path, returns @array. Recursive.
• meta_get_records( Table => $t,
  Fields => [ 'id', $f1 ],
  Where => $sql,
  Limit => $int,
  OrderField => $fieldname,
  OrderMode => 'DESC' or 'ASC',
  Memcache => 1 or 0, better CONF_MEMCACHED
  MemcacheTime => $<time_to store in memcached> ) - generic method for DB queries with built-in memcached support. Just add Memcache => CONF_MEMCACHED in arguments hash. Returns hash. $id => { @fields }. Table must contain 'id' field as PRIMARY KEY. Use it. :-)
• meta_get_record(...) - same, but returns one record
• in( $val, @arr ) - checks wherever $val inside @arr or not
• download_url( URL => $url, Referer => $ref, Agent => $agentstr ) - Only URL parameter is mandatory. Returns hash reference. $outcome -> { "msg" } = ( 'ok' or 'bad' ) If bad, $outcome -> { "code" } contains http error code. On success: code, size, ctype, file or data, msg fields are set.

Top

$WOBJ Object

$WOBJ is object used to get access to Wendy state, initialization information, modules and handlers. Sometimes $WOBJ gets modified, for example template_process puts where a list of processed templates, not to cycle.

How to get $WOBJ

$WOBJ is passed to your wendy_handler as first argument.

Or you can get $WOBJ, by calling Wendy::__get_wobj() method.

What $WOBJ is:

Look ad it's dump:

$VAR1 = { 'HPATH' => 'somepath',
          'LNG' => 'en',
          'HOST' => { 'defaultlng' => '1',
              'id' => '1',
              'host' => 'www.myhost.com' },
          'COOKIES' => {},
          'TPLSTORE' => '/var/www/wendy/var/hosts/www.myhost.com/tpl',
          'RLNGS' => { 'en' => '1' },
          'CGI' => CGI object,
          'DBH' => DBI object, 
          'HANDLERSRC' => '/var/www/wendy/var/hosts/www.myhost.com/lib/somepath.pl',
          'REQREC' => Apache2::RequestRecord object };

It contains information about current host, language and also references to some objects you may need.

CGI	CGI object. Use to get POST/GET parameters, form headers, etc. see perldoc CGI
DBH	Database handle. I think you don't need it, look at Wendy::Db, for selecting data with memcached support, use meta_get_records
REQREC	mod_perl Apache2::RequestRecord object

Top

Output Object

Output object is a hash reference, in fields of which any output parameter can be customized. The following fields are available now:

data	Data to be sent to client. HTML, text, binary, etc
file	Path to file, which contents will be sent ( with $r -> sendfile() )
ctype	Custom content-type. Default is text/html.
code	Custom HTTP response code. Default is 200.
ttl	Seconds, how long can this page live in cache. Default - forever.
expires	Ugly version of ttl, specifies exact expiration timestamp (in seconds).
headers	Hash-reference to any custom headers header_name => header_value. Cookies are to be set this way currently.
nocache	1 or 0 Dont cache my output!
msg	Status message to show after http code.

Full output object can be returned from wendy_handler. But if handler returns scalar (string data) it is assumed to be data part:

return "Hello, world!";

my $output_object = { data => "Hello, world!" };
return $output_object;

Top

That's all, folks!

Top