The Dada Mail Libraries API (Introduction)
- The Dada Mail Libraries API
The Dada Mail Libraries API
Dada Mail's API and library design/structure has been created extremely piecemeal through it's almost ten year history of being a program. Dada Mail started out as a 90k single CGI perl script, but is now composed of more than 200 different libraries and many, many CPAN dependencies. As features were added, so has the API been enlarged. A, "Grand Scheme" has never been made of how Dada Mail was to be designed, but the growth of the API is much more akin to a city, or other organic organism.
This doc is to help give you a birds eye view of the API and describe which modules do what. We understand that not all modules may be covered.
DADA::App namespace holds a mish-mash of modules that make up the program's behaviour, which doesn't fit in anywhere else. Very quickly:
Used to manage the, "Bounce Score Card" for the bounce handler
A wrapper around
DBI for SQL database access
Displays pretty HTML error screens
The main templating system for email messages. Also see
This module is used as a base for the majority of Dada Mail's DB File support.
This module is most likely the oldest module in Dada Mail and is the dump of utility subroutines. If you're looking at how to validate an email address, it's in here (for example)
Stores the GPL for easy access
Contains dead-simple search of plain text files.
Subroutines in this module are subroutines that used to live in the
mail.cgi file, but were taken out, due to being complicated and large. It's hoped that doing so would speed up execution of the
Holds subroutines for often used email messages, like the confirmation message. Also has a high-level subroutine for creating email messages, to be passed to,
A wrapper around,
MIME::Lite::HTML that fixes a lot of annoyances.
A wrapper around
Mail::POP3Client and provides the majority of POP3 access and support in Dada Mail.
Gives caching support for HTML screens in Dada Mail
Session/State management for access to the list control panel. See,
DADA::Profile::Session for session/state management of Dada Mail Profiles. Both this and that other module are mostly wrappers around
Holds extremely high level subroutines to work directly with Dada Mail's subscription and unsubscription system. Extremely useful. API is a little tricky.
Holds the default configuration of Dada Mail. Must be customized when Dada Mail is installed, but hopefully minimally. It's better to save customizations in an installation in an outside configuration file. In Dada Mail, this is the,
DADA::Mail::Send is used to send out messages, both individually and to an entire mailing list. It's very convoluted and contains extremely large dragons. It also works pretty well, but isn't a pearl of coding aestheticism.
It's main job is to send mail, as the name suggests. For messages to an entire mailing list, its uses
DADA::Mail::MailOut extremely closely.
DADA::Mail::MailOut is used to manage and monitor sending a Mailing List Message. A Mailing List Message goes to (primarily) an entire mailing list full of subscribers. When a Mailing List Message is sent out a ton of meta information is created about the actual sending of the message, everything from a copy of the original message, to information about where the sending process is, how long its taken, if the message has been paused, etc. It's fairly well documented, but still very complicated on the inside. It's not very complicated to use, though. Bugs in this module are very hard to fix.
Although it sounds lofty,
DADA::MailingList.pm is mostly used to create and remove mailing lists. Most of the API for actual mailing lists is in the DADA::MailingList namespace.
This namespace maps out various major components that make up a, "Mailing List" It's one of the oldest namespaces in Dada Mail and also one of the most fractured, given what it has to do. There's no one "mailing list" object to use - each part of a mailing list has to be used separately. This may change, in the future.
DADA::MailingList::Archives handles adding/editing/removing archived messages - messages sent by a mailing list, that are later saved. It also handles searching and various HTML formatting, including RSS/atom feeds. The one module is very monolithic and is due for being chopped up into much more manageable pieces.
DADA::MailingList::Settings namespace works with a mailing list's settings and options. Pretty straightforward.
DADA::MailingList::Subscriber is a recent split from
DADA::MailingList::Subscribers. It's used when you want to work with an individual subscriber, mostly to add/edit/remove/copy one subscriber on one list.
Holds validation routines to make sure the subscriber is allowed to subscribe. It's API is also not used directly by Dada Mail (yet), but probably used via the older,
DADA::MailingList::Subscribers is generally used when you want to work with all of the subscribers of a mailing list. This could involve adding/editing/removing en-mass and its methods are optimized for more than one action at a time.
Its methods also have indirect access to Dada Mail Profile information, as well as a backwards-compatibility with the new
DADA::MailingList::Subscriber namespace, as most of the code of Dada Mail deosn't actually work with
DADA::MailingList::Subscriber directly yet.
The modules that comprise the
DADA::Profile namespace are some of the newest in the API. They comprise the API for Dada's, "Profiles", which are very much separate from Mailing Lists.
A Profile in Dada Mail holds meta information about an email address, which may be subscribed to one or many Dada Mail mailing lists.
Dada Mail Profile Fields, once called, "Profile Fields" holds free-form information tied to a Profile. This information can be anything that's been set by the list owners - things like, Name, Age, City, State - whatever information a list owner may want to capture, other than the email address, when an email address is subscribed to a list.
DADA::Profile::Session is a wrapper (basically) around
CGI::Session and handles the web-based profile control panel session/state handling for profile users themselves to manage their own profiles.
DADA::ProfileFieldsManager is the API to change the design of the Profile Fields that Dada Mail can manage. As well as the fields themselves, it also provides the API for the meta information about the various fields. This meta information is currently very bare-bones, but may be developed further, in the future.
The DADA::Template namespace holds objects for generation of HTML and email messages via (mostly) templates. It's another very old API that's in need of a revision
This is another one of the oldest modules in DADA Mail, it's slowly being deprecated, but still provides subroutines for the main, "List" template, as well as the, "Admin" template. These two templates are used for wrappers around content.
DADA::Template::Widgets, as the name suggests, was first created to hold methods that would be called to return often-used pieces of HTML, like a subscription form, or even smaller things, like a HTML form field that holds a popup menu of all the lists.
It still does that, but it's most important job is as the major templating system for most all of Dada Mail, HTML screens and email messages included. The most important and also most complicated subroutine is,
screen(), which is a very fancy wrapper around what Dada Mail uses for its templating engine:
HTML::Template::Expr. Most every other method in,
DADA::Template::Widgets calls screen to create the HTML, except for certain form fields, which are more easily created by wrapping calls to,
screen() is fairly well documented and worth a look.