DADA::App::Guts

- NAME
- SYNOPSIS
- DESCRIPTION
- SUBROUTINES

- check_for_valid_email
- strip
- pretty
- make_pin
- check_email_pin
- make_template
- delete_list_template
- delete_list_info
- check_if_list_exists
- available_lists
- date_this
- convert_to_ascii
- uriescape
- make_safer
- check_list_setup
- user_error
- make_all_list_files
- message_id
- check_setup
- cased
- xss_filter
- check_referer

- COPYRIGHT

# NAME

DADA::App::Guts

# SYNOPSIS

     use DADA::App::Guts;

# DESCRIPTION

This module holds commonly used subroutines for the variety of other modules in Dada Mail. This module is slowly fading away, in favor of having much of Dada Mail Object Oriented. There are some subroutines that are, in reality, just wrappers around the new, Object Oriented ways of doing things. They are noted here.

# SUBROUTINES

## check_for_valid_email

            $e_test = check_for_valid_email($email_address);

returns 1 if the email is invalid.

But will return 0 if an email is invalid if you specify that addres in the @DADA::Config::EMAIL_EXCEPTIONS array in the Config file. Good for testing.

## strip

            my $str = strip($str);

    a simple subroutine to take off leading and trailing white spaces

## pretty

            $str = pretty($str);

a simple subroutine to turn underscores to whitespace

## make_pin

            $pin = make_pin(-Email => $email);

Returns a pin number to validate subscriptions

You can change how the pin number is generated a few ways;

There are two variables in the Config.pm file called the $DADA::Config::PIN_WORD and the $DADA::Config::PIN_NUM , they'll change the outcome of $pin, The algorithym to make a pin number isn't that sophisticated, I'm not trying to keep a nuclear submarine from launching its missles, although if you create your own $DADA::Config::PIN_NUM and $DADA::Config::PIN_WORD , it'll be pretty hard to decipher 6230 from justin@example.com

## check_email_pin

            my $check = check_email_pin(-Email=>$email, -Pin=> $pin);

checks a given e-mail with the given pin, returns 0 on when the pin is VALID (Weird, yes?), 1 on FAILURE.

## make_template

            make_template({
                          -List     => $list,
                          -Template => $template
                         });

takes where you want the template to be saved, the list that this template belongs to and the actual data to be saved in the template and saved this to a file. Usually, a template file is made when a list is created, using either the default Dada Mail template.

Templates are stored in the $DADA::Config::TEMPLATES directory (which is usually set the same as $DADA::Config::FILES) under the name $listname.template, where $listname is the List's shortname.

## delete_list_template

            delete_list_template({ -List => $list });

deletes a template file for a list.

## delete_list_info

            delete_list_info(-List => $list);

deletes the db file for a list.

## check_if_list_exists

            check_if_list_exists(-List => $list, );

checks to see if theres a filename called $list returns 1 for success, 0 for failure.

## available_lists

            my @lists = available_lists();

return an array containing the listshortnames of available list.

Can take a few paramaters - all are optional:

- -As_Ref

  returns a reference to an array, instead of an array

- -In_Order

  returns the array in alphabetic order - but NOTE: not in alphabetical order based on the listshortnames, but of the actual list names.

- -Dont_Die

  As the name implies, the subroutine won't kill the program calling it, if there's a problem opening the directory you've set in the Config.pm $FILES variable.

- -dbi_handle

  In Dada Mail, dbi handles are passed to different methods/subroutines in various was, so that they may be reused.

  If you're using Dada Mail with the SQL backend for the list settings, you could do something like this:

       use DADA::Config;
       use DADA::App::Guts;

       my $dbi_handle;

       if($SETTINGS_DB_TYPE =~ m/SQL/){
           require DADA::App::DBIHandle;
           $dbi_handle = DADA::App::DBIHandle->new;
       }

       my @available_lists = DADA::App::Guts::available_lists(-dbi_handle => $dbi_handle);

  to reuse the database handle you've just made.

Using all these paramaters at once would look something like this:

     my $available_lists = available_lists(
                                            -As_Ref => 1,
                                            -In_Order => 1,
                                            -Dont_Die => 1,
                                            -dbi_handle => $dbi_handle,
                                           );

## date_this

            my $readable_date =     date_this($packed_date)

this takes a packed date, say, the key of an archive entry and transforms it into an html data. the date is packed as

yyyymmdd

where, yyyy is the year in this form: 2000 mm is the month in this form: 01 dd is the day in this for 31

it returns something that looks like this:

            <i>Sent January 1st, 2001</i>

## convert_to_ascii

            $string = convert_to_ascii($string);

takes a string and dumbly strips out HTML tags,

## uriescape

            $string = uriescape($string);

    use to escape strings to be used as url strings.

## make_safer

            $string = make_safer($string);

This subroutine is used to make sure strings, such as list names, path to directories, critical stuff like that. This is in effort to make Dada Mail able to run in 'Taint' Mode. If you need to run in taint mode, it may need still some tweakin.

## check_list_setup

`check_list_setup()` is used when creating and editing the core basic list information, like the list name, list password, list owner's email address and the list password. to check a new list, you'll want to do this:

     my ($list_errors,$flags) =
         check_list_setup(-fields => {list            => $list,
                                       list_owner_email      => $list_owner_email,
                                        password        => $password,
                                        retype_password => $retype_password,
                                        info            => $info,
                                        });

Its a big boy. What's happening? this function returns two things, a reference to a hash with any errors it finds, and a scalar who's value is 1 or above if it finds any errors. here's a small reference to what $list_errors would return, all values in the hash ref will be one IF they are found to have something wrong in em:

list - no list name was given list_exists - the list exists password - no password given retype_password - the second password was not given password_ne_retype_password - the first password didn't math the second slashes_in_name - slashes were found in the list name weird_characters - unprintable characters were found in the list name quotes - quotes were found in the list name invalid_list_owner_email - the email address for the list owner is invlaid info - no list info was given.

here's a better example on how to use this:

     my ($list_errors,$flags) =
     check_list_setup(-fields => {list            => $list,
                                    list_owner_email      => $list_owner_email,
                                    password        => $password,
                                    retype_password => $retype_password,
                                    info            => $info,
                                    });
            if($flags >= 1){
            print "your list name was never entered!" if $list_errors -> {list} == 1;
            }

Now, if you want to check the setup of a list already created (editing a list) just set the -new_list flag to 'no', like this:

     my ($list_errors,$flags) =
     check_list_setup(-fields => {list            => $list,
                                    list_owner_email      => $list_owner_email,
                                    password        => $password,
                                    retype_password => $retype_password,
                                    info            => $info,
                                    },
                        -new_list => 'no'
                                    );

This will stop checks on the list name (which is already set) and if the list exists (which, hopefully it does, since we're editing it)

## user_error

deals with errors from a CGI interface

            user_error(-List => 'my_list',
                       -Error => 'some_error',
                       -Email => 'some@email.com');

## make_all_list_files

            make_all_list_files(-List => $list);

makes all the list files needed for a Dada Mail list.

## message_id

returns an id, based on the date.

## check_setup

makes sure the following directories exists and can be written into:

$DADA::Config::FILES $DADA::Config::TEMPLATES $DADA::Config::TMP

returns '1' if this is the case, 0 otherwise.

This test is disabled is $OS is set to a windows ( ^Win|^MSWin/i ) variant.

## cased

my $email = cased('SOME@WHERE.COM');

cased takes a string and recases the string, depending on what $DADA::Config::EMAIL_CASE is set to.

if the email address is: SOME@WHERE.com,

it will be changed to: some@where.com if $DADA::Config::EMAIL_CASE is set to: 'lc_all'

it will be changed to: SOME@where.com if $DADA::Config::EMAIL_CASE is set to: 'lc_domain'

## xss_filter

     $str = xss_filter($str);

Simple subroutine that strips '<', '>' and '``', and replaces them with HTML entities. This is used to stop text that can be interpretted as javascript, etc code from being executed.

## check_referer

     check_referer($q->referer());

Checks to see if the referer is the same as what's set in $DADA::Config::PROGRAM_URL

# COPYRIGHT

Copyright (c) 1999-2008 Justin Simoni

http://justinsimoni.com

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.