This document describes how to create your own Wendy handler. Wendy handlers are Perl functions, written in separate modules (files). They allow you to perform any custom actions and return any custom output. Handlers can be hooked on any valid Wendy URL.

Example

For example, we have a host running Wendy, named www.example.com. On that host, we have a form for users to fill, at www.example.com/request/. We want our handler to process user input at www.example.com/request/process/.

Creating address

Go to Wendy admin -> Templates -> New page. Enter request/process. New address created.

Locating handler file

All handler files are located in <wendy dir>/var/hosts/www.example.com/lib directory. File name is form_address-ed of request path, so it will become request_process.pl.

Handler file contents

If you have direct access to hosts lib directory, you may write handler there yourself, otherwise use File Manager in Wendy admin to place request_process.pl file in correct location.

Here is example Wendy handler source:

use strict;
# Correct package name MUST be set
package request_process;

use Wendy::Templates;
use Wendy::Db;
use XML::Quote;

sub wendy_handler
{
    my $WOBJ = shift;
    my $cgi = $WOBJ -> { "CGI" };

    # Fetch form parameters:

    my $username = $cgi -> param( "username" );
    my $useremail = $cgi -> param( "email" );

    my $output = "";
    if( $username and $email ) # Form filled correctly
    {
        &wdbconnect();         # Connect to write DB server
        &wdbdo( "INSERT INTO request (name,mail)..." );


        # Request stored, process template and return its data
        my $oo = &template_process( "request_process" );
        $output = $oo -> { "data" };

    } else # Form not filled correctly
    {
        # Pre-fill user form with his values
        &add_replace( "USERNAME" => $username,
                      "USERMAIL" => $useremail );

        # Process and return initial form template
        my $oo = &template_process( "request" );
        $output = $oo -> { "data" };
    }

    return $output;
}
# Return true, for Perl require
1;

Note package request_process; statement at the beginning.

Output

This handler returns simple scalar which is used as text/html output. However, a complex Wendy output object can be returned (a hash reference). Documentation on Wendy output object can be found at Wendy API reference page.

Errors

Currently, for maximum performance, handlers are not eval-ed, but called directly, so a run-time or compile-time error in Wendy handler will cause 500 Internal Server Error — be sure to look into Apache error_log then.

Meta handler

From the 0.9.20080804 version a meta handler for any host can be defined. Meta handler is usual wendy handler, placed in meta.pl file (in host's lib directory) and providing meta::wendy_handler sub.

It has lower priority than exact address handler, so you can define a meta-handler for any addresses and a special one for a certain address at the same time.

Top