Dada Mail 5.x to Dada Mail 6.x Guide
- Dada Mail 5 to Dada Mail 6 Upgrade Guide
- Towards a new web framework
- Database Schema
- Perl Version Requirements
- Config.pm documentation removed
- .dada_config file
- Removed variables: $FILES, $TEMPLATES, $TMP, $BACKUPS, $ARCHIVES, $LOGS
- Added variable: $BACKEND_DB_TYPE; Removed variables: $SUBSCRIBER_DB_TYPE, $ARCHIVE_DB_TYPE, $SETTINGS_DB_TYPE, $SESSION_DB_TYPE, $BOUNCE_SCORECARD_DB_TYPE, $CLICKTHROUGH_DB_TYPE
- %SQL_PARAMS: removed table names
- Database Connection, Bounce Handler POP3 Connection Testers
- Installer can now grab information from the previous installation
- Template Changes
- "templates" directory move
- Plugins: Templated out
- Migration from Prototype/Scriptaculous to jQuery/jQueryUI
- Static Files directory location, $SUPPORT_FILES config variable, Installation and Configuration
- Clickthrough/Message Opens, etc tracking support dropped for Default Backend
- List Control Panel
- Admin Menu
- List Control Panel Screens
- Mass Mailing >> Send a Message
- Membership >> View
- Membership >> Recent Activity
- WYSIWYG editors and Template Tags
- Data Cache
- Bounce Handler
- Scheduled Mailings - DEPRECATED
- dada_digest.pl - REMOVED
Dada Mail 5 to Dada Mail 6 Upgrade Guide
The focus of this major release of Dada Mail is to make room for growth of the app, by creating a better foundation for future features.
Dada Mail's UI/UX has been migrated to jQuery, from Prototype, where development has all but ceased.
Towards a new web framework
For most people, there are no changes in any of the database schemas between Dada Mail 5 and Dada Mail 6. If you are using the PostgreSQL backend, do note that the dada_sessions table is slightly different. You will want to
DROP the current dada_sessions table you have, and recreate the table:
CREATE TABLE dada_sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a_session BYTEA NOT NULL );
Again, this is only for PostgreSQL.
Upgrading is fairly straightforward, with no need for any Dada Mail 5 to Dada Mail 6 SQL upgrade scripts.
When using the Dada Mail Installer (which you should use, when installing or upgrading), you will definitely want to create a new
.dada_config file, when asked.
There is one new config variable,
$SUPPORT_FILES that needs to be set up correctly. If you do not make a new
.dada_config file, or install manually, without putting in this new variable, the upgrade will not work.
Perl Version Requirements
This is currently no change in the Perl Version requirement of v5.8.1. This may change, before a stable release of v6 is released, most likely to v5.10.x of Perl. We're still working on that.
Config.pm documentation removed
Documentation that was in the Config.pm has been cleaned up, revised, updated and moved to the, dada/extras/documentation/pod_source/global_variables.pod file.
.dada_config file that's generated by the included installer has undergone a few changes.
Removed variables: $FILES, $TEMPLATES, $TMP, $BACKUPS, $ARCHIVES, $LOGS
These variables were added to the
.dada_config file, but are almost kept the same as the default, ala:
$FILES = $DIR . '/.lists'; $TEMPLATES = $DIR . '/.templates'; $TMP = $DIR . '/.tmp'; $BACKUPS = $DIR . '/.backups'; $ARCHIVES = $DIR . '/.archives'; $LOGS = $DIR . '/.logs';
Instead of taking up extra space and line noise, these files are simply added to the
dada/DADA/Config.pm file as the default. You may still add these variables in the
.dada_config file to change their default, but it's not really recommended. The,
$DIR variable has been added to the
dada/DADA/Config.pm as a true config variable, so you do not want to have the first line read,
my $DIR = '/home/account/.dada_files';
$DIR = '/home/account/.dada_files';
Will be fine. Keeping,
my will probably break things.
Added variable: $BACKEND_DB_TYPE; Removed variables: $SUBSCRIBER_DB_TYPE, $ARCHIVE_DB_TYPE, $SETTINGS_DB_TYPE, $SESSION_DB_TYPE, $BOUNCE_SCORECARD_DB_TYPE, $CLICKTHROUGH_DB_TYPE
For the SQL backend, all these variables are already set the same, ala:
$SUBSCRIBER_DB_TYPE = 'SQL'; $ARCHIVE_DB_TYPE = 'SQL'; $SETTINGS_DB_TYPE = 'SQL'; $SESSION_DB_TYPE = 'SQL'; $BOUNCE_SCORECARD_DB_TYPE = 'SQL'; $CLICKTHROUGH_DB_TYPE = 'SQL';
For the Default backend, they're set like this:
$SUBSCRIBER_DB_TYPE = 'PlainText'; $ARCHIVE_DB_TYPE = 'Db'; $SETTINGS_DB_TYPE = 'Db'; $SESSION_DB_TYPE = 'Db'; $BOUNCE_SCORECARD_DB_TYPE = 'Db'; $CLICKTHROUGH_DB_TYPE = 'Db';
To reduce line noise,
$BACKEND_DB_TYPE is being introduced. If set to,
SQL, it'll set the other variables accordingly. Same with setting this variable to,
%SQL_PARAMS: removed table names
Remove to further lesson the line noise.
Database Connection, Bounce Handler POP3 Connection Testers
The installer now has inline testers for both your Database Connection, and the Bounce Handler's POP3 Connection, to help you make sure these work, before committing to an installation.
Installer can now grab information from the previous installation
When using the installer to upgrade a current Dada Mail, it'll able to grab some of the configuration information from your previous installation: Program URL, Support Files Directory, Dada Mail Root Password, Backend Options, Plugin/Extensions that were previously installed, and your WYSIWYG options.
(If you added additional configuration variables after an install has completed, you will still have to re-add these manually)
This can help save time during an upgrade and ensure that everything goes smoothly. You can also re-enable the installer, after a successful initial installation, to change your Dada Mail configuration - for example: add/remove a plugin.
"templates" directory move
In v5, template files lived in the directory:
They are now located in:
It's hoped that this directory move will make it easier for people to find the
templates directory. This directory is still in the,
dada directory, instead of, say, the,
static directory since template files are themselves little, simply programs, that need to be interpreted, and aren't themselves actually static.
Plugins: Templated out
There was a voluminous amount of inline HTML in the plugins/extensions that are shipped with Dada Mail. This HTML is now saved in separate template files, which you can find in,
Each plugin has its own directory for its templates, eg: dada/templates/plugins/tracker, etc.
The Scheduled Mailings plugin still has program generated and inline HTML. It's a big mess.
This change should help performance of the app. These files are also not cached in Dada Mail's Screen Cache, as they're going to be served faster by the webserver simply as static files.
Migration from Prototype/Scriptaculous to jQuery/jQueryUI
Static Files directory location, $SUPPORT_FILES config variable, Installation and Configuration
Dada Mail now separates out its static files needed for the app, from the dynamic template files. These static files ship with the app under the directory,
In previous versions of Dada Mail, these files were served via Dada Mail, creating a new running instance of the app per request, which is slow, awkward and confusing.
Both the server path, and URL to this directory will be saved in your
.dada_config file, under the varible,
$SUPPORT_FILES. This variable is required to be correctly configured, for Dada Mail to work.
This does create an additional thing that needs to be configured for Dada Mail to be successfully installed, but we feel this extra step is worth it, for performance and for future features of the app.
Clickthrough/Message Opens, etc tracking support dropped for Default Backend
The Tracker plugin and all of its functionality now requires the use of one of the SQL backends.
List Control Panel
View Subscribers: Shows # of Subscribers
The, "View Subscribers" Admin Menu now shows the number of subscribers you have on the current mailing list you're logged into. This is automatically updated every 5 minutes
Monitor Your Mailings - Auto Updated
The, "Monitor Your Mailings" Admin Menu shows how many mass mailings are going out on the current mailing lsit you're logged into, as well as the total number of mass mailings that are going out. This is now automatically updated every 5 minutes.
List Control Panel Screens
Mass Mailing >> Send a Message
Options for Mass Mailing, including File Attachments, Archive Options, etc have been moved to a tabbed interface.
Membership >> View
Breakdown by Domain Graph
The Breakdown by Domain graph, that used to be in the Tracker plugin has been moved to the Membership - View screen. Clicking on any of the pie slices will perform a search on the domain you have selected.
The Subscriber search form has autocomplete capabilities, which searches and matches on email addresses
Membership >> Recent Activity
Subscription Trends graph
The Recent Activity screen now has a graph labeled, Subscription Trends. This graph shows daily, as well as cumulative data on Subscriptions and Unsubscriptions on your mailing list.
WYSIWYG editors and Template Tags
In version < 6 of Dada Mail, when template tags like,
<!-- tmpl_var list_settings.list_name -->
are entered in the rich text (rather than source view) of the WYSIWYG editor, the "<", and, ">" characters are converted into their HTML entities, so the source of your message now looks like this:
<!-- tmpl_var list_settings.list_name -->
Which breaks the tag, and you will see the original template tag, which will not be converted to its value.
In v6, Dada Mail will look for these types of conversions, and convert them back, fixing the template tag, to be parsed correctly.
Dada Mail now has a data cache, for things like generated JSON files. This data cache can be managed with the new,
DADA::App::DataCache module and can be enabled/disabled using the
$DADA_CACHE config variable. Old cached data will be removed periodically (1 hour), automatically. The data cache is located in the,
directory. The files, as well as the directory itself, may be safely removed at any time.
The Tracker plugin has been essentially rewritten, and its features have been expanded. All charts, graphs and maps generated are now interactive and mousing over various parts of the chart/graph/map will reveal additional information. The UI itself has been redesigned, as well.
The new charts/graphs/maps are powered by the Google Visualization API. Data, in the JSON format is created for Dada Mail using the Perl CPAN module, JSON (http://search.cpan.org/~makamaka/JSON/). This module will need to be installed on your hosting platform for these charts/graphs/maps to be created.
Although not part of the standard Perl Library, the module proves to be so useful, that it's usually already installed on many hosting platforms (like LWP, CGI, etc). Dada Mail will be shipped with a copy of this module, although it will be disabled (enabling just means renaming a file and a directory - covered in the Error FAQ)
Expanded location-based information
As well as country-specific information, Tracker now supports showing information on a city-specific level.
City Reports by IP Address
Reports are now generated per country, breaking down then by city, and then by individual IP address that may have caused an event, (a message open, clickthrough, forward, archive view) and listed in chronological order.
Included City Geo IP Data
Dada Mail now comes with both a country Geo IP database, as well as a city-level Geo IP database. The city-level database is fairly large - ~20 megs., but it's utility is worth its size. Geo IP data is provided by http://maxmind.com, who also provide more accurate country/city data, on a subscription.
The distro of Dada Mail is much larger - around 20 megs. compressed, rather than ~7.5 megs for v5 of Dada Mail. This additional size is mostly from the bundled city-level Geo IP database.
Both the city, and country-level Geo IP databases can be found in the,
An, "open" is recorded, when a, "clickthrough" is recorded when no "open" is previously recorded.
What this means, is this:
Opens are counted when a special embedded image is loaded from the email message you send out. This works well, except when images are not displayed by default by the mail reader, which is often the default for mail readers, or if you're sending out a PlainText message, which does not support embedded images.
To counteract that, Dada Mail supports simply counting a "clickthrough" also as an, "open", if it hasn't also already recorded an open for that specific user, and that specific email message. This is going to lead to a potentially higher - and more accurate open rate in Tracker.
Filename change: dada_bounce_handler.pl to bounce_handler.cgi
Make sure to update any cronjobs, links, etc.
The Bounce Handler Rules, used to match the type of bounced message that gets sent to the bounce handler, has been moved out of the code and into its own file, which you may find at,
You may also copy the file, and place it in your,
directory, make your own changes/customizations, and the Bounce Handler will use your copy, instead of what ships with Dada Mail.
More Rules Added
Over 10 new rules have been added to the Bounce Handler Rules. For the most part, these rules are easy to understand and only match a specific type of bounce, making them easy to modify.
Filename change: dada_bridge.pl to bridge.cgi
Make sure to update any cronjobs, links, etc.
List Email Mail Forwarding Support
You may now set up a List Email as a Mail Forward, that pipes a message directory to Dada Bridge, rather than as a POP3 email account, that is checked on a schedule via a cronjob. This should greatly help any lag between when the message is sent to the List Email address, and when the message is checked by Bridge, and sent out to the entire mailing list.
Clean Up Replies Filter - Disabled
This experimental feature doesn't work very well and has been disabled in v6.
Scheduled Mailings - DEPRECATED
The current scheduled_mailings.pl plugin, as it currently stands, needs a rewrite and isn't currently benefitting from the advances of code style, best practices and techniques offered by the rest of Dada Mail.
Unless rewritten, it will be removed in a future version of Dada Mail.