NAME
CGI::Listman - Easily managing web subscribtion lists
SYNOPSIS
use CGI::Listman;
DESCRIPTION
CGI::Listman provides an object-oriented interface to easily manage web-based subscribtion lists. It implements concepts such as "dictionaries", "selections", "exporters", provides some checking facilities (field duplication or requirements) and uses the DBI interface so as to provide a backend-independent storage area (PostgreSQL, ...).
The CGI::Listman class manages the listmanagers of your project. This is the very first class you want to instantiate. It is the logical central point of all others objects. Except for CGI::Listman::line, CGI::Listman::exporter and CGI::Listman::selection, you should not call any other class's "new" method since CGI::Listman will handle its own instances for you.
API
new
As for any perl class, new acts as the constructor for an instance of this class. It has three optional arguments that, if not specified, can be replaced with calls to the respective methods: set_backend, set_list_name, set_list_directory.
- Parameters
-
All the parameters are optional with this method.
- backend
-
A string representing the DBI backend to be used. (Warning: only "CSV" and "mysql" are supported at this time.)
- list filename
-
A string representing the base filename for the dictionary and the storage file (for the CVS backend).
- list directory
-
A string representing the directory where the list data will be stored.
- Return values
-
A reference to a blessed instance of CGI::Listman.
- Examples
-
-
my $list_manager = CGI::Listman->new; # creates a simple list # manager without any # arguments
-
# creates a list manager by specifying the backend, the filename # and the storage directory my $list_manager = CGI::Listman->new ('CSV', 'userlist', '/var/lib/weblists');
-
set_backend
Defines the DBI backend used to store the list data.
- Parameters
-
- backend
-
A string representing the DBI backend. As noted before only 'CSV' and 'mysql' are currently supported. More will be supported in the future.
- Return values
-
This method returns nothing.
set_list_name
Gives a name to your list.
- Parameters
-
- name
-
A string representing the name of your list, which it turns define the base name for various storage files. The name of the list's dictionary (see CGI::Listman::dictionary) will be deduced from it as well as its CSV "database" file if ever.
- Return values
-
This method returns nothing.
set_list_directory
Defines where the list's dictionary and data files are stored.
- Parameters
-
- directory
-
A string representing the directory where this instance of CGI::Listman will have its data files stored.
- Return values
-
This method returns nothing.
set_table_name
For "real" (i.e. everything except "CSV") database backends, gives the name of the table the list is stored into. If not called, the list name will be used.
dictionary
Obtain the dictionary of this instance (there is only one dictionary for each instance). This method will automatically create and read the list's dictionary for you if needed.
- Parameters
-
This method takes no parameter.
- Return values
-
A reference to an instance of CGI::Listman::dictionary.
seek_line_by_num
Returns the n'th CGI::Listman::line of this instance.
- Parameters
-
- number
-
An integer representing the requested CGI::Listman::line.
- Return values
-
A reference to an instance of CGI::Listman::line.
add_line
Add a CGI::Listman::line (see CGI::Listman::line to this instance's list of lines.
- Parameters
-
- line
-
An instance of CGI::Listman::line to be added to this list manager.
- Return values
-
This method returns nothing.
load_lines
Loads the line from the list database or storage file. This function is deprecated and will probably be removed or made private in a later release.
list_contents
Returns a reference to an ARRAY of the list's lines. This method takes care of preloading the list from the database if needed.
- Parameters
-
This method takes no argument.
- Return values
-
A reference to the ARRAY of CGI::Listman::line of this list manager object.
check_params
This method checks the presence in the hash ref of keys that are marked as mandatory in the instance's dictionary. It returns two ARRAY references, the first of which lists the missing mandatory fields, the second being a list of the fields that are not present in the dictionary.
- Parameters
-
- fields_hashref
-
A reference to a HASH whereof the keys are the names CGI fields.
- Return values
-
- missing_arrayref
-
A reference to an array of mandatory fields (see CGI::Listman::dictionary::term that were missing from parameters_hashref.
- unknown_arrayref
-
A reference to an array of "unknown fields". That is, fields that were part of parameters_hashref but that were not found in the dictionary.
commit
This method commits any changes made to your instance, after which, that instance will be invalidated. As long as it is not called, you can of course apply any modifications to your instance. This limitation will probably be got rid of in a next release.
delete_line
Delete a CGI::Listman::line from this instance's list of lines.
- Parameters
-
An instance of CGI::Listman::line to be removed from this list manager.
- Return values
-
This method returns nothing.
delete_selection
Delete many lines at the same time through the use of a CGI::Listman::selection (see CGI::Listman::selection).
- Parameters
-
An instance of CGI::Listman::selection made of lines to be removed from this list manager.
- Return values
-
This method returns nothing.
AUTHOR
Wolfgang Sourdeau, <Wolfgang@Contre.COM>
COPYRIGHT
Copyright (C) 2002 iScream multimédia <info@iScream.ca>
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
CGI::Listman::line(3) CGI::Listman::exporter(3) CGI::Listman::dictionary(3) CGI::Listman::dictionary::term(3) CGI::Listman::selection(3)
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 848:
Non-ASCII character seen before =encoding in 'multimédia'. Assuming CP1252