digest_email 1.0.1

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Peter Hamilton
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,137 @@
+# DigestEmail
+
+This is a project put together in a weekend by [Peter Hamilton](http://peterhamilton.github.com).
+The overall aim was to simplify the process of generating weekly Computing Society emails for students.
+
+There were several reasons for making this gem:
+- **Fun** - It's not often I have time to make side projects right now. This was a nice non-uni related hack
+- **Learning** - I wanted to do several things - learn more about TDD, create a command line ruby gem etc. This seemed like a great opportunity to tick the boxes
+- **Consistency** - Currently everyone provides their digest info in random formats all over the place. Now they can provide the yaml config for their digest entry and I can just combine them all and generate a digest email
+- **Legacy** - I wanted something future society members could use and improve on
+
+The result is a gem which turns [this](https://gist.github.com/4092848) into [this](http://docsoc.s3.amazonaws.com/sample/sample_digest_email.html)
+
+## Background
+  I'm responsible for collating together around 4-6 notices which need to go out to our students each week for jobs, clubs, meetings and events. I currently have to write raw HTML for each email which involves a lot of Copy-Paste and inline styles and this weekend I decided to find a way to automate the process.
+
+  I just collated and generated this weeks digest using this method and it's gone from taking **2 hours** down to **5 minutes**. I'd call that a success.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'digest_email'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install digest_email
+
+## Usage
+
+### 1. Write a digest file
+I name mine something like 2012-01-01.yml.
+
+A digest file must consist of 3 main sections, a header, items and a footer.
+
+- Header
+Must contain:
+  - `title` - The main digest title
+  - `subtitle` - Optional
+  - `subsubtitle` - Optional
+
+- Items
+Contains a list of items, each of which must contain:
+
+    - `list_title` - The title which appears in the digest summary at the top
+    - `image` - A full url to a hosted image (150px wide recommended)
+    - `title` - The title for the item
+    - `body` - The body for the item
+
+Fields are parsed as markdown using [Maruku](https://github.com/bhollis/maruku) so the body can be easily customised
+
+- Footer
+Must contain:
+  - `signature` - Will be aligned to the right e.g. "DocSoc 2012/2013"
+  - `sponsors_image` - A 600px wide hosted image for the bottom of the email
+
+See below for a full example, also available as a [github gist](https://gist.github.com/4092848)
+```yaml
+# sample_digest_email.yml
+# Parses with the digest_email (http://peterhamilton.github.com/digest_email) gem
+# See the result of running this file through the gem here: http://docsoc.s3.amazonaws.com/sample/sample_digest_email.html
+header:
+  title: "Weekly Digest"
+  subtitle: November 12th 2012
+  subsubtitle:
+
+items:
+    - list_title: New, Easy Email Digests
+      image: https://s3-eu-west-1.amazonaws.com/docsoc/sample/suitcase.jpg
+      title: We have nice simple email digests!
+      body: |
+        This is an example of a simple digest item.
+        In this example it might be for a potential industry placement - for example, check out the rather nice suitcase image on the left
+
+    - list_title: Robotics Hackathon
+      image: https://s3-eu-west-1.amazonaws.com/docsoc/sample/walle.jpg
+      title: These aren't the droids you're looking for...
+      body: |
+        Another sample sigest item. This one is all about a fantasy hackathon!
+
+        For more details contact *[Peter Hamilton](http://peterhamilton.github.com)*
+
+footer:
+  signature: -- DoCSoc Committee 2012
+  sponsors_image: https://s3-eu-west-1.amazonaws.com/docsoc/docsocsponsors.jpg # Bottom Sponsor Banner
+```
+
+### 2. Write a template
+An HTML file. The digest email renderer will look for the tag {{content}} and replace it with generated digest html.
+
+If you need to add styling, you may do so in the header and it will be converted to inline styles for email client compatibility.
+
+You can see a sample template at [https://peterhamilton.github.com/digest-email/blob/master/templates/default.html]
+
+### 3. Generate
+
+In the command line type `digest_email -h` to see a list of commands
+
+```bash
+digest_email -h
+Usage: digest_email [generate] [OPTIONS]
+
+Commands
+     generate: renders the email digest
+
+Required:
+    -f, --file FILE                  A digest file e.g. 2012-01-01.yml
+    -o, --output FILE                The file to output the html to e.g index.html
+
+Optional:
+    -t, --template FILE              an HTML file with a {{content}} template tag
+    -w, --warnings                   if present, will show premailer warnings
+    -h, --help                       help
+```
+
+For example to generate a digest email from [this template file](https://peterhamilton.github.com/digest-email/blob/master/templates/default.html) (template.html locally) and [this digest file](https://gist.github.com/4092848) (2012-01-01.yml locally) you would type the following:
+
+```bash
+digest_email -f 2012-01-01.yml -t template.html -o 2012-01-01_digest.html
+```
+
+Which results in the file you can see [here](http://docsoc.s3.amazonaws.com/sample/sample_digest_email.html). From there it's easy to send it out as an email.
+
+## Contributing
+This is a project put together in a few days in my spare time for a fairly specific use case, however if you do see improvements which could be made, I'd love to have people contribute.
+
+Just follow the following recommended process:
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/bin/digest_email

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'digest_email'
+require 'optparse'
+
+options = {}
+
+opt_parser = OptionParser.new do |opt|
+  opt.banner = "Usage: digest_email [generate] [OPTIONS]"
+  opt.separator  ""
+  opt.separator  "Commands"
+  opt.separator  "     generate: renders the email digest"
+  opt.separator  ""
+  opt.separator  "Required:"
+
+  opt.on("-f","--file FILE","A digest file e.g. 2012-01-01.yml") do |template|
+    options[:file] = template
+  end
+
+  opt.on("-o","--output FILE","The file to output the html to e.g index.html") do |output|
+    options[:output] = output
+  end
+
+  opt.separator  ""
+
+  opt.separator  "Optional:"
+
+  opt.on("-t","--template FILE","an HTML file with a {{content}} template tag") do |template|
+    options[:template] = template
+  end
+
+  opt.on("-w","--warnings","if present, will show premailer warnings") do |warnings|
+    options[:warnings] = warnings
+  end
+
+  opt.on("-h","--help","help") do
+    puts opt_parser
+    exit
+  end
+end
+
+
+begin
+  opt_parser.parse!(ARGV)
+  raise OptionParser::MissingArgument if options[:file].nil?
+
+  case ARGV[0]
+  when "generate"
+    begin
+      puts "#{Time.now} - Rendering Digest"
+      digest_yaml = YAML.load_file(options[:file])
+
+      template_file = options[:template] || File.join(File.dirname(__FILE__), "..", "templates/default.html")
+      warnings = options[:warnings] || false
+      template = File.read template_file
+
+      d = DigestEmail.parse(digest_yaml)
+
+      File.open(options[:output], 'w') { |file| file.write(d.render template, warnings) }
+      puts "#{Time.now} - Done. Digest saved as #{options[:output]}"
+    rescue Exception => e
+      puts "Error generating digest: #{e}"
+      exit
+    end
+  else
+    raise
+  end
+rescue
+  puts opt_parser
+  exit
+end
+
+

data/lib/digest_email/digest.rb

@@ -0,0 +1,45 @@
+require 'digest_email/digest_element'
+require 'premailer'
+
+module DigestEmail
+  class Digest < DigestElement
+
+
+    def initialize(header, items, footer)
+      @header = header
+      @items = items
+      @footer = footer
+      @children = [@header, @items, @footer]
+    end
+
+    def render(template = "{{content}}", show_warnings = false)
+      html = [@header.render(@items.children), @items.render, @footer.render].join
+      html = template.gsub '{{content}}', wrap(html)
+
+      # Convert any styles to inline
+      premailer = Premailer.new(html, :with_html_string => true)
+      html = premailer.to_inline_css
+
+      # Output any CSS warnings
+      if show_warnings
+        puts "Email Client Compatibility Warnings:"
+        premailer.warnings.each do |w|
+          puts "#{w[:message]} (#{w[:level]}) may not render properly in #{w[:clients]}"
+        end
+      end
+      html
+    end
+
+    def wrap(inner)
+      ["<div class=\"digest\">",
+       "<table>",
+       "<tr>",
+       "<td>",
+       inner,
+       "</td>",
+       "</tr>",
+       "</table>",
+       "</div>"].join
+    end
+  end
+end

data/lib/digest_email/digest_element.rb

@@ -0,0 +1,21 @@
+require 'digest_email/digest_element'
+
+module DigestEmail
+  class DigestElement
+    attr_accessor :children
+
+    def initialize
+      @children = []
+    end
+
+    # Render each child, join all the html and wrap it
+    def render
+      wrap @children.map(&:render).join("\n")
+    end
+
+    # By default don't wrap with anything
+    def wrap(inner)
+      inner
+    end
+  end
+end

data/lib/digest_email/digest_footer.rb

@@ -0,0 +1,36 @@
+require 'digest_email/digest_element'
+require 'maruku'
+
+module DigestEmail
+  class DigestFooter < DigestElement
+    attr_accessor :signature, :sponsors_image
+
+    def initialize(footer)
+      super()
+      @signature = footer["signature"]
+      @sponsors_image = footer["sponsors_image"]
+    end
+
+    def render
+      parsed_signature = Maruku.new(@signature).to_html
+      html  = [
+        "<div class=\"digest-email-dot-seperator\"></div>",
+        "<div class=\"digest-email-footer-signature\"><div>#{parsed_signature}</div></div>",
+        render_sponsors_image
+      ]
+
+      wrap html.join("\n")
+    end
+
+    def render_sponsors_image
+      html  = ["<div class=\"digest-email-footer-sponsors-image\">"]
+      html << ["<img src=\"#{@sponsors_image}\"/>"]
+      html << ["</div>"]
+      html.join("\n")
+    end
+
+    def wrap(inner)
+      "<div class=\"digest-email-footer\">#{inner}</div>"
+    end
+  end
+end

data/lib/digest_email/digest_header.rb

@@ -0,0 +1,65 @@
+require 'digest_email/digest_element'
+require 'maruku'
+
+module DigestEmail
+  class DigestHeader < DigestElement
+    attr_accessor :title, :subtitle, :subsubtitle
+
+    def initialize(header)
+      super()
+      @title = header["title"]
+
+      if header.has_key? "subtitle"
+        @subtitle = header["subtitle"]
+      else
+        @subtitle = nil
+      end
+
+      if header.has_key? "subsubtitle"
+        @subsubtitle = header["subsubtitle"]
+      else
+        @subsubtitle = nil
+      end
+    end
+
+    def render(items)
+      parsed_title = Maruku.new(@title).to_html
+
+      html = ["<div class=\"digest-email-header-title\">#{parsed_title}</div>"]
+
+      unless @subtitle.nil?
+        parsed_subtitle = Maruku.new(@subtitle).to_html
+        html << ["<div class=\"digest-email-header-subtitle\">",
+                 parsed_subtitle,
+                 "</div>"]
+      end
+
+      unless @subsubtitle.nil?
+        parsed_subsubtitle = Maruku.new(@subsubtitle).to_html
+        html << ["<div class=\"digest-email-header-subsubtitle\">",
+                 parsed_subsubtitle,
+                 "</div>"]
+      end
+
+      # Contents List
+      html << ["<div class=\"digest-email-dot-seperator\"></div>"]
+      html << render_contents_list(items)
+      html << ["<div class=\"digest-email-dot-seperator\"></div>"]
+
+      wrap html.join("\n")
+    end
+
+    def render_contents_list(items)
+      html =  ["<div class=\"digest-email-header-contents-list\">"]
+      html << ["<ol>"]
+      html << items.map { |item| "<li>#{item.list_title}</li>" }.join
+      html << ["</ol>"]
+      html << ["</div>"]
+      html.join
+    end
+
+    def wrap(inner)
+      "<div class=\"digest-email-header\">#{inner}</div>"
+    end
+  end
+end

data/lib/digest_email/digest_item.rb

@@ -0,0 +1,42 @@
+require 'digest_email/digest_element'
+require 'maruku'
+
+module DigestEmail
+  class DigestItem < DigestElement
+    attr_accessor :list_title, :title, :image, :body
+
+    def initialize(item)
+      super()
+      @list_title = item["list_title"]
+      @title = item["title"]
+      @image = item["image"]
+      @body = item["body"]
+    end
+
+    def render
+      parsed_title = Maruku.new(@title).to_html
+      parsed_body = Maruku.new(@body).to_html
+
+      html  = [
+        render_image,
+        "<div class=\"digest-email-item-content-container\">",
+          "<div class=\"digest-email-item-title\">#{parsed_title}</div>",
+          "<div class=\"digest-email-item-body\">#{parsed_body}</div>",
+        "</div>"
+      ]
+
+      wrap html.join("\n")
+    end
+
+    def render_image
+      html  = ["<div class=\"digest-email-item-image\">"]
+      html << ["<img src=\"#{@image}\"/>"]
+      html << ["</div>"]
+      html.join("\n")
+    end
+
+    def wrap(inner)
+      "<div class=\"digest-email-item\">#{inner}<div class=\"clear\"></div></div>"
+    end
+  end
+end

data/lib/digest_email/digest_items.rb

@@ -0,0 +1,26 @@
+require 'digest_email/digest_element'
+
+class Array
+  # As per http://stackoverflow.com/questions/3676027
+  def intersperse(separator)
+    (inject([]) { |a,v|  a + [v,separator] })[0...-1]
+  end
+end
+
+module DigestEmail
+  class DigestItems < DigestElement
+    def initialize(items)
+      super()
+      @children = items
+    end
+
+    def render
+      rendered_items = @children.map(&:render)
+      wrap rendered_items.join "\n<div class=\"digest-email-dot-seperator\"></div>\n"
+    end
+
+    def wrap(inner)
+      "<div class=\"digest-email-items\">#{inner}</div>"
+    end
+  end
+end

data/lib/digest_email/digest_parser.rb

@@ -0,0 +1,41 @@
+require File.dirname(__FILE__) + '/digest_parser_validator'
+
+module DigestEmail
+  class DigestParser
+    extend DigestParserValidator
+
+    def self.parse(digest)
+      begin
+        validate_indices(digest, ["header", "items", "footer"])
+
+        header = parse_header(digest["header"])
+        body   = parse_items(digest["items"])
+        footer = parse_footer(digest["footer"])
+
+        DigestEmail::Digest.new(header, body, footer)
+      rescue Exception => e
+        raise "Failed to parse digest: #{e.message}"
+      end
+    end
+
+    def self.parse_header(header)
+      validate_index(header, "title")
+      DigestEmail::DigestHeader.new header
+    end
+
+    def self.parse_items(items)
+      DigestEmail::DigestItems.new items.map{|item| parse_item(item)}
+    end
+
+    def self.parse_item(item)
+      validate_indices(item, ["list_title", "image", "title", "body"])
+
+      DigestEmail::DigestItem.new item
+    end
+
+    def self.parse_footer(footer)
+      validate_indices(footer, ["signature", "sponsors_image"])
+      DigestEmail::DigestFooter.new footer
+    end
+  end
+end

data/lib/digest_email/digest_parser_validator.rb

@@ -0,0 +1,22 @@
+module DigestParserValidator
+
+  # Invalidates index if missing or empty, taking advantage of lazy eval
+  def valid_index?(item, index)
+    item.has_key?(index) and !item[index].nil? and !item[index].empty?
+  end
+
+  # Validate an index for given hash
+  def validate_index(item, index)
+    unless valid_index?(item, index)
+      raise "Missing digest field #{index.capitalize}"
+    end
+  end
+
+  # Validates multiple indices for given hash
+  def validate_indices(item, indices)
+    indices.each do |index|
+      validate_index(item, index)
+    end
+  end
+
+end

data/lib/digest_email/version.rb

@@ -0,0 +1,3 @@
+module DigestEmail
+  VERSION = "1.0.1"
+end

data/lib/digest_email.rb

@@ -0,0 +1,13 @@
+require "digest_email/version"
+require "digest_email/digest"
+require "digest_email/digest_header"
+require "digest_email/digest_items"
+require "digest_email/digest_item"
+require "digest_email/digest_footer"
+require "digest_email/digest_parser"
+
+module DigestEmail
+  def self.parse(digest_hash)
+    DigestParser.parse digest_hash
+  end
+end

data/templates/default.html

@@ -0,0 +1,134 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+    <style type="text/css">
+
+      /*
+         Elements taken from:
+         http://meyerweb.com/eric/tools/css/reset/
+         v2.0 | 20110126
+         License: none (public domain)
+      */
+
+      table {
+        -premailer-width: 600;
+      }
+
+      p {
+        margin: 5px 0px;
+        padding: 0;
+        border: 0;
+        vertical-align: baseline;
+      }
+
+      /* HTML5 display-role reset for older browsers */
+      article, aside, details, figcaption, figure,
+      footer, header, hgroup, menu, nav, section {
+        display: block;
+      }
+
+      body {
+        line-height: 1;
+      }
+
+      blockquote, q {
+        quotes: none;
+      }
+      blockquote:before, blockquote:after,
+      q:before, q:after {
+        content: '';
+        content: none;
+      }
+      table {
+        border-collapse: collapse;
+        border-spacing: 0;
+        -premailer-width: 600;
+        -premailer-cellpadding: 20;
+      }
+
+      /* END RESET */
+
+      * {
+        font-family: Arial, Helvetica, sans-serif!important;
+      }
+
+      body {
+        color:#000000;
+        padding: 0px;
+        margin: 0px;
+        color: #444;
+      }
+
+      .digest {
+        width: 600px;
+        margin: 0 auto;
+      }
+
+      .digest-email-header-title {
+        font-size:50px;
+        line-height:60px;
+        text-align: center;
+      }
+
+      .digest-email-header-subtitle {
+        font-size: 20px;
+        text-align: center;
+        margin-bottom: 10px;
+      }
+
+      .digest-email-header-contents-list {
+        font-size: 20px;
+        line-height: 25px;
+      }
+
+      .digest-email-item {
+        margin: 10px 0px;
+      }
+
+      .digest-email-item-image {
+        width: 150px;
+        float: left;
+      }
+
+      .digest-email-item-content-container {
+        margin-left:10px;
+        width: 440px;
+        float: left;
+        text-align: justify;
+        font-size: 14px;
+        line-height: 20px;
+      }
+
+      .digest-email-item-title {
+        font-weight: bold;
+        margin-bottom: 5px;
+      }
+
+      .digest-email-dot-seperator {
+        background: url('https://s3-eu-west-1.amazonaws.com/docsoc/dots.jpg');
+        background-repeat: repeat-x;
+        height: 1px;
+        margin: 5px 0px;
+      }
+
+      .digest-email-footer-signature {
+        padding-top: 10px;
+        text-align: right;
+      }
+
+      .digest-email-footer-sponsors-image {
+        margin-top: 15px;
+      }
+
+      .clear {
+        clear: both;
+      }
+
+
+    </style>
+  </head>
+  <body>
+    {{content}}
+  </body>
+</html>

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: digest_email
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Peter Hamilton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-17 00:00:00.000000000 Z
+dependencies: []
+description: Gem to generate a weekly email digest
+email:
+- peter@inspiredpixel.net
+executables:
+- digest_email
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/digest_email/digest.rb
+- lib/digest_email/digest_element.rb
+- lib/digest_email/digest_footer.rb
+- lib/digest_email/digest_header.rb
+- lib/digest_email/digest_item.rb
+- lib/digest_email/digest_items.rb
+- lib/digest_email/digest_parser.rb
+- lib/digest_email/digest_parser_validator.rb
+- lib/digest_email/version.rb
+- lib/digest_email.rb
+- templates/default.html
+- bin/digest_email
+- README.md
+- LICENSE.txt
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Gem to generate a weekly email digest
+test_files: []