DADA::MailingList::Settings

- NAME
- SYNOPSIS
- DESCRIPTION

- Mailing List Settings Model
- Default Values of List Settings

- Public Methods

- Initializing
- new
- Getting/Setting Mailing List Paramaters
- get

- Diagnostics

- save

- Diagnostics

- param

- Diagnostics

- params
- A note about param and params

- BUGS AND LIMITATIONS
- COPYRIGHT

# NAME

    DADA::MailingList::Subscribers - API for the Dada Mailing List Settings

# SYNOPSIS

     # Import
     use DADA::MailingList::Settings;

     # Create a new object
      my $ls = DADA::MailingList::Settings->new(
                            {
                                            -list => $list,
                                    }
                            );

            # A hashref of all settings
            my $li = $ls->get;
            print $li->{list_name};

            # Save a setting
            $ls->save(
                    {
                            list_name => "my list",
                    }
            )

      # get one setting
      print $ls->param('list_name');

     #save one setting:
     $ls->param('list_name', "My List");

     # Another way to get all settings
     my $li = $ls->params;

# DESCRIPTION

This module represents the API for Dada Mail's List Settings. Each DADA::MailingList::Settings object represents ONE list.

Dada Mail's list settings are basically the saved values and preferences that make up the, ``what'' of your Dada Mail list. The settings hold things like the name of your list, the description, as well as things like email sending options.

## Mailing List Settings Model

Settings are saved in a key/value pair, as originally, the backend for all this was a dn file - and still is, for the default backend. This module basically manipulates that key/value hash. Very simple.

## Default Values of List Settings

The default value of ALL list settings are saved currently in the Config.pm file, in the variable, `%LIST_SETUP_DEFAULTS`

This module will make sure you will not attempt to save an unknown list setting in the `save` method, as well when calling `param` with either one or two arguments.

The error will be fatal. This may seem rash, but many bugs surface just because of trying to use a list setting that does not actually exist.

The `get` method is NOT guaranteed to give back valid list settings! This is a known issue and may be fixed later, after backwards-compatibility problems are assessed.

# Public Methods

Below are the list of Public methods that we recommend using when manipulating the Dada Mail List Settings:

## Initializing

## new

     my $ls = DADA::MailingList::Settings->new({-list => 'mylist'});

`new` requires you to pass a listshortname in, `-list`. If you don't, your script will die.

A `DADA::MailingList::Settings` object will be returned.

## Getting/Setting Mailing List Paramaters

## get

     my $li = $ls->get;

There are no public paramaters that we suggest passing to this method.

This method returns a hashref that contains each and every key/value pair of settings associated with the mailing list you're working with.

This method will grab a fresh copy of the list settings from whatever backend is being used. Because of this, we suggest that instead of using this method, you use the, `param` or `params` method, which has caching of this information.

### Diagnostics

None, really.

## save

     $ls->save({list_name => 'my new list name'});

`save` accepts a hashref as a paramater. The hashref should contain key/value pairs of list settings you'd like to change. All key/values passed will re-write any options saved. There is no validation of the information you passed.

DO NOT pass, list as one of the key/value pairs. The method will return an error.

This method is most convenient when you have many list settings you'd like saved at one time. See the, `param` method if all you want to do is save one list setting paramater.

Returns 1 on success.

### Diagnostics

- Attempt to save a unregistered setting -

  The actual settings you attempt to save have to actually exist. Make sure the names (keys) of your the list settings you're attempting to pass are valid.

## param

     # Get a Value
     $ls->param('list_name');

     # Save a Value
     $ls->param('list_name', 'my new list name');

`param` can be used to get and save a list setting paramater.

Call `param` with one argument to receive the value of the name of the setting you're passing.

Call `param` with two arguments - the first being the name of the setting, the second being the value you'd like to save.

`param` is something of a wrapper around the `get` method, but we suggest using `param` over, `get` as, `param` checks the validity of the list setting name that you pass, as well as caching information you've already fetched from the backend.

### Diagnostics

- You MUST pass a name as the first argument!

  You cannot call, `param` without an argument. That first argument needs to be the name of the list setting you want to get/set.

- Cannot call `param()` on unknown setting.

  If you do call `param` with 2 arguments, the first argument has to be the name of a setting tha actual exists.

For the two argument version of calling this method, also see the, Diagnostics section of the, `save` method.

## params

            my $li = $ls->params;

Takes no arguments.

Returns the exact same thing as the, `get` method, except does caching of any information fetched from the backend. Because of this, it's suggested that you use `params`, instead of, `get` whenever you can.

## A note about param and params

The name, `param` and, `params` is taken from the CGI.pm module:

Many different modules support passing paramater values to their own methods, as a sort of shortcut. We had this in mind, but we haven't used or tested how compatible this idea is. When and if we do, we'll update the documentation to reflect this.

# BUGS AND LIMITATIONS

# COPYRIGHT

Copyright (c) 1999-2008 Justin Simoni 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.