Email

Xataface Email Module

The Xataface Email module allows you to convert your database into a mailing list so that you can easily send email to any found set of records, as long as the records contain an email address to send to.

Features

• Send email to any found set.
• Mail merge macros
• HTML Email support (uses NicEdit WYSIWYG editor for email editing).
• Opt out support (allows recipients to opt out of your mailing list).

Requirements

• Xataface 1.0+
• MySQL 4.1+
• PHP 5+

Download

https://sourceforge.net/project/platformdownload.php?group_id=253820

Installation

1. Download and extract Email directory so that it is located inside the xataface/modules directory (i.e. xataface/modules/Email)
2. Add the following to the [_modules] section of your application's conf.ini file:

   modules_Email="modules/Email/Email.php"

3. Configure the [email] action in your application's actions.ini file. See the section called 'Configuration' for configuration details.
4. Add a line to your crontab file to send out pending email periodically. The line should look like:

   * * * * * /usr/bin/php <cronpath> <indexpath> <indexurl> mail
   
   where <cronpath> is the absolute path to the cron.php script.
         <indexpath> is the absolute path to your application's index.php script.
         <indexurl> is the absolute url to your application's index.php script.
           
   For example:
   
   * * * * * /usr/bin/php /var/www/xataface/modules/Email/cron.php         /var/www/myapp/index.php         http://example.com/myapp/index.php         mail

   If you want to see what this line should be like for your server, you can simply point your browser to the email_install action of your application (i.e. http://example.com/yourapp/index.php?-action=email_install) and it will generate this line to copy and paste into your crontab. Note that the /usr/bin/php portion of this line may vary according to your environment. It represents the path to your PHP binary.
5. That's it! You're ready to send email. See the Usage section to see how to send email from your application.

Configuration

Though the email action may work out of the box, you will likely have to configure it to work the way you want. Some examples of things you will want to configure include:

1. Limit the email action to only be available for certain tables.
2. Apply permissions to the action so that only administrators can send email.
3. Set the name of the column that contains email address (default is 'email').
4. Change the name of the table that is used to store sent email messages.

Overriding the [email] action

The first thing you need to do to configure the email action is override it in your appliation's actions.ini file. You can do this by adding the following to your actions.ini file:

[email > email]

Now any directives you add in this section will override the email action.

Examples:

Limiting email action to certain tables

In your appliation's actions.ini file:

        
[email > email]
    condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'"

Limiting email action by permission

By default your users require the email permission in order to have access to the email form. This permission is not included with any roles by default so you'll need to extend any roles that you want to have access to the email access and explicitly add the email permission. The exception to this rule is if you have assigned your users the Dataface_PermissionsTool::ALL() permissions in your getPermissions() method.

Suppose you want the READ ONLY role to have access to the email action, you could add the following to your application's permissions.ini file:

[READ ONLY extends READ ONLY]
     email=1

Changing the name of the email address column

By default, the Email module will try to guess which column contains the email address for a table. Generally it looks for a column named email. You can override this setting to explicitly tell the module which column contains the email address by overriding the email_column directive of the email action in your application's actions.ini file:

[email > email]
    email_column = "emailAddress"

=Changing the name of the table that stores the sent email

Xataface automatically stores each sent email for your records. By default it stores these emails in a table named newsletters. You can override this table name with the email_table directive in your application's actions.ini file. This table will be automatically created by Xataface when email is sent out.

[email > email]
    email_table = "newsletters"

Altogether

[email > email]
    condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'"
    permission=email
    email_column = "emailAddress"
    email_table = "newsletters"

Usage:

Sending Email to All Records of a Table

1. Navigate to a table for which your email module is enabled, and click on the list tab.
2. Click on the "Email" icon in the upper right corner. This should display an email form.
3. Fill in the email form and press Save.
   
4. You should receive a message saying that the email has been queued for delivery. Your cron script will automatically begin sending emails the next time around. So make sure that you have yoru cron script set up properly.

Opting Out of the Email List

If you have received an email that was sent via the email module you can easily opt out of the mailing list by clicking on the link at the end of the email. This link will bring you to a webpage that asks you to confirm that you no longer wish to receive email from this list.

Using a View to add Email Action to Related Record List

You can simulate a many-to-many relationship in a mysql view by creating a view with all possible combinations.

e.g. If you have a Many to Many relationship between books and authors your relationship from the books table might be something like:

[authors] 
__sql__ = "select * from authors a inner join book_authors ab on a.author_id=ab.author_id where ab.book_id='$book_id'" 

And your relationship from the authors table would be something like:

[books] 
__sql__ = "select * from books b inner join book_authors ab on b.book_id=ab.book_id where ab.author_id='$author_id'" 

Now if our goal was to be able to send email to all authors of a particular book (i.e. send to the authors relationship), we could create a view:

create view book_authors_maillist as 
select * from authors a inner join book_authors ab on a.author_id=ab.author_id 

This view can now be used in xataface like a regular table (if you add a fields.ini file for it and mark the primary key columns). If you wanted to find all authors for a certain book you would just do:

index.php?-action=list&-table=book_authors_maillist&book_id=10

So you could easily create an action in the actions.ini file that would like to the mail action on the book_authors_maillist table with the parameters you wanted.

e.g.

[related_authors_mail] 
    category=related_list_actions 
    url="{$site_href}?-action=email&-table=book_authors_maillist&book_id={$record->val('book_id')}" 
    icon="{$dataface_url}/images/mail_icon.gif" 
    url_condition="$record" 
    condition="$query['-table']=='books' and $query['-relationship'] == 'authors'" 
    permission="email" 

This action would send mail to only the authors related to the current books. It would be made available in the icons in the upper right on the related list view of only the authors of a book.

Mail Merge

The 'Embed Macro' shown above the email form lists the fields which may be included in the email.

Say you have a field called 'email_firstname'. You would type this into the message area like this: %email_firstname%

When the email is sent, this is substituted for the record of that recipient.

Eg. Dear %email_firstname% would be received by email as Dear Tom

If the particular record of the field you are merging is blank, then (in this case) the first name will not be shown.