Download the PHP package implico/email-framework without Composer

implico-email-framework

Smarty Template Engine email coding framework. A kind of preprocessor that facilitates daily work with email templates.

Concept & example

When developing an email template, you often face issues such as:

• setting the same (often prehistoric) attributes and css properties across the whole project like:

• using font tag unconveniently
• setting img sizes manually
• having multiple language versions (or other small differences between templates) for one layout
• using same values across whole project (widths etc.) - that could be accessed as variables (and in some cases could also take a default configuration value when not set, like font parameters)

Produced code is often hard to maintain.

The framework brings configured Smarty plugins and CLI interface, so you can develop project like this:

And run the watcher:

The code is converted (may vary according to the actual settings) to:

Installation

To use the framework you need the following software:

• PHP >= 5.5 with openssl and mbstring extensions enabled
• Composer
  • for Windows, use the installer
  • for Linux, install globally
• optionally, if you want to benefit from gulp, i.e. live browser reload on each change with Browsersync, you will need to install: nodejs and of course gulp (the new proper way, by gulp-cli)

PHP installation

• Windows

  1. unpack the downloaded PHP archive (e.g. PHP 5.6.x Non Thread Safe Zip - rather that 7.x) into c:\PHP
  2. add c:\PHP to your PATH environment variable
  3. rename c:\PHP\php.ini-development to php.ini, edit and uncomment:
     • extension_dir = "ext"
     • extension=php_mbstring.dll
     • extension=php_openssl.dll
• Linux - run in the terminal:

Framework installation

1. Open a console/terminal window.

2. Run:

3. Add the Composer's global bin folder to your PATH variable. First, to get the path, run:

   And then:

   • Windows: follow the instructions
   • Linux: edit the /etc/environment file (or /etc/profile if you don't see the PATH definition there) as a root user and restart system
4. You can now start a new project - see the examples section to find out more.

Framework update

CLI

The global executable is named iemail. Run it from your projects dir (e.g. email-projects).

Initialize projects directory

Creates a new projects directory (where your projects will be kept) with specified project_name. Creates _custom subdirectory, with master config file and custom plugins dir.

Options:

• projects_dir_name: directory name

Example:

Initialize new project

Creates a new project with specified project_name. Run it in the directory created with create command.

Contents of the base_project_name are copied into a new directory. First, the script searches for it in the current working directory, then in the core framework samples.

Options:

• base_project_name: enter the name of the base project to copy; defaults to plain

Example (creates test project based on the multilang core example):

Compile project

Compiles project with specified project_name. Options:

• -s (--script): script name(s), if not set - all scripts are compiled
• -d (--dir): projects directory, defaults to current direcotry
• -w (--watch): watch mode - starts watching your project dir and compiles on any change
• -o (--output): output mode - minified (m) or formatted with indentation (f)

Example (compiles and then watches test project for changes):

Send test email(s)

Sends test email(s) for the specified project_name. All images are converted and embedded as cids. SMTP and default options are set in the configuration file.

Options:

• -s (--script): script name, defaults to index
• -d (--dir): projects directory, defaults to projects
• -t (--toaddress): target address(es), defaults to configuration settings (for multiple, use: -t [email protected] -t [email protected])
• -f (--toaddressfn): name of a text file in the project's root directory with target addresses (separated by newline)
• --fromname: from name, defaults to configuration settings
• --fromaddress: from address, defaults to configuration settings
• -u (--subject): email subject, defaults to configuration settings
• -a (--attachments): attaches one or more files from the output directory (for multiple, use: -a file1 -a file2)
• -m (--minified): uses minified script version instead of formatted
• -l (--log): logs addresses into the project's root directory:
  • log-done.txt: addresses to which sending succeeded
  • log-fail.txt: addresses to which sending eventually failed
• -i (--interval): interval in ms between sending each email, defaults to 1000
• --errorstop: quits on error

Example (sends test project to [email protected]):

Gulp integration

The newly initialized project directory comes with package.json and gulpfile.js, allowing you to use the gulp watch and Browsersync live browser reload on each source code change. Technically, the watcher just executes the compiler in a normal way and then refreshes the browser.

For the first run, after using iemail create, enter the new project directory and execute (assuming nodejs and gulp are already installed):

Then you can use a simple gulp api:

Compiles a project and opens a web browser. Then watches the project, compiling and reloading the browser on changes.

Options:

• -p (--project): project name (required)
• -s (--script): script name, defaults to index; if not specified (gulp -p sample -s), all scripts are listed in the browser
• -a (--params): additional parameters passed to the compile command, e.g. gulp -p sample -a ' -om' will produce the minified version (note the leading space)
• -r (--resume): prevents new browser window to be opened

Directory structure

Framework

The framework directory structure overview:

• core: PHP files, Smarty plugins and master config file
• samples: example projects, used also for bootstraping
• vendor: modules installed with Composer

Projects dir

The _custom subdirectory contains optional: custom master config file and your own Smarty plugins - place them in the plugins directory.

Other dirs contain per project files. Each of them has the following structure:

• configs: configuration for the whole project and for particular scripts
• views: view templates:
  • layout.tpl: the main view (layout) file
  • scripts: if you want to have multiple views for one main layout (which differ in language or some details like colors, graphics), place them here; by default, there is only one script: script.tpl; see the Multilang example for use case
• styles: CSS styles (as Smarty templates, so you can e.g. access config variables)
  • layout.tpl: main styles included in your view layout template (you can rename or create new ones)
  • inline.tpl: styles to put inline with CssToInlineStyles (you cannot rename it, but can include other templates from within)
• outputs: compiled project files (HTML); put your images here

Plugin reference

Reference scheme:

Where:

• parameter1 is set to 0
• parameter2 is set to configuration value config_value
• parameter3 is not displayed

Attribute names which are equal to the HTML ones are not camelCase (like cellpadding, bordercolor), others like lineHeight are.

Standard parameters are:

• style: additional CSS style, like border: 1px solid #000;
• id: id attribute
• class: one or more classes separated by space
• attrs: additional HTML attributes, like valign="middle" border="0"

These won't be described in the reference below.

Function plugin has only the start tag, e.g. {margin height=20}, other (block) must have the ending tag, e.g. {table}...{/table}.

Specify width, height, font sizes without units.

Table

Notes:

• maxWidth: sets the max-width style and creates an Outlook-conditional wrapper table

Tr

Td

Notes:

• when using background (image), you will probably want to set a fallback color with bgcolor; note that background images embedded as cids seem not to work with Gmail mobile app (but do work when referencing external URLs)
• backgroundNoRepeat causes the background image to fill all the cell space
• padding: set as a CSS padding property value, e.g. 10px 20px
• noFont: blocks applying font styles even if fontStyleTdTag config value is set to true
• overflow: set to true for hidden (shorthand)

Vertical margin (function)

Creates a row with specified height.

Font

Notes:

• sizeForce: adds !important to CSS font-size property value (useful when you don't want the font to be resized on e.g. mobile Gmail apps)
• bold, italic, underlined, centered: have aliases derived from the first letter; set any truthy value, like {font b=1}
• noWrap adds styles and replaces content white spaces with  

Link

Notes:

• textDecoration: use CSS values for text-decoration property
• buttonHeight: if you want to "buttonize" the link, set its height; you should add sizeForce=true parameter to the {font} used inside this button to prevent font scaling on mobile Gmail apps; you would also probably need to set the button background color on wrapping {td}; see Button plugin for a cross-client solution

Button

Notes:

• creates a Microsoft Outlook-compatible button (based on Bulletproof email buttons)
• centered: refers to centering of the button content, remember to set align="center" for containing {td}
• you can nest markup to obtain font styles, e.g.

Image (function)

Notes:

• autoSize: if true, when width and height is not specified, actual image dimensions are taken
• marginV and marginH: vertical and horizontal margin (setting vspace and hspace attributes + CSS margin)

Force strip

To force white space strip (in the formatted version), use the following syntax: #(strip)[stripped_code]#(/strip)

Configuration

Default settings are defined in the master file core/config.conf. To change them, edit (if they do not exist - create) the following files:

• [projects_dir]/_custom/config.conf: your custom common config applied to all projects
• [projects_dir]/[project_name]/configs/config.conf: config applied to the project
• [projects_dir]/[project_name]/configs/scripts/[script_name].conf: per script config (name it as the script name)

All most recent options are described in the master file. You can change (among others):

• encoding, font defining mode (as a font tag, span and/or in a td cell tag)
• default table and cells attributes, font family/color/size, link and img styles
• sending test email options, such as default subject/target address or SMTP access

Examples

Starting a new project

To create a directory where you will keep your projects, use the create command:

This will create a directory named email-projects with custom config and plugins folder.

Then, go to this directory and run the init command:

By default, the base (copy source) project is the plain sample from the core (unless you create own plain project, then it will be the default for bootstraping). You can specify base project by the second parameter:

If the base project is not found in the current directory, it will be searched in the framework core sample directory.

After initialization, run compiler in watch mode:

Open the script HTML file located in your project outputs directory. Refresh on every compilation to see the changes.

Alternatively, use the more convenient gulp integration guide to watch for changes.

Plain

This is a plain, bootstrap project. Includes only a layout with the main table defined.

Grid

This shows how to build more complex projects, including lists and buttons.

Responsive

Presents the way to build a responsive (in fact - fluid) project. Notes:

• config options tableWidth and tdWidth are set to 100%
• layout template:
  • <meta name="viewport"> is uncommented, primarily for Apple devices that support media queries (see the last media query that limits table width)
  • added Outlook max-width hack as a conditional comment (before and after the main table definition)
  • added max-width to the main table (for e.g. Gmail)
• all width units (tables, cells, images) are set in percentage

Multilang

Multi-language project presents two ways of defining language-specific content for English and Polish. The concept is that the layout template (layout.tpl) is extended by language scripts (see Smarty template inheritance), in this case en.tpl and pl.tpl.

First way is to set script-specific config values in the configs/scripts directory, and then just use it like {#title#}.

Second way is to inject content by using blocks in language scripts.

Integration

To use the framework in your own PHP scripts:

• install it with Composer

• to render an email, first create a Smarty object:

• add plugins dir

  Replace path_to_core_plugins_dir with the actual path, e.g. __DIR__.'/vendor/email-framework/core/plugins/'.

• load config file(s)

• set directories the templates are referring to, like this:

• execute the script and then send it using your favorite library (like PHPMailer or Swift Mailer)

• for PHPMailer, you can embed images as cids using the msgHTML method

Quick tips

• to create a vertical line (<hr>), you can use the following code:

• to create an unordered list, use • entity, e.g.:

• if you have repeated code, take advantage of functions; if the code repeats among projects, you can think about creating own plugins (template functions or block functions)

• set line heights in pixels, rather than percentages or numbers (Outlook will treat it as pixels); if a Gmail mobile app wrongly converts it on small screens, target such more modern clients in the CSS by a media query and apply a patch, e.g.

• to achieve precision (and avoid Outlook bugs in certain cases), define cell paddings by nesting tables, instead of setting CSS padding property

• set a background color on tables, rather than on cells (causes gap lines on iPhones)

TODO

[x] integration with gulp for:

• more optimized watch
• auto-refresh by Browsersync

[ ] use of TinyPNG

[ ] error handling when one of required project subdirectories does not exist

Alternatives

Take a look at other interesting tools and frameworks:

• MJML
• Inky
• Node Email Templates
• some nodeJS modules