DADA::MailingList::Settings
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({
-settings => {
list_name => "my list",
}
});
# save a setting, from a CGI parameter, with a fallback variable:
$ls->save_w_params(
-associate => $q, # our CGI object
-settings => {
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. 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 parameters 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({-settings => {list_name => 'my new list name'}}); save accepts a hashref as a parameter. 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 parameter.
Returns 1 on success.
save_w_params
$ls->save_w_params(
-associate => $q, # our CGI object
-settings => {
list_name => 'My List',
}
); save_w_params allows you to save list settings that are passed in a compatible Perl object (one that has a param method, similar to CGI.pm's)
save_w_params also allows you to pass a fallback value of the list settings you want to save.
-associate should hold a Perl Object with the compatable, param method (like CGI.pm's param method. required
-settings should hold a hashref of the fallback values for each list setting you want to save.
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 parameter.
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,
paramwithout 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
paramwith 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 parameter 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 - 2023 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.