inkcite 1.0.0

data/lib/inkcite/renderer/litmus.rb

@@ -0,0 +1,33 @@
+module Inkcite
+  module Renderer
+    class Litmus < Base
+
+      def render tag, opt, ctx
+
+        # Litmus tracking is enabled only for production emails.
+        return nil unless ctx.production? && ctx.email?
+
+        code = opt[:code] || opt[:id]
+        return nil if code.blank?
+
+        merge_tag = opt[MERGE_TAG] || ctx[MERGE_TAG]
+
+        ctx.styles << "@media print{#_t { background-image: url('https://#{code}.emltrk.com/#{code}?p&d=#{merge_tag}');}}"
+        ctx.styles << "div.OutlookMessageHeader {background-image:url('https://#{code}.emltrk.com/#{code}?f&d=#{merge_tag}')}"
+        ctx.styles << "table.moz-email-headers-table {background-image:url('https://#{code}.emltrk.com/#{code}?f&d=#{merge_tag}')}"
+        ctx.styles << "blockquote #_t {background-image:url('https://#{code}.emltrk.com/#{code}?f&d=#{merge_tag}')}"
+        ctx.styles << "#MailContainerBody #_t {background-image:url('https://#{code}.emltrk.com/#{code}?f&d=#{merge_tag}')}"
+
+        ctx.footer << '<div id="_t"></div>'
+        ctx.footer << "<img src=\"https://#{code}.emltrk.com/#{code}?d=#{merge_tag}\" width=1 height=1 border=0 />"
+
+        nil
+      end
+
+      private
+
+      MERGE_TAG = :'merge-tag'
+
+    end
+  end
+end

data/lib/inkcite/renderer/lorem.rb

@@ -0,0 +1,39 @@
+module Inkcite
+  module Renderer
+    class Lorem < Base
+
+      def render tag, opt, ctx
+
+        # Lazy load only if Lorem is used in the email.
+        require 'faker'
+
+        type = (opt[:type] || :sentences).to_sym
+
+        # Get the limit (e.g. the number of sentences )
+        limit = opt[:sentences] || opt[:size] || opt[:limit] || opt[:count]
+
+        # Always warn the creator that there is Lorem Ipsum in the email because
+        # we don't want it to ship accidentally.
+        ctx.error 'Email contains Lorem Ipsum'
+
+        if type == :headline
+
+          words = (limit || 4).to_i
+          Faker::Lorem.words(words).join(SPACE).titlecase
+
+        else
+
+          sentences = (limit || 3).to_i
+          Faker::Lorem.sentences(sentences).join(SPACE)
+
+        end
+
+      end
+
+      private
+
+      SPACE = ' '
+
+    end
+  end
+end

data/lib/inkcite/renderer/mobile_image.rb

@@ -0,0 +1,67 @@
+# Image swapping technique courtesy of Email on Acid.
+# http://www.emailonacid.com/blog/details/C13/a_slick_new_image_swapping_technique_for_responsive_emails
+module Inkcite
+  module Renderer
+    class MobileImage < ImageBase
+
+      # Image swapping technique
+      def render tag, opt, ctx
+
+        tag_stack = ctx.tag_stack(:mobile_image)
+
+        if tag == '/mobile-img'
+          tag_stack.pop
+          return '</span>'
+        end
+
+        tag_stack << opt
+
+        # This is a transient, wrapper Element that we're going to use to
+        # style the attributes of the object that will appear when the
+        # email is viewed on a mobile device.
+        img = Element.new('mobile-img')
+
+        mix_dimensions img, opt
+
+        mix_background img, opt
+
+        display = opt[:display]
+        img.style[:display] = "#{display}" if display && display != BLOCK && display != DEFAULT
+
+        align = opt[:align]
+        img.style[:float] = align unless align.blank?
+
+        # Create a custom klass from the mobile image source name.
+        klass = klass_name(opt[:src], ctx)
+
+        src = image_url(opt[:src], opt, ctx)
+        img.style[BACKGROUND_IMAGE] = "url(#{src})"
+
+        # Initially, copy the height and width into the CSS so that the
+        # span assumes the exact dimensions of the image.
+        DIMENSIONS.each { |dim| img.style[dim] = px(opt[dim]) }
+
+        mobile = opt[:mobile]
+
+        # For FILL-style mobile images, override the width.  The height (in px)
+        # will ensure that the span displays at a desireable size and the
+        # 'cover' attribute will ensure that the image fills the available
+        # space ala responsive web design.
+        # http://www.campaignmonitor.com/guides/mobile/optimizing-images/
+        img.style[:width] = '100%' if mobile == FILL
+
+        # Now visualize a span element
+        span = Element.new('span')
+
+        mix_responsive span, opt, ctx, IMAGE
+
+        # Add the class that handles inserting the correct background image.
+        ctx.media_query << span.add_rule(Rule.new('span', klass, img.style))
+
+        span.to_s
+      end
+
+    end
+  end
+end
+

data/lib/inkcite/renderer/mobile_style.rb

@@ -0,0 +1,40 @@
+module Inkcite
+  module Renderer
+
+    class MobileStyle < Responsive
+
+      def render tag, opt, ctx
+
+        klass = detect(opt[:name], opt[:id])
+        if klass.blank?
+          ctx.error('Declaring a mobile style requires a name attribute')
+
+        else
+
+          mq = ctx.media_query
+
+          declarations = opt[:style]
+          if declarations.blank?
+            ctx.error('Declaring a mobile style requires a style attribute', { :name => klass })
+
+          elsif !mq.find_by_klass(klass).nil?
+            ctx.error('A mobile style was already defined with that class name', { :name => klass, :style => declarations })
+
+          else
+
+            # Create a new rule with the specified klass and declarations but mark
+            # it inactive.  Like other rule presets, it will be activated on first use.
+            mq << Rule.new(UNIVERSAL, klass, declarations, false)
+
+          end
+
+        end
+
+        nil
+      end
+
+    end
+
+  end
+end
+

data/lib/inkcite/renderer/mobile_toggle.rb

@@ -0,0 +1,27 @@
+# Brian Graves' Toggle Responsive Pattern
+# http://briangraves.github.io/ResponsiveEmailPatterns/patterns/navigation/toggle.html
+module Inkcite
+  module Renderer
+
+    class MobileToggleOn < Responsive
+
+      def render tag, opt, ctx
+
+        return '{/a}' if tag == '/mobile-toggle-on'
+
+        id = opt[:id]
+        if id.blank?
+          ctx.error('The mobile-toggle-on requires an id')
+
+        else
+          "{a href=\"##{id}\" mobile=\"show\"}"
+
+        end
+
+      end
+
+    end
+
+  end
+end
+

data/lib/inkcite/renderer/outlook_background.rb

@@ -0,0 +1,48 @@
+module Inkcite
+  module Renderer
+    class OutlookBackground < Base
+
+      def render tag, opt, ctx
+
+        # Do nothing if vml is disabled globally.
+        return nil unless ctx.vml_enabled?
+
+        html = '<!--[if gte mso 9]>'
+
+        if tag == '/outlook-bg'
+          html << '</div>'
+          html << '</v:textbox>'
+          html << '</v:rect>'
+
+        else
+
+          src = opt[:src]
+          raise 'Outlook background missing required src attribute' if src.blank?
+
+          width = opt[:width].to_i
+          height = opt[:height].to_i
+          raise "Outlook background requires dimensions: #{width}x#{height} " if width <= 0 || height <= 0
+
+          html << render_tag('v:rect',
+              { :'xmlns:v' => quote('urn:schemas-microsoft-com:vml'), :fill => quote(true), :stroke => quote(false) },
+              { :width => px(width), :height => px(height) }
+          )
+
+          html << render_tag('v:fill', { :type => 'tile', :src => quote(ctx.image_url(src)), :color => hex(opt[:bgcolor]), :self_close => true })
+
+          html << render_tag('v:textbox', { :inset => '0,0,0,0' })
+          html << '<div>'
+
+          # Flag the context as having had VML used within it.
+          ctx.vml_used!
+
+        end
+
+        html << '<![endif]-->'
+
+        html
+      end
+
+    end
+  end
+end

data/lib/inkcite/renderer/partial.rb

@@ -0,0 +1,31 @@
+module Inkcite
+  module Renderer
+    class Partial < Base
+
+      def render tag, opt, ctx
+
+        # Get the name of the file to include and then resolve the full
+        # path to the file relative to the email's project directory.
+        file_name = opt[:file]
+        file = ctx.email.project_file(file_name)
+
+        # Verify the file exists and route it through ERB.  Otherwise
+        # let the designer know that the file is missing.
+        if File.exist?(file)
+          ctx.eval_erb(File.open(file).read, file_name)
+
+        else
+          ctx.error "Include not found", :file => file
+
+          # Return an empty string so that the renderer has something
+          # to process - otherwise it throws an additional error on
+          # the command line.
+          ''
+
+        end
+
+      end
+
+    end
+  end
+end

data/lib/inkcite/renderer/preheader.rb

@@ -0,0 +1,22 @@
+module Inkcite
+  module Renderer
+    class Preheader < Base
+
+      def render tag, opt, ctx
+
+        if tag == '/preheader'
+          '</span>'
+
+        else
+
+          # Preheader text styling courtesy "Don’t forget about preheader text" section of
+          # Lee Munroe's blog entry: http://www.leemunroe.com/building-html-email/
+          '<span style="color: transparent; display: none !important; height: 0; max-height: 0; max-width: 0; opacity: 0; overflow: hidden; mso-hide: all; visibility: hidden; width: 0;">'
+
+        end
+
+      end
+
+    end
+  end
+end

data/lib/inkcite/renderer/property.rb

@@ -0,0 +1,39 @@
+module Inkcite
+  module Renderer
+    class Property < Base
+
+      def render tag, opt, ctx
+
+        html = ctx[tag]
+        if html.nil?
+          ctx.error 'Unknown tag or property', { :tag => tag, :opt => "[#{opt.to_query}]" }
+          return nil
+        end
+
+        # Need to clone the property - otherwise, we modify the original property.
+        # Which is bad.
+        html = html.clone
+
+        Parser.each html, VARIABLE_REGEX do |pair|
+
+          # Split the declaration on the equals sign.
+          variable, default = pair.split(EQUALS, 2)
+
+          # Check to see if the variable has been defined in the parameters.  If so, use that
+          # value - otherwise, inherit the default.
+          (opt[variable.to_sym] || default).to_s
+
+        end
+
+      end
+
+      private
+
+      VARIABLE_REGEX = /\$([^\$]+)\$/
+
+      DOLLAR = '$'
+      EQUALS = '='
+
+    end
+  end
+end

data/lib/inkcite/renderer/responsive.rb

@@ -0,0 +1,334 @@
+module Inkcite
+  module Renderer
+    class Responsive < Base
+
+      BUTTON    = 'button'
+      DROP      = 'drop'
+      FILL      = 'fill'
+      HIDE      = 'hide'
+      IMAGE     = 'img'
+      SHOW      = 'show'
+      SWITCH    = 'switch'
+      SWITCH_UP = 'switch-up'
+      TOGGLE    = 'toggle'
+
+      # For elements that take on different background properties
+      # when they go responsive
+      MOBILE_BGCOLOR             = :'mobile-bgcolor'
+      MOBILE_BACKGROUND          = :'mobile-background'
+      MOBILE_BACKGROUND_COLOR    = :'mobile-background-color'
+      MOBILE_BACKGROUND_IMAGE    = :'mobile-background-image'
+      MOBILE_BACKGROUND_REPEAT   = :'mobile-background-repeat'
+      MOBILE_BACKGROUND_POSITION = :'mobile-background-position'
+      MOBILE_BACKGROUND_SIZE     = :'mobile-background-size'
+
+      class Rule
+
+        attr_reader :declarations
+        attr_reader :klass
+
+        def initialize tags, klass, declarations, active=true
+          @klass = klass
+          @declarations = declarations
+
+          @tags = Set.new [*tags]
+
+          # By default, a rule isn't considered active until it has
+          # been marked used.  This allows the view to declare built-in
+          # styles (such as hide or stack) that don't show up in the
+          # rendered HTML unless the author references them.
+          @active = active
+
+        end
+
+        def << tag
+          @tags << tag
+        end
+
+        def activate!
+          @active = true
+        end
+
+        def active?
+          @active
+        end
+
+        def att_selector_string
+          "[class~=#{Renderer.quote(@klass)}]"
+        end
+
+        def block?
+          declaration_string.downcase.include?('block')
+        end
+
+        def declaration_string
+          if @declarations.is_a?(Hash)
+            Renderer.render_styles(@declarations)
+          elsif @declarations.is_a?(Array)
+            @declarations.join(' ')
+          else
+            @declarations.to_s
+          end
+        end
+
+        def include? tag
+          universal? || @tags.include?(tag)
+        end
+
+        def to_css
+
+          rule = ""
+
+          att_selector = att_selector_string
+
+          if universal?
+
+            # Only the attribute selector is needed when the rule is universal.
+            # http://www.w3.org/TR/CSS2/selector.html#universal-selector
+            rule << att_selector
+
+          else
+
+            # Create an attribute selector that targets each tag.
+            @tags.sort.each do |tag|
+              rule << ',' unless rule.blank?
+              rule << tag
+              rule << att_selector
+            end
+
+          end
+
+          rule << " { "
+          rule << declaration_string
+          rule << " }"
+
+          rule
+        end
+
+        def universal?
+          @tags.include?(UNIVERSAL)
+        end
+
+      end
+
+      class TargetRule < Rule
+
+        def initialize tag, klass
+          super tag, klass, 'display: block !important;'
+        end
+
+        def att_selector_string
+          "[id=#{@klass}]:target"
+        end
+
+      end
+
+      def self.presets ctx
+
+        styles = []
+
+        # HIDE, which can be used on any responsive element, makes it disappear
+        # on mobile devices.
+        styles << Rule.new(UNIVERSAL, HIDE, 'display: none !important;', false)
+
+        # SHOW, which means the element is hidden on desktop but shown on mobile.
+        styles << Rule.new(UNIVERSAL, SHOW, 'display: block !important;', false)
+
+        # Brian Graves' Column Drop Pattern: Table goes to 100% width by way of
+        # the FILL rule and its cells stack vertically.
+        # http://briangraves.github.io/ResponsiveEmailPatterns/patterns/layouts/column-drop.html
+        styles << Rule.new('td', DROP, 'display: block; width: 100% !important; background-size: 100% auto !important; -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box;', false)
+
+        # Brian Graves' Column Switch Pattern: Allows columns in a table to
+        # be reordered based on up and down states.
+        # http://www.degdigital.com/blog/content-choreography-in-responsive-email/
+        styles << Rule.new('td', SWITCH, 'display: table-footer-group; width: 100% !important; background-size: 100% auto !important;')
+        styles << Rule.new('td', SWITCH_UP, 'display: table-header-group; width: 100% !important; background-size: 100% auto !important;')
+
+        # FILL causes specific types of elements to expand to 100% of the available
+        # width of the mobile device.
+        styles << Rule.new('img', FILL, 'width: 100% !important; height: auto !important;', false)
+        styles << Rule.new([ 'table', 'td' ], FILL, 'width: 100% !important; background-size: 100% auto !important;', false)
+
+        # For mobile-image tags.
+        styles << Rule.new('span', IMAGE, 'display: block; background-position: center; background-size: cover;', false)
+
+        # BUTTON causes ordinary links to transform into buttons based
+        # on the styles configured by the developer.
+        cfg = Button::Config.new(ctx)
+
+        button_styles = {
+            :color => "#{cfg.color} !important",
+            :display => 'block',
+            BACKGROUND_COLOR => cfg.bgcolor,
+            TEXT_SHADOW => "0 -1px 0 #{cfg.text_shadow}"
+        }
+
+        button_styles[:border] = cfg.border unless cfg.border.blank?
+        button_styles[BORDER_BOTTOM] = cfg.border_bottom if cfg.bevel > 0
+        button_styles[BORDER_RADIUS] = Renderer.px(cfg.border_radius) if cfg.border_radius > 0
+        button_styles[FONT_WEIGHT] = cfg.font_weight unless cfg.font_weight.blank?
+        button_styles[:height] = Renderer.px(cfg.height) if cfg.height > 0
+        button_styles[MARGIN_TOP] = Renderer.px(cfg.margin_top) if cfg.margin_top > 0
+        button_styles[:padding] = Renderer.px(cfg.padding) if cfg.padding > 0
+        button_styles[TEXT_ALIGN] = 'center'
+
+        styles << Rule.new('a', BUTTON, button_styles, false)
+
+        styles
+      end
+
+      protected
+
+      def mix_font element, opt, ctx, parent=nil
+
+        # Let the super class do its thing and grab the name of the font
+        # style that was applied, if any.
+        font = super
+
+        # Will hold the mobile font overrides for this element, if any.
+        style = { }
+
+        font_size = detect_font(MOBILE_FONT_SIZE, font, opt, parent, ctx)
+        style[FONT_SIZE] = "#{px(font_size)} !important" unless font_size.blank?
+
+        line_height = detect_font(MOBILE_LINE_HEIGHT, font, opt, parent, ctx)
+        style[LINE_HEIGHT] = "#{px(line_height)} !important" unless line_height.blank?
+
+        mix_responsive_style element, opt, ctx, Renderer.render_styles(style) unless style.blank?
+
+        font
+      end
+
+      def mix_responsive element, opt, ctx, klass=nil
+
+        # Apply the "mobile" attribute or use the override if one was provided.
+        mix_responsive_klass element, opt, ctx, klass || opt[:mobile]
+
+        # Apply the "mobile-style" attribute if one was provided.
+        mix_responsive_style element, opt, ctx, opt[MOBILE_STYLE]
+
+      end
+
+      def mix_responsive_klass element, opt, ctx, klass
+
+        # Nothing to do if there is no class specified.s
+        return nil if klass.blank?
+
+        mq = ctx.media_query
+
+        # The element's tag - e.g. table, td, etc.
+        tag = element.tag
+
+        # Special handling for TOGGLE-able elements which are made
+        # visible by another element being clicked.
+        if klass == TOGGLE
+
+          id = opt[:id]
+          if id.blank?
+            ctx.errors 'Mobile elements with toggle behavior require an ID attribute', { :tag => tag} if id.blank?
+
+          else
+
+            # Make sure the element's ID field is populated
+            element[:id] = id
+
+            # Add a rule which makes this element visible when the target
+            # field matches the identity.
+            mq << TargetRule.new(tag, id)
+
+            # Toggle-able elements are HIDE on mobile by default.
+            klass = HIDE
+
+          end
+        end
+
+        # Check to see if there is already a rule that specifically matches this klass
+        # and tag combination - e.g. td.hide
+        rule = mq.find_by_tag_and_klass(tag, klass)
+        if rule.nil?
+
+          # If no rule was found then find the first that matches the klass.
+          rule = mq.find_by_klass(klass)
+
+          # If no rule was found and the declaration is blank then we have
+          # an unknown mobile behavior.
+          if rule.nil?
+            ctx.error 'Undefined mobile behavior - are you missing a mobile-style declaration?', { :tag => tag, :mobile => klass }
+            return nil
+          end
+
+          rule << tag if !rule.include?(tag)
+
+        end
+
+        # If the rule is SHOW (only on mobile) we need to restyle the element
+        # so it is hidden.
+        element.style[:display] = 'none' if klass == SHOW
+
+        # Add the responsive rule to the element
+        element.add_rule rule
+
+      end
+
+      def mix_responsive_style element, opt, ctx, declarations=nil
+
+        # Check to see if a mobile style (e.g. "mobile-style='background-color: #ff0;'")
+        # has been declared for this element.
+        declarations ||= opt[MOBILE_STYLE]
+        return if declarations.blank?
+
+        mq = ctx.media_query
+
+        tag = element.tag
+
+        # If no klass was specified, check to see if any previously defined rule matches
+        # the style declarations.  If so, we'll reuse that rule and apply the klass
+        # to this object to avoid unnecessary duplication in the HTML.
+        rule = mq.find_by_declaration(declarations);
+        if rule.nil?
+
+          # Generate a unique class name for this style if it has not already been declared.
+          # These are of the form m001, etc.  Redability is not important because it's
+          # dynamically generated and referenced.
+          klass = unique_klass(ctx)
+
+          rule = Rule.new(tag, klass, declarations)
+
+          # Add the rule to the list of those that will be rendered into the
+          # completed email.
+          mq << rule
+
+        elsif !rule.include?(tag)
+
+          # Make sure this tag is included in the list of those that
+          # the CSS will match against.
+          rule << tag
+
+        end
+
+        # Add the responsive rule to the element which automatically adds its
+        # class to the element's list.
+        element.add_rule rule
+
+      end
+
+      def unique_klass ctx
+        "m%1d" % ctx.unique_id(:m)
+      end
+
+      private
+
+      # Attribute used to declare custom mobile styles for an element.
+      MOBILE_STYLE = :'mobile-style'
+
+      # Universal CSS selector.
+      UNIVERSAL = '*'
+
+      # For font overrides on mobile devices.
+      MOBILE_FONT_SIZE   = :'mobile-font-size'
+      MOBILE_LINE_HEIGHT = :'mobile-line-height'
+
+    end
+  end
+end