sfEleAdminEmailPlugin - 0.8.0

Plugin for email templates administration and sending.

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

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.com
  • Now 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