sfEleAdminEmailPlugin
0.8.0devel
for sf 1.2sf 1.1 MIT
The sfEleAdminEmailPlugin is a tool for managing email templates and sending made by Elevator Company.
Features:
app.yml configuration for setting banner templates, parameters and sending configuration (from, reply-to);- Simple tool for managing email templates;
- Swift_Message extension to provide extra functions to deal with template emails;
- Possibility to send emails in html and text plain format (the email client will decide which to use);
- Administration tool based on
sfAdminGenerator;
- Simple installation.
Requirements:
* For mail sending using the Swift_Mailer extension class you will need the tool Swift_Mailer v4.x. This version provides extra methods that allow the sending of HTML and text in one email.
Developers
License
The MIT License
Copyright (c) 2008 Elevator.cz
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
sfEleAdminEmail plugin
The sfEleAdminEmailPlugin is a symfony plugin that provides a simple tool for email template
administration and also an extension for SwiftMailer message class that allow the sending of
formated templates.
It consists in one module called sfEleAdminEmailTemplate for content administration and one
class sfEleEmailMessage that extends Swift_Message class providing support for templates.
Dependencies
This plugin needs the SwiftMailer 4.x, a library recomended by Symfony developers to deal with mail
sending. The version 4.x is also needed because of support to multiple bodies (in this version you
can send a message in HTML format and also set an alternative message in text plain format to be
read by mail clients that don't support or don't allow HTML).
This plugin also uses TinyMCE in admin module to help user making HTML formated templates.
SwiftMailer Instalation
Download the last 4.x version in SwiftMailer site.
Create the directory lib/vendor/swift in your symfony project.
Copy the SwiftMailer library (/lib folder content) to lib/vendor/swift directory.
To use SwiftMailer you should include the swift_init.php file:
[php]
require_once(sfConfig::get('sf_lib_dir').'/vendor/swift/swift_init.php');
Installation
Install the plugin
$ symfony plugin:install sfEleAdminEmailPlugin
Publish plugin assets (When using pear install on unix, you don't have to follow this step)
$ symfony plugin:publish-assets
Rebuild your model
$ symfony propel:build-model
$ symfony propel:build-sql
$ symfony propel:build-forms
$ symfony propel:build-filters
Update your database tables by starting from scratch (it will delete all the existing tables, then re-create them):
$ symfony propel:insert-sql
or you can just create the new tables by using the generated SQL statements in
data/sql/plugins.sfEleAdminEmailPlugin.lib.model.schema.sql
Set the module enabled in your settings.yml (usually located in /apps/<your_app>/config/settings.yml)
all:
.settings:
enabled_modules: [<your_enabled_modules>, sfEleAdminEmail]Clear your cache
$ symfony cc
Configuration
Before start making email templates in administration module you should define some configuration in you app.yml file.
The basic structure is:
[yml]
all:
sf_ele_admin_email:
template_parameter_prefix: <prefix> # prefix for template parameters
template_parameter_sufix: <sufix> # sufix for template parameters
templates: # list of available email templates
<template_key_1>: # email template key
name: <template_name> # email template name
params: [<available_parameter_1>, <available_parameter_...>] #list of available template parameters
sender: <sender_email> # email used for sending (optional)
<template_key_2>: # you can set as many template as needed
...
mailer_config: #config for mail sending
from: <sender_email> #sender (used if template sender is not set)
reply_to: <reply_to_email> #reply_to (allows array and string)
In this file you have to set prefix and sufix for template parameters. It means that the dynamic parameters you can use while
editing the template should contain the defined prefix and sufix, what will be used for replacing these values when sending
an email.
Under templates are set the available templates, the respective name, parameters and the sender to be used. The parameters
set there are used only for user helping and should be set when sending the email.
Administration Design
Administration is suited to use sf_admin theme (or advanced theme sf_ele_admin)
Using Administration Module
The administration module generates a list of templates based in the app.yml configuration. There you can edit the text and html
body for each templates and use the template parameters set.
sfEleEmailMessage Class
The sfEleEmailMessage class extends the default Swift_Message class used to set email message for sending.
It requires the fields template and also an array with the list of parameters to be replaced in the template body.
The parameters should be an array where the keys are the names of the parameters to be replaced (without the prefix and
sufix set in app.yml).
After setting these fields, the class will generate a message according to template and provided parameters.
Step by step example
Call the mail sending function providing all parameters available.
[php]
//Set the template parameters
$templateParameters = array();
$templateParameters['user_name'] = $user->getName();
$templateParameters['user_email'] = $user->getEmail();
$templateParameters['article_title'] = $article->getTitle();
//Creates a link parameter for the article with absotue path
$templateParameters['article_link'] = $this->generateUrl('article_detail', array('slug', $article->getSlug()), true);
//Include the swift mailer needed files
require_once(sfConfig::get('sf_lib_dir').'/vendor/swift/swift_init.php');
//Create instance of swift transport
$transport = new Swift_SmtpTransport();
//Create instance of swift mailer based on transport
$swiftMailer = new Swift_Mailer($transport);
//Create message by giving the template key and parameters
$message = new SfEleEmailMessage('send_to_friend', $templateParameters);
//Set the 'to'
$message->setTo($friendEmail);
//Send email with the message
$swiftMailer->send($message);
Set app.yml configuration based on this new email template:
all:
sf_ele_admin_email:
template_parameter_prefix: (+
template_parameter_sufix: +)
templates:
send_to_friend:
name: Send to Friend
params: [user_name, user_email, article_title, article_link]
from: sender@company.com
mailer_config:
from: mainsender@company.com
reply_to: mainsender@company.comNow go to administration module sfEleAdminEmailTemplate, it will create automatically a new template for this configuration.
Edit the new template by setting the text content and HTML content (using the template parameters set).
Hi.
Your friend (+user_name+) sent you an interesting article:
- (+article_title+)
To see the entire article, click in the link below:
(+article_link+)
Thanks.
[html]
Hi.<br/>
<p>Your friend <b>(+user_name+)</b> sent you an interesting article:</p>
<p>- (+article_title+)</p>
<p>To see the entire article, click <a href="(+article_link+)">here</a></p>
Thanks.Now your new template is ready for use.
Author
Thyago CLEMENTE 