=head1 RFC - The Road To Multiple Fields (OUTDATED)

=head1 History of the document

This document served as the blue print for the Arbitrary Subscriber Fields feature. 


It is currently outdated, but is still in the documentation for B<historical purposes>. Do not use it as a guide 
to the multiple fields feature in any version of Dada Mail. 


=head1 General Overview

The multiple fields feature will most likely mean that the modules in the DADA::MailingList::Subscribers namespace will be totally rewritten. 

This also means that all code that uses the DADA::MailingList::Subscribers namespace will have to be rewritten. 

=head2 Subtractive Changes

=head3 Removal of the PlainText Backend

Multiple Fields will most likely require the use of the SQL backend, either in Postgres of MySQL. It's my hope that both backends will be worked on at one time and most of the code will be able to be shared between these two SQL backends (as it currently is now) 

This isn't to say there will B<never> be a PlainText backend for subscribers again, but it does mean that it isn't a target we're going to initially hit. 

Because of this, the many limitations that the PlainText backend currently has (ahem: no multiple fields for one!) won't have to be addressed by limiting what can happen with the SQL backend. Currently, the features of each backend, PlainText, MySQL and Postgres are essentially the same. 

=head2 SQL representation of subscriber fields

I propose that there be two tables associated with the subscription backend, one table holding the basic information about the subscriber, the second holding the various user-defined fields for each subscriber. 

The various rows in the first table may look something like this: 

 UID     list list_type email_address   password    admin_privileges    moderator_privileges  (etc) 

B<UID> is the unique identifier for this specific subscription. 

As it stands right now, an email address can be subscribed to more than one list and the subscription details would also be separate. 

B<list> is the specific list the email address is subscribed to. 

B<list_type> is the type of (basically) sublist a subscriber is on. Some clarification will need to be done to see if sublists will control things such as the ability for a specific subscriber to moderator a list, or, if this will be controlled by a separate field in the subscriber table instead. 

For example, in the 2.x model of Dada Mail, a moderator would have to be a subscriber in a separate, "moderators" list, which would  be completely seperate from the actual subscriber list. 

In 3.x (which we'll say is the version that multiple fields will make an appearance for this paper), moderation may just be another field in our table, that we can turn on or off. 

The other fields, including B<password>, B<admin_privileges>, B<moderator_privileges> would hold meta-information about the subscriber. These fields are all just examples of what could be there. 

B<password> may be a field that holds a user-defined password, so that a subscriber can essentially log into their own administration panel to add/change/delete individual information about themselves, without needing the intevention of the list owner. 

B<admin_privileges> may be a column that when set to a true value, allows the subscriber to have administration privileges and access to the actual list control panel. 

B<moderator_privileges> (like we were talking about), may be set to a true value to allow this subscriber to approve messages sent to a discussion list. 

Obviously, the amount of different columns is fairly elastic, where different features may call for the need to create new columns. 

A question may be asked - should this elastic information be in its own table - thoughts? 

The second table will hold the user-defined fields, for example: 

    First_Name Last_Name Favorite_Color Birthday Zip_Code

Each of these fields may denote something that could be important for the current list owner to collect.  For example, perhaps they want to personalize an email message. They could write: 

 Dear [First_Name]
 
 It seems that it is your birthday! Happy birthday!
 
 _ Your Friend The Mailing List

Dada Mail could also allow you to send this message to people who's birthday it actually is that day and also allow you to send this birthday notice daily. 

It's still up in the air how much information is known about each field. For example, for the, "Zip_Code" field, you may want it able to only collect zip codes. This would mean that you would use a specific SQL type of column field and also, perhaps have a different table describing that field, or a different table where you can store all your fields' meta information. 

If the amount of information about each field is quite large, it would make sense to make a new table that simple holds the meta-information about the field itself. Some things that might be nice to know about the fields are: 

=over

=item * Name

The label of the field itself It B<Would> be nice to have this fairly free form, so if I want to name my field, "First Name" I can, and not just, B<FirstName> or, B<First_Name> or whatever

=item * Constraints 

Constraints would hold what kind of information the field can accept. This could be somewhat taken care of by SQL, by actually stating the type of data that can be added, but SQL has this interesting habit sometimes of failing without an error - especially when adding data that's too long for a certain fieldtype. 

constraints could be labels of a few already-defined Perl subroutines that hold how actually to validate the information. I'm thinking specifically on how Data::FormValidator does things: 

http://search.cpan.org/~markstos/Data-FormValidator/lib/Data/FormValidator.pm

It would make sense to use such a package instead of making our own wheel. 

Constraints could be something like, 

=over

=item * zipcode

=item * phone_number

=item * state

=back

Ect. 

If you don't like how we're defining the contraints, you can simply make your own version. 


=item * Form Widget

It may be nice to state what sort of Form Widget you'd like to use to input the field information, things like: 

=over

=item * TextArea

=item * Text

=item * state_popup_meny

=item * password

=back

The actual HTML code for any of these widgets could be simply HTML::Template templates, which, if you don't like what we ship, you can make your own! 

=back



=head2 Perl module namespace

Roughly, these two tables would be described via two perl modules (or three, if we decide to have each field be more smart about things)

 DADA::MailingList::Subscribers

 DADA::MailingList::Subscriber::Fields

 DADA::MailingLits::Subscriber::Fields::Types
 
=head2 Perl Module API

Hopefully, the API for all this would be simple. For example: 


 # Make a new subscriber object
 my $sh = DADA::MailingList::Subscribers->new({ -list => 'mylist' }); 
 
 # Add a new subscriber! 
 $sh->add_subscriber(
                     { -email_address => 'me@example.com', 
                       -list_type     => 'list', 
                       -password      => 'abcdwxyz', 
                       -fields => { 
                            First_Name     => 'Sal' ,
                            Last_Name      => 'Barbier', 
                            Zip_Code       => '900212', 
                            Favorite_Color => 'Blue', 
                            Birthday       => '4/19/81', 
                            
                      }
 
                    }); 

Hopefully, the API for validating that a subscriber is valid would be as similar to actually removing them as possible: 

    my($is_valid, $problems) = validate_subscription(
                                                { -email_address => 'me@example.com', 
                                                  -list_type     => 'list', 
                                                  -password      => 'abcdwxyz', 
                                                   -fields => { 
                                                        First_Name     => 'Sal' ,
                                                        Last_Name      => 'Barbier', 
                                                        Zip_Code       => '900212', 
                                                        Favorite_Color => 'Blue', 
                                                        Birthday       => '4/19/81', 
                                                   }
                                                  }
                                                ); 

Removing would be as simple: 

    my($is_valid, $problmes) = remove_subscriber(
                                                { -email_address => 'me@example.com', 
                                                  -list_type     => 'list', 
                                                }
                                                ); 

Changing information follows the pattern: 

 # Add a new subscriber! 
 $sh->edit_subscriber(
                     { -email_address => 'me@example.com', 
                       -list_type     => 'list', 
                       
                       -fields => { 
                            First_Name     => 'Salvador' ,
                      }
 
                    }); 

=head2 Subscribing an Individual Email Address w/multiple fields

From a user's perspective, it seems the system would be fairly similar to what it is now (with just one field for the email address). 

I forsee two ways this could be done: 

The form will look exactly as it does now, one field to input your email address, 

When this form is submitted, the user will then see a form with the rest of the fields to be filled out. 

This form is submitted and (if needed) a confirmation email will be sent out. 

The confirmation email itself will be slightly different, most likely - and this is a vast improvement over the current system, the cofirmation email will be completely unique, something like: 

 http://example.com/cgi-bin/dada/mail.cgi?verify=sdfa982nm3232dfs0090asdf
 
or so. 

This verification credentials will only work exactly once. Currently the email/pin system can be figured out fairly easily and isn't very secure. 


The actual information being submitted would be stored in a temporary location - perhaps even a different sublist in the subscriber database, so that when a subscriber confirms a subscription, this information would be simple copied over to the, "Subscription" list. 

The second scenario is similar to the first, except the user is given the entire form at once. 

=head2 Subscribing multiple email addresses at once (administrative) 

From the administrative point of view, I don't see why a similar form could be presented to the list owner, if she would like to subscribe B<one> email address at a time, but for more than one address at a time, it would probably behoove everyone if there was a more economical system. 

That system will most likely be by submitting a Comma Separated Values document to Dada  Mail that reflects the same fields that are saved in Dada Mail's two tables. 

The CVS file will have to be somewhat of a hybrid of the two tables, but it shouldn't be too too hard to figure out. 

Exporting the subscription list would be done in a similar fashion with a CSV file. 


Since Submitted thousands of subscriptions at once is resource-intensive, Dada Mail will probably need to be able to only work with a small part of any submitted information at a time, to avoid browser timeouts and the like. 

