inkcite 1.11.0 → 1.12.0

data/lib/inkcite/renderer/snow.rb

@@ -56,7 +56,7 @@ module Inkcite
 
         # If the image is missing, record an error to the console and
         # clear the image allowing the color to take precedence instead.
-        src = nil unless ctx.assert_image_exists(src)
+        src = nil if src && !ctx.assert_image_exists(src)
 
         # Flake rotation, used if an image is present.  (Rotating a colored
         # circle has no visual distinction.)  For convenience this tag accepts
@@ -77,6 +77,9 @@ module Inkcite
         # snow effect.
         mix_background div_wrap, opt, ctx
 
+        # Text alignment within the wrapper
+        mix_text_align div_wrap, opt, ctx
+
         # Kick things off by rendering the wrapping div.
         html = div_wrap.to_s
 
@@ -146,13 +149,17 @@ module Inkcite
         start_interval = end_time / flakes.to_f
         start_time = 0
 
+        # Will hold the sizes of each flake and will be used to offset their
+        # initial starting position in the animation section.
+        flake_sizes = {}
+
         # Now add individual class definitions for each flake with unique size,
         # speed and starting position.  Also add the animation trigger that loops
         # infinitely, starts at a random time and uses a random speed to completion.
         flakes.times do |flake|
 
           speed = rand(speed_range).round(1)
-          size = rand(size_range)
+          size = flake_sizes[flake] = rand(size_range)
 
           opacity = rand(opacity_range).round(1)
           if opacity < OPACITY_FLOOR
@@ -169,7 +176,7 @@ module Inkcite
           style << "    border-radius: #{px((size / 2.0).round)};" unless src
 
           style << "    opacity: #{opacity};" if opacity < OPACITY_CEIL
-          style << with_browser_prefixes('    ', "animation: #{anim_prefix}#{flake + 1} #{speed}s linear #{start_time.round(1)}s infinite;", webkit_only)
+          style << Animation.with_browser_prefixes("animation: #{anim_prefix}#{flake + 1} #{speed}s linear #{start_time.round(1)}s infinite;", ctx)
           style << '  }'
 
           start_time += start_interval
@@ -192,14 +199,17 @@ module Inkcite
           # Calculate the ending rotation for the flake, if rotation is enabled.
           end_rotation = rotation_enabled ? rand(ROTATION_RANGE) : 0
 
-          _style = "keyframes #{anim_prefix}#{flake + 1} {\n"
-          _style << "    0%   { top: -3%; left: #{start_left}%; }\n"
-          _style << "    100% { top: 100%; left: #{end_left}%;"
-          _style << with_browser_prefixes(' ', "transform: rotate(#{end_rotation}deg);", webkit_only, '') if end_rotation != 0
-          _style << " }\n"
-          _style << '  }'
+          keyframes = Animation::Keyframes.new("#{anim_prefix}#{flake + 1}", ctx)
+
+          # Start above the div area
+          keyframes.add_keyframe(0, :top => px(-flake_sizes[flake]), :left => pct(start_left.round))
+
+          # End below the div area, applying rotation if necessary.
+          keyframe = Animation::Keyframe.new(100, :top => '100%', :left => pct(end_left))
+          keyframe.add_with_prefixes(:transform, "rotate(#{end_rotation}deg)", ctx) if end_rotation != 0
+          keyframes << keyframe
 
-          style << with_browser_prefixes("  @", _style, webkit_only)
+          style << keyframes.to_s
 
         end
 

data/lib/inkcite/renderer/social.rb

@@ -0,0 +1,128 @@
+module Inkcite
+  module Renderer
+    class Social < Base
+
+      class Facebook < Social
+
+        def initialize
+          super(:src => 'facebook.png', :alt => 'Facebook', :cta => 'Share')
+        end
+
+        protected
+
+        def get_share_href url, text, opts, ctx
+          %Q(https://www.facebook.com/sharer/sharer.php?u=#{url}&t=#{text})
+        end
+
+      end
+
+      class Pintrest < Social
+
+        def initialize
+          super(:src => 'pintrest.png', :alt => 'Pintrest', :cta => 'Pin it', :color => '#CB2027')
+        end
+
+        protected_methods
+
+        def get_share_href url, text, opts, ctx
+
+          media = opts.delete(:media).to_s
+          ctx.error("Pintrest sharing 'media' attribute can't be blank", :id => opts[:id]) if media.blank?
+
+          %Q(https://www.pinterest.com/pin/create/button/?url=#{url}&media=#{Util::escape(media)}&description=#{text})
+        end
+
+      end
+
+      class Twitter < Social
+
+        def initialize
+          super(:src => 'twitter.png', :alt => 'Twitter', :cta => 'Tweet', :scale => 81 / 100.0)
+        end
+
+        protected
+
+        def get_share_href url, text, opts, ctx
+          %Q(https://twitter.com/share?url=#{url}&text=#{text})
+        end
+
+      end
+
+      def initialize defaults
+        @defaults = defaults
+
+        # Ensure a default scale of 1:1 is installed into the defaults
+        # if one is not otherwise provided.
+        @defaults[:scale] ||= 1.0
+
+      end
+
+      def render tag, opts, ctx
+
+        id = opts[:id]
+
+        share_url = opts.delete(:href).to_s
+        ctx.error("Social sharing 'href' attribute can't be blank", :tag => tag, :id => id) if share_url.blank?
+
+        share_text = opts.delete(:text).to_s
+        ctx.error("Social sharing 'text' attribute can't be blank", :tag => tag, :id => id, :href => share_url) if share_text.blank?
+
+        # Let the extending class format the fully-qualified URL to the sharing service.
+        service_href = get_share_href Util.escape(share_url), Util.escape(share_text), opts, ctx
+
+        # Check to see if there is a special color for this link (e.g. Pintrest) or
+        # if it has been specified by the caller.
+        opts[:color] ||= @defaults[:color]
+
+        if icon = !opts[:noicon]
+
+          # Ensure that the sharing icon exists in the project.
+          ensure_icon_exists ctx
+
+          height = (opts.delete(:size) || opts.delete(:height) || 15).to_i
+          width = (height / @defaults[:scale]).round
+
+          # Force the font size and line height to match the size of the
+          # icon being used - this ensures proper vertical middle alignment.
+          opts[FONT_SIZE] = height
+          opts[LINE_HEIGHT] = height
+
+        end
+
+        cta = opts[:cta] || @defaults[:cta]
+
+        html = %Q({a href="#{service_href}" #{Renderer.join_hash(opts)}})
+        html << %Q({img src=#{@defaults[:src]} height=#{height} width=#{width} display=inline alt="#{@defaults[:alt]}"} ) if icon
+        html << %Q(#{cta}{/a})
+
+        html
+      end
+
+      protected
+
+      def ensure_icon_exists ctx
+
+        src = @defaults[:src]
+
+        # Get the full destination path to the icon in the current project.  If
+        # the icon already exists, then there is nothing left to do.
+        dest_icon_path = ctx.email.image_path(src)
+        return if File.exist?(dest_icon_path)
+
+        # Get the full path to the source icon bundled with Inkcite.
+        source_icon_path = File.join(Inkcite.asset_path, 'social', src)
+
+        # Ensure that the images/ directory exists in the project, then copy
+        # the image into it.
+        FileUtils.mkpath(ctx.email.image_dir)
+        FileUtils.cp(source_icon_path, dest_icon_path)
+
+      end
+
+      def get_share_href url, text, opts, ctx
+        raise NotImplementedError
+      end
+
+    end
+  end
+end

data/lib/inkcite/renderer/table.rb

@@ -2,6 +2,10 @@ module Inkcite
   module Renderer
     class Table < TableBase
 
+      # Name of the attribute allowing a transition attribute to be placed
+      # on the automatically-added <tr> element.
+      TR_TRANSITION = :'tr-transition'
+
       def render tag, opt, ctx
 
         html = ''
@@ -108,7 +112,15 @@ module Inkcite
           mix_responsive table, opt, ctx, mobile
 
           html << table.to_s
-          html << '<tr>'
+
+          tr = Element.new('tr')
+
+          # Check for a row transition which is necessary to facilitate
+          # cross-column animation - e.g. tr-transition="all .5s cubic-bezier(0.075, 0.82, 0.165, 1)"
+          tr_transition = opt[TR_TRANSITION]
+          tr.style[:transition] = tr_transition unless none?(tr_transition)
+
+          html << tr.to_s
 
           if is_fluid_drop
 

data/lib/inkcite/renderer/table_base.rb

@@ -12,6 +12,7 @@ module Inkcite
 
       def mix_all element, opt, ctx
 
+        mix_animation element, opt, ctx
         mix_background element, opt, ctx
         mix_border element, opt, ctx
         mix_dimensions element, opt, ctx
@@ -20,12 +21,11 @@ module Inkcite
 
       def mix_background element, opt, ctx
 
-        bgcolor = opt[:bgcolor]
-        bgcolor = nil if bgcolor == NONE
+        bgcolor = detect_bgcolor(opt)
 
         # Set the bgcolor attribute of the element as a fallback if
         # css isn't supported.
-        element[:bgcolor] = hex(bgcolor) unless bgcolor.blank?
+        element[:bgcolor] = bgcolor unless bgcolor.nil?
 
         bgimage    = opt[:background]
         bgposition = opt[BACKGROUND_POSITION]

data/lib/inkcite/renderer/td.rb

@@ -24,9 +24,12 @@ module Inkcite
 
         if tag == CLOSE_TD
 
-          # Retrieve the opts that were used to open this TD.  We'll need them to
-          # check for the private _fluid_drop attribute.
-          tag_stack.pop
+          # Retrieve the opts that were used to open this TD.
+          open_opt = tag_stack.pop
+
+          # If the opening tag initiated an automatic outlook background
+          # then we need to inject the close tag here.
+          html << "{/outlook-bg}\n" if outlook_bg?(open_opt)
 
           # Normal HTML produced by the Helper to close the cell.
           html << '</td>'
@@ -126,7 +129,7 @@ module Inkcite
                   :color => NONE,
                   FONT_SIZE => 1,
                   LINE_HEIGHT => 1
-              }) unless opt[:flush].blank?
+              }) if opt[:flush]
 
           # Custom handling for text align on TDs rather than Base's mix_text_align
           # because if possible, using align= rather than a style keeps emails
@@ -165,11 +168,23 @@ module Inkcite
 
           mix_responsive td, opt, ctx, mobile
 
-          #outlook-bg	<!-&#45;&#91;if gte mso 9]>[n]<v:rect style="width:%width%px;height:%height%px;" strokecolor="none"><v:fill type="tile" src="%src%" /></v:fill></v:rect><v:shape id="theText[rnd]" style="position:absolute;width:%width%px;height:%height%px;margin:0;padding:0;%style%">[n]<!&#91;endif]&#45;->
-          #/outlook-bg	<!-&#45;&#91;if gte mso 9]></v:shape><!&#91;endif]&#45;->
-
           html << td.to_s
 
+          # For convenience and to keep code DRY, support the outlook-bg boolean
+          # attribute which causes an {outlook-bg} Helper to be injected automatically
+          # inside of the {td}.
+          if outlook_bg?(opt)
+
+            html << "\n"
+            html << Element.new('outlook-bg', {
+                    :bgcolor => detect_bgcolor(opt),
+                    :width => opt[:width],
+                    :height => opt[:height],
+                    :src => opt[:background]
+                }).to_helper
+
+          end
+
         end
 
         html
@@ -177,9 +192,19 @@ module Inkcite
 
       private
 
+      # Returns true if the conditions are met that enable the
+      # automatic {outlook-bg} helper integration.
+      def outlook_bg? opt
+        opt && opt[OUTLOOK_BG] && !opt[:background].blank?
+      end
+
       CLOSE_TD = '/td'
       LEFT = 'left'
 
+      # Boolean attribute triggering automatic outlook background
+      # integration in the TD.
+      OUTLOOK_BG = :'outlook-bg'
+
     end
   end
 end

data/lib/inkcite/renderer/video_preview.rb

@@ -0,0 +1,257 @@
+module Inkcite
+  module Renderer
+
+    # Better video preview courtesy of @stigm
+    # https://medium.com/cm-engineering/better-video-previews-for-email-12432ce71846#.2o9qgc7hd
+    class VideoPreview < Base
+
+      def render tag, opt, ctx
+
+        # Get a unique ID for this video which will make its CSS classes
+        # distinct from other videos in the email.
+        uid = ctx.unique_id(:video)
+
+        # Links need an ID
+        id = opt[:id] || "video-preview#{uid}"
+
+        # Grab the URL for the video - this is passed on to the {a} Helper and
+        # the user will be warned appropriately if the URL is missing.
+        href = opt[:href].freeze
+
+        # Grab the name of the source file that can be optionally embeded with %1
+        # which will increment for each frame (e.g. video%1.jpg becomes video1.jpg,
+        # video2.jpg etc. up to the total number of frames).  The original source
+        # image name is frozen to ensure it isn't modified later.
+        src = opt[:src].freeze
+
+        # This will hold all frame source file names interpolated to include
+        # index (e.g. %1 being replaced with the frame number, if present).
+        frames = []
+
+        # For each frame, create a fully-qualified image source and
+        # add it to the frame list.
+        frame_count = (opt[:frames] || 1).to_i
+
+        # True if the video clip will animate using smooth fading
+        # between several frames of the video.
+        has_animation = frame_count > 1
+
+        # Iterate through the frames and replace %1 with the frame number.
+        # this loop also verifies that the referenced image exists.
+        frame_count.times do |n|
+          frame_src = src.gsub('%1', "#{n + 1}")
+
+          # Check that non-fully-qualified images exist in the project's
+          # images/ directory.
+          unless Util::is_fully_qualified?(frame_src)
+            ctx.assert_image_exists(frame_src)
+            frame_src = ctx.image_url(frame_src)
+          end
+
+          frames << frame_src
+        end
+
+        # Grab the first fully-qualified frame
+        first_frame = frames[0]
+
+        # Duration of the animated frame cycling, if multiple frames are provided.
+        duration = (opt[:duration] || 15).to_i
+
+        # Desired dimensions of the video clip.
+        width = opt[:width].to_i
+        height = opt[:height].to_i
+        ctx.error("Video preview #{uid} is missing dimensions", { :width => width, :height => height, :src => src, :href => href }) unless width > 0 && height > 0
+
+        # Calculate the scaled width for the left-side of the table
+        # which is a crafty way to preserve the aspect ratio of the
+        # video while it still fluidly scales.
+        scaled_width = (width * SCALE).round
+
+        # Background color and edge gradient - which defaults to a darker
+        # version of the background color if not specified.
+        bgcolor = detect_bgcolor(opt, '#5b5f66')
+        gradient = opt[:gradient] || Util::darken(bgcolor, 0.25)
+
+        # This is the name of the class applied to the anchor tag
+        # to animate the hover.
+        hover_klass = 'video'
+        play_button_klass = 'play-button'
+
+        # This is the name of the animation, if any, that will be
+        # assigned to the table and defined in the CSS.
+        animation_name = "#{hover_klass}#{uid}-frames"
+
+        html = []
+        html << '<!--[if !vml]-->'
+
+        # Using an Element to produce the appropriate anchor helper with
+        # the desired
+        html << Element.new('a', { :id => id, :href => href, :class => hover_klass, :bgcolor => bgcolor, :bggradient => gradient, :block => true }).to_helper
+
+        table = Element.new('table', {
+                :width => '100%', :background => first_frame, BACKGROUND_SIZE => 'cover',
+                Table::TR_TRANSITION => %q("all .5s cubic-bezier(0.075, 0.82, 0.165, 1)")
+            })
+        table[:animation] = %Q("#{animation_name} #{duration}s ease infinite") if has_animation
+        html << table.to_helper
+
+        html << Element.new('td', :width => '25%').to_helper
+
+        # Transparent spacer for preserving aspect ratio.
+        spacer_image_name = "vp-#{scaled_width}x#{height}.png"
+        spacer_image = File.join(ctx.email.image_dir, spacer_image_name)
+
+        # Test if the file exists
+        unless File.exist?(spacer_image)
+
+          # Requiring on-demand, don't load chunky_png unless the user has
+          # started using video_preview.
+          require 'chunky_png'
+
+          # Creating an image from scratch, save as an interlaced PNG
+          png = ChunkyPNG::Image.new(scaled_width, height, ChunkyPNG::Color::TRANSPARENT)
+          png.save(spacer_image, :interlace => true)
+
+        end
+
+        # 12/21/16: Using placehold.it is sub-optimal. It would be better
+        # to generate a transparent gif using something like Rmagick.  I've
+        # seen some instances where placeholdit can crash outlook but I guess
+        # this part is hidden from outlook so it isn't so bad.
+        html << Element.new('img', { :src => ctx.image_url(spacer_image_name), :alt => '', :width => '100%', :border => 0,
+                :style => { :height => :auto, :opacity => 0, :visibility => :hidden } }).to_s
+
+        html << '{/td}'
+
+        # Center column holds the CSS-based arrow
+        html << Element.new('td', :width => '50%', :align => :center, :valign => :middle).to_helper
+
+        play_arrow_size = (opt[PLAY_ARROW_SIZE] || 30).to_i
+
+        play_border_radius = (play_arrow_size * 1.1333).round
+        play_border_top_bottom = (play_arrow_size * 0.6).round
+        play_border_right = (play_arrow_size * 0.5333).round
+        play_border_left = (play_arrow_size * 0.8).round
+        play_arrow_height = (play_arrow_size * 0.5666).round
+
+        # These are the arrow and circle border, respectively.  Not currently
+        # configurable in terms of size or color.
+        html << %Q(<div class="#{play_button_klass}" style="background-image: linear-gradient(rgba(0,0,0,0.5), rgba(0,0,0,0.1)); border: 4px solid white; border-radius: 50%; box-shadow: 0 1px 2px rgba(0,0,0,0.3), inset 0 1px 2px rgba(0,0,0,0.3); height: #{px(play_border_radius)}; margin: 0 auto; padding: #{px(play_border_top_bottom)} #{px(play_border_right)} #{px(play_border_top_bottom)} #{px(play_border_left)}; transition: transform .5s cubic-bezier(0.075, 0.82, 0.165, 1); width: #{px(play_border_radius)};">)
+        html << %Q(<div style="border-color: transparent transparent transparent white; border-style: solid; border-width: #{px(play_arrow_height)} 0 #{px(play_arrow_height)} #{px(play_arrow_size)}; display: block; font-size: 0; height: 0; Margin: 0 auto; width: 0;">&nbsp;</div>)
+        html << '</div>'
+
+        html << '{/td}'
+        html << '{td width=25%}&nbsp;{/td}'
+        html << '{/table}'
+        html << '{/a}'
+
+        # Pre-loading the images prevents a flash that can occur because the
+        # browser only loads the frames once the animation demands them.
+        if has_animation && !opt[NO_PRELOAD]
+          all_frames = frames.collect { |f| %Q(url(#{f})) }.join(',')
+          html << Element.new('div', :style => { BACKGROUND_IMAGE => %Q("#{all_frames}"), :display => 'none' }).to_s + '</div>'
+        end
+
+        # Concludes the if [if !vml] section targeting non-outlook.
+        html << '<![endif]-->'
+
+        # Outlook arrow size also not configurable at this time.
+        outlook_arrow_size = 78
+        outlook_left = width / 2 - outlook_arrow_size / 2
+        outlook_top = height / 2 - outlook_arrow_size / 2
+
+        # Use the link central processing routine to ensure a viable link has
+        # been provided and tag/track it from Outlook.
+        outlook_href = Link.process(id, href, false, ctx)
+
+        html << '<!--[if vml]>'
+        html << %Q(<v:group xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" coordsize="#{width},#{height}" coordorigin="0,0" href="#{outlook_href}" style="width:#{width}px;height:#{height}px;">)
+        html << %Q(<v:rect fill="t" stroked="f" style="position:absolute;width:#{width};height:#{height};"><v:fill src="#{first_frame}" type="frame"/></v:rect>)
+        html << %Q(<v:oval fill="t" strokecolor="white" strokeweight="4px" style="position:absolute;left:#{outlook_left};top:"#{outlook_top};width:#{outlook_arrow_size};height:#{outlook_arrow_size}"><v:fill color="black" opacity="30%" /></v:oval>)
+        html << %q(<v:shape coordsize="24,32" path="m,l,32,24,16,xe" fillcolor="white" stroked="f" style="position:absolute;left:289;top:151;width:30;height:34;" />)
+        html << '</v:group>'
+        html << '<![endif]-->'
+
+        # Will hold any CSS styles, if there are some necessary
+        # to inject into the email.
+        styles = []
+
+        # If this is the first video clip in the email, we need
+        # to include the general styles shared across all clips.
+        if uid == 1
+          styles << ".#{hover_klass}:hover .#{play_button_klass} {"
+          styles << '  transform: scale(1.1);'
+          styles << '}'
+          styles << ".#{hover_klass}:hover tr {"
+          styles << '  background-color: rgba(255, 255, 255, .2);'
+          styles << '}'
+        end
+
+        # If this video clip has animation, then we need to include
+        # the keyframes necessary to smoothly animate between each.
+        if has_animation
+
+          # The time spent in each frame is based on a weighted distribution
+          # of frames vs. transition time between frames.
+          total_weight = ((FRAME_WEIGHT * frame_count) + (TRANSITION_WEIGHT * frame_count)).to_f
+          percent_per_frame = (FRAME_WEIGHT / total_weight * 100.0).round
+          percent_per_transition = (TRANSITION_WEIGHT / total_weight * 100.0).round
+
+          # This will hold the total percentage as we increment toward the
+          # end of the animation.
+          percent = 0.0
+
+          keyframes = Animation::Keyframes.new(animation_name, ctx)
+
+          # Iterate through each frame and add two keyframes, the first
+          # being the time at which the frame appears plus another frame
+          # after the duration it should be on screen.
+          frames.each do |f|
+            this_frame_url = "url(#{f})"
+
+            keyframes.add_keyframe(percent, { BACKGROUND_IMAGE => this_frame_url })
+            percent += percent_per_frame
+            keyframes.add_keyframe(percent, { BACKGROUND_IMAGE => this_frame_url })
+            percent += percent_per_transition
+
+          end
+
+          # Transition back to the first frame.
+          keyframes.add_keyframe(100, { BACKGROUND_IMAGE => "url(#{first_frame})" })
+
+          # Add the keyframes to the styles array.
+          styles << keyframes.to_s
+
+        end
+
+        # Add the styles to the email's header
+        ctx.styles << styles.join("\n") unless styles.blank?
+
+        html.join("\n")
+
+      end
+
+      private
+
+      # Name of the attribute that controls the size of the play button arrow.
+      PLAY_ARROW_SIZE = :'play-size'
+
+      # Name of the boolean attribute that can be provided to disable the
+      # preloading of images in an animation.
+      NO_PRELOAD = :'no-preload'
+
+      # Constants defining the weight of a frame relative to the weight of
+      # the transition.  In this case, 2-to-1 means each frame will be on
+      # the screen for twice as long as it takes to transition between
+      # them.
+      FRAME_WEIGHT = 2.0
+      TRANSITION_WEIGHT = 1.0
+
+      # Scale applied to the width of the image to preserve the aspect
+      # ratio of the video that fluidly scales on mobile devices.
+      SCALE = 0.25
+
+    end
+  end
+end
+