ABSTRACT

This class encapsulates mail templates. Mail templates contain text that is mailed to students when he subscribes or unsubscribes to an event; or as a reminder. This text can contain placeholders.

Each event defines which template should be send when a student subscribes, unsubscribes or as a reminder per mail or SMS. The templates are identified by names not referenced by IDs, because there may be up to three versions for a template: for male, female or unknown sex students.

Each template has the following attributes:

ID
An internal ID

Name
A Name. There may be up to 3 versions with different gender for the same name.

Gender
0 for recipient with unknown sex, 1 for male and 2 for female recipients.

Description
A 2 to 255 long ISO-8859-1 string which is used as a memo for admins only. It is never included in a mail, but should be used to explain, where the template should be used.

From
An RFC-822 email address that will be used for the From MIME header.

Subject
A String of 2 to 255 ISO-8859-1 characters. It may contain placeholders which will be translated. This string is converted to plain US-ASCII before it is included in a mail.

Text
A String of 2 to 255 ISO-8859-1 characters. It may contain placeholders which will be translated. It will be send as ISO-8859-1 encoded.


DESCRIPTION

Object Constructor

$template = MailTemplates->find( -id=>Ident );
$template = MailTemplates->find( -name=>Name, -gender=>number );
$template = MailTemplates->find( -name=>Name, -preferred_gender=>number );
$template = MailTemplates->find( -name=>Name );
Returns a mail template. If -name and -gender are specified, only that template will be returned; if it is not found, an empty template will be returned. if -name is specified, any one of the genders may be returned; with an additional -preferred_gender argument the preferred gender can be specified; if it is not found, an other gender may be returned.

$template = MailTemplates->create( );
Returns an empty template, which is not yet stored on the DB. All its values should be defined with an update method call.

$aref = MailTemplates->get_object_list( );
$aref = MailTemplates->get_object_list( -name=>$string );
Returns a reference to an array of mail template objects. Called without arguments the array contains all templates (ordered by name and gender). Called with a -name argument, three templates with that name are returned: ordered by gender. If one of the genders is not defined, an other gender is included in its place. If called with a -name argument, with a name that is not found on the DB, a reference to an empty array is returned.

$aref = MailTemplates->get_id_list( );
returns a (reference to a) list of all IDs of mail templates; unsorted.

$aref = MailTemplates->get_id_list( );
returns a (reference to a) list of three idents of templates, where the position in the array corresponds to the gender of the template. If a gender does not exist on the DB, its place will be undef.

Object Accessor Methods

The following methods return the current state of a user object:

$string = $template->id;
$string = $template->name;
$string = $template->gender;
$string = $template->from;
$string = $template->subject;
$string = $template->text;

Actions

$emsg = MailTemplates->send_template( -subscription=>..., -template_type=>...)
$emsg = MailTemplates->send_template( -subscription=>..., -template_type=>..., -to=>$email)
Mails a template. A subscription references an event, where there are the names of 4 templates which should be used for confirmation of subscription or unsubscription and as reminder per mail or SMS. This method gets the right template (specified by template_type which should be 'subscribe_mail', 'unsubscribe_mail', 'reminder' or 'blocked'. In case of 'reminder' the subscriptions field reminder_by decides if the reminder_mail or reminder_sms field of the event will be used.

The -to=> argument can be used to specify where the mail should be addressed to. A default is taken from the subscription (mail of subscribers validation or, in case of -template_type=>'reminder', from reminder_to.

$emsg = MailTemplates->send_template( -subscription=>..., -template_name=>...)
$emsg = MailTemplates->send_template( -subscription=>..., -template_name=>..., -to=>$email)
Mails the template named -template_name=>... (not a template of a given type). The -to=> argument can be used to specify where the mail should be addressed to. A default is taken from the subscription (mail of the subscribers validation).

Object Modifier Method

($field, $errmsg) = $user->update( ... )
Updates the mail template (object state and data base permanent storage). Before any data is changed, all values are checked. If a check fails, the update will not change any data but return a list of two values: the name of the field and an error message. If all checks are ok, the update method will change the objects state in memory and on the VIP database and return undef. What will be updated is determinated by arguments as follows:
-name=>$iso_string
ISO-8859-1 string. 2 to 255 characters long. Identification.

-gender=>0
-gender=>1
-gender=>2
To each name, there should be three gender versions: 0 for unknown sex, 1 for male and 2 for female recepients.

descrition=>$iso_string
ISO-8859-1 string. 2 to 255 characters long. Never mailed, but used as help text for admins, i.e. what is this template used for.

-from=>$rfc_822_email
-subject=>$iso_8859-1_string
Maay be 2 to 255 ISO-8859-1 characters. Can contain place holders.

-text=>$iso_8859-1_string
Maay be 2 to 1 MB ISO-8859-1 characters. Can contain place holders.


SEE ALSO

Events.pm


COPYRIGHT

Copyright 2005-2014 Thedi gerber@id.ethz.ch