inkcite 1.12.1 → 1.13.0

data/lib/inkcite/renderer/snow.rb

@@ -1,278 +1,83 @@
 module Inkcite
   module Renderer
-    class Snow < ContainerBase
+    class Snow < SpecialEffect
 
-      # Ambient snow special effect renderer courtesy of
-      # http://freshinbox.com/blog/ambient-animations-in-email-snow-and-stars/
-      def render tag, opt, ctx
+      protected
 
-        return '</div>' if tag == '/snow'
+      def config_all_children_style style, sfx
 
-        # Get a unique ID for this wrap element.
-        uid = ctx.unique_id(:snow)
+        style[:top] = "-#{px(sfx.max_size + 4)}"
 
-        # Total number of flakes to animate
-        flakes = (opt[:flakes] || 3).to_i
+      end
+
+      def config_child n, child, style, animation, sfx
+
+        speed = sfx.rand_speed
+
+        size = sfx.rand_size
+        style[:width] = px(size)
+        style[:height] = px(size)
+        style[BORDER_RADIUS] = px((size / 2.0).round) if sfx.src.blank?
 
-        # This is the general class applied to all snow elements within this
-        # wrapping container.
-        all_flakes_class = ctx.development? ? "snow#{uid}-flakes" : "s#{uid}fs"
-        flake_prefix = ctx.development? ? "snow#{uid}-flake" : "s#{uid}f"
-        anim_prefix = ctx.development? ? "snow#{uid}-anim" : "s#{uid}a"
+        opacity = sfx.rand_opacity
+        style[:opacity] = opacity if opacity < OPACITY_CEIL
 
-        # Grab the min and max sizes for the flakes or inherit default values.
-        flake_min_size = (opt[FLAKE_SIZE_MIN] || 6).to_i
-        flake_max_size = (opt[FLAKE_SIZE_MAX] || 18).to_i
+        animation.duration = speed
+        animation.delay = ((sfx.time / sfx.count) * n).round(1)
+        animation.timing_function = Animation::LINEAR
 
-        # Grab the min and max speeds for the flakes, the smaller the value the
-        # faster the flake moves.
-        flake_min_speed = (opt[FLAKE_SPEED_MIN] || 3).to_f
-        flake_max_speed = (opt[FLAKE_SPEED_MAX] || 8).to_f
+        start_left = sfx.positions_x[n]
 
         # Determine the spread of the flakes - the bigger the spread, the larger
         # the variance between where the flake starts and where it ends.
         # Measured in %-width of the overall area.
-        spread = (opt[:spread] || 20).to_i
+        spread = sfx.opt[:spread].to_i
         half_spread = spread / 2.0
-
-        # Determine the opacity variance.
-        flake_min_opacity = (opt[FLAKE_OPACITY_MIN] || 0.5).to_f
-        flake_max_opacity = (opt[FLAKE_OPACITY_MAX] || 0.9).to_f
-
-        # Overall time for the initial distribution of flakes.
-        end_time = (opt[:time] || 4).to_f
-
-        # Setup some ranges for easier random numbering.
-        size_range = (flake_min_size..flake_max_size)
-        speed_range = (flake_min_speed..flake_max_speed)
         spread_range = (-half_spread..half_spread)
-        opacity_range = (flake_min_opacity..flake_max_opacity)
-
-        # Snowflake color.
-        color = hex(opt[:color] || '#fff')
-
-        # Check to see if a source image has been specified for the snowflakes.
-        src = opt[:src]
-
-        # If the image is missing, record an error to the console and
-        # clear the image allowing the color to take precedence instead.
-        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
-        # boolean rotate and rotation
-        rotation_enabled = src && (opt[:rotate] || opt[:rotation])
-
-        # Initialize the wrap that will hold each of the snowflakes and the
-        # content within that will have it's
-        div_wrap = Element.new('div')
-
-        # Resolve the wrapping class name - readable name in development,
-        # space-saving name in all other environments.
-        wrap_class = ctx.development? ? "snow#{uid}-wrap" : "s#{uid}w"
-        div_wrap[:class] = wrap_class
-
-        # Background color gets applied directly to the div so it renders
-        # consistently in all clients - even those that don't support the
-        # 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
-
-        # Get the number of flakes that should be included.  Create a child div for
-        # each flake that can be sized, animated uniquely.
-        flakes.times do |flake|
-          html << %Q(<div class="#{all_flakes_class} #{flake_prefix}#{flake + 1}"></div>)
-        end
-
-        # Check to see if there is a height required for the wrap element - otherwise
-        # the wrap will simply enlarge to hold all of the contents within.
-        wrap_height = opt[:height].to_i
-
-        # Will hold all of the styles as they're assembled.
-        style = []
-
-        # True if we're limiting the animation to webkit only.  In development
-        # or in the browser version of the email, the animation should be as
-        # compatible as possible but in all other cases it should be webkit only.
-        webkit_only = !(ctx.development? || ctx.browser?)
-
-        # Hide the snow effect from any non-webkit email clients.
-        style << '@media screen and (-webkit-min-device-pixel-ratio: 0) {' if webkit_only
-
-        # Snow wrapping element in-which the snow flakes will be animated.
-        style << "  .#{wrap_class} {"
-        style << '    position: relative;'
-        style << '    overflow: hidden;'
-        style << '    width: 100%;'
-        style << "    height: #{px(wrap_height)};" if wrap_height > 0
-        style << '  }'
-
-        # Common attributes for all snowflakes.
-        style << "  .#{all_flakes_class} {"
-        style << '    position: absolute;'
-        style << "    top: -#{flake_max_size + 4}px;"
-
-        # If no image has been provided, make the background a solid color
-        # otherwise set the background to the image source and fill the
-        # available space.
-        if src.blank?
-          style << "    background-color: #{color};"
-        else
-          style << "    background-image: url(#{ctx.image_url(src)});"
-          style << "    background-size: 100%;"
-        end
-
-        style << '  }'
-
-        # Space the snowflakes generally equally across the width of the
-        # container div.  Random distribution sometimes ends up with
-        # snowflakes clumped at one edge or the other.
-        flake_spacing = 100 / flakes.to_f
-
-        # Now build up a pool of equally-spaced starting positions.
-        # TODO: This is probably a perfect spot to use inject()
-        start_left = flake_spacing / 2.0
-        start_positions = [start_left]
-        (flakes - 1).times { |f| start_positions << start_left += flake_spacing }
 
-        # Randomize the starting positions - otherwise they draw right-to-left
-        # as starting positions are popped from the pool.
-        start_positions.shuffle!
-
-        # Snowflakes will be dispersed equally across the total time
-        # of the animation making for a smoother, more balanced show.
-        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 = flake_sizes[flake] = rand(size_range)
-
-          opacity = rand(opacity_range).round(1)
-          if opacity < OPACITY_FLOOR
-            opacity = OPACITY_FLOOR
-          elsif opacity > OPACITY_CEIL
-            opacity = OPACITY_CEIL
-          end
-
-          style << "  .#{flake_prefix}#{flake + 1} {"
-          style << "    height: #{px(size)};"
-          style << "    width: #{px(size)};"
-
-          # Only apply a border radius if the snowflake lacks an image.
-          style << "    border-radius: #{px((size / 2.0).round)};" unless src
-
-          style << "    opacity: #{opacity};" if opacity < OPACITY_CEIL
-          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
+        # Randomly choose where the snow will end its animation.  Prevent
+        # it from going outside of the container.
+        end_left = (start_left + rand(spread_range)).round
+        if end_left < POSITION_FLOOR
+          end_left = POSITION_FLOOR
+        elsif end_left > POSITION_CEIL
+          end_left = POSITION_CEIL
         end
 
-        # Declare each of the flake animations.
-        flakes.times do |flake|
-
-          start_left = start_positions.pop
-
-          # Randomly choose where the snow will end its animation.  Prevent
-          # it from going outside of the container.
-          end_left = (start_left + rand(spread_range)).round
-          if end_left < POSITION_FLOOR
-            end_left = POSITION_FLOOR
-          elsif end_left > POSITION_CEIL
-            end_left = POSITION_CEIL
-          end
-
-          # Calculate the ending rotation for the flake, if rotation is enabled.
-          end_rotation = rotation_enabled ? rand(ROTATION_RANGE) : 0
+        # Calculate the ending rotation for the flake, if rotation is enabled.
+        end_rotation = sfx.rotation?? sfx.rand_rotation : 0
 
-          keyframes = Animation::Keyframes.new("#{anim_prefix}#{flake + 1}", ctx)
+        # Start above the div area
+        animation.add_keyframe(0, { :top => px(-size), :left => pct(start_left.round) })
 
-          # 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 << keyframes.to_s
-
-        end
-
-        style << '}' if webkit_only
-
-        ctx.styles << style.join("\n")
-
-        html
+        # End below the div area, applying rotation if necessary.
+        keyframe = animation.add_keyframe(100, { :top => '100%', :left => pct(end_left) })
+        keyframe[:transform] = "rotate(#{end_rotation}deg)" if end_rotation != 0
 
       end
 
-      private
-
-      # Renders the CSS with the appropriate browser prefixes based
-      # on whether or not this version of the email is webkit only.
-      def with_browser_prefixes indentation, css, webkit_only, separator="\n"
-
-        # Determine which prefixes will be applied.
-        browser_prefixes = webkit_only ? WEBKIT_BROWSERS : ALL_BROWSERS
-
-        # This will hold the completed CSS with all prefixes applied.
-        _css = ''
+      def config_effect_context sfx
 
-        # Iterate through the prefixes and apply them with the indentation
-        # and CSS declaration with line breaks.
-        browser_prefixes.each do |prefix|
-          _css << indentation
-          _css << prefix
-          _css << css
-          _css << separator
-        end
+        # Shuffle the x-positions so that the snowflakes fall across
+        # the container's width in random order.
+        sfx.positions_x.shuffle!
 
-        _css
       end
 
-      # Size constraints on the flakes.
-      FLAKE_SIZE_MIN = :'min-size'
-      FLAKE_SIZE_MAX = :'max-size'
-
-      # Speed constraints on the flakes.
-      FLAKE_SPEED_MIN = :'min-speed'
-      FLAKE_SPEED_MAX = :'max-speed'
-
-      # Opacity constraints.
-      FLAKE_OPACITY_MIN = :'min-opacity'
-      FLAKE_OPACITY_MAX = :'max-opacity'
-      OPACITY_FLOOR = 0.2
-      OPACITY_CEIL = 1.0
-
-      # Rotation angles when image rotation is enabled.
-      ROTATION_RANGE = (-270..270)
-
-      # Position min and max preventing snow flakes
-      # from leaving the bounds of the container.
-      POSITION_FLOOR = 0
-      POSITION_CEIL = 100
-
-      # Static arrays with browser prefixes.  Turns out that
-      # Firefox, IE and Opera don't require a prefix so to
-      # target everything we need the non-prefixed version
-      # (hence the blank entry) plus the webkit prefix.
-      WEBKIT_BROWSERS = ['-webkit-']
-      ALL_BROWSERS = [''] + WEBKIT_BROWSERS
+      def defaults opt, ctx
+        {
+            :color => '#fff',
+            :count => 3,
+            SIZE_MIN => 6,
+            SIZE_MAX => 18,
+            SPEED_MIN => 3,
+            SPEED_MAX => 8,
+            :spread => 20,
+            OPACITY_MIN => 0.5,
+            OPACITY_MAX => 0.9,
+            :time => 4
+        }
+      end
 
     end
 

data/lib/inkcite/renderer/sparkle.rb

@@ -0,0 +1,77 @@
+module Inkcite
+  module Renderer
+    class Sparkle < SpecialEffect
+
+      protected
+
+      def config_child n, child, style, animation, sfx
+
+        # Random size
+        size = sfx.rand_size
+        style[:height] = px(size)
+        style[:width] = px(size)
+        style[BORDER_RADIUS] = px((size / 2).round) unless sfx.src
+
+        # Random opacity
+        opacity = sfx.rand_opacity
+        style[:opacity] = opacity if opacity < OPACITY_CEIL
+
+        # Random position
+        style[:top] = pct(sfx.positions_y[n].round(0))
+        style[:left] = pct(sfx.positions_x[n].round(0))
+
+        # Calculate the ending rotation for the flake, if rotation is enabled.
+        end_rotation = sfx.rotation? ? sfx.rand_rotation : 0
+        half_rotation = (end_rotation / 2.0).round(1)
+
+        #animation.timing_function = Animation::EASE
+
+        speed = sfx.rand_speed
+
+        max_delay = speed * 0.1
+        delay = rand(max_delay).round(1)
+        animation.duration = (speed + delay).round(1)
+
+        delay_percent = 100 - ((delay / animation.duration) * 100).round(0)
+        midpoint_percent = (delay_percent / 2.0).round(0)
+
+        # Start above the div area
+        keyframe = animation.add_keyframe(0, { :transform => 'scale(0.0)' })
+        keyframe.append(:transform, "rotate(0deg)") if half_rotation != 0
+
+        keyframe = animation.add_keyframe(midpoint_percent, { :transform => 'scale(1.0)' })
+        keyframe.append(:transform, "rotate(#{half_rotation}deg)") if half_rotation != 0
+
+        keyframe = animation.add_keyframe(delay_percent, { :transform => 'scale(0.0)' })
+        keyframe.append(:transform, "rotate(#{end_rotation}deg)") if end_rotation != 0
+
+        keyframe = animation.add_keyframe(100, { :transform => 'scale(0.0)' })
+        keyframe.append(:transform, "rotate(#{end_rotation}deg)") if end_rotation != 0
+
+      end
+
+      def config_effect_context sfx
+
+        # Randomly shuffle the x- and y-positions for the sparkles.
+        sfx.positions_x.shuffle!
+        sfx.positions_y.shuffle!
+
+      end
+
+      def defaults opt, ctx
+        {
+            :count => 6,
+            :color => '#fff',
+            OPACITY_MIN => 0.33,
+            OPACITY_MAX => 1.0,
+            SIZE_MIN => 6,
+            SIZE_MAX => 24,
+            SPEED_MIN => 0.5,
+            SPEED_MAX => 2.0,
+            :time => 4
+        }
+      end
+
+    end
+  end
+end

data/lib/inkcite/renderer/special_effect.rb

@@ -0,0 +1,429 @@
+module Inkcite
+  module Renderer
+    class SpecialEffect < ContainerBase
+
+      # A convenience class for accessing the attributes that are
+      # common to special effects like snow and sparkle.
+      class EffectContext
+
+        attr_reader :uuid
+
+        # Expose the opt and ctx attributes
+        attr_reader :opt, :ctx
+
+        # Allow sfx to be treated equivalent to the options map it wraps.
+        # This makes it easy for the consumer to set custom state into
+        # the context (during config_effect_context) and then use those
+        # values during the rendering methods.
+        delegate :[], :[]=, :to => :opt
+
+        def initialize tag, opt, ctx, defaults={}
+
+          @tag = tag
+
+          # Merge the provided opts over the defaults to ensure the values
+          # provided by the developer take precedence.
+          @opt = defaults.merge(opt)
+          @ctx = ctx
+
+          # Request a unique ID for this special effect which will be used
+          # to uniquely identify the classes and animations associated with
+          # this special effect.
+          @uuid = ctx.unique_id(:sfx)
+
+        end
+
+        def all_children_class_name
+          obfuscate_class_names? ? "sfx#{@uuid}c" : "#{@tag}#{@uuid}-children"
+        end
+
+        def animation_class_name child_index
+          obfuscate_class_names? ? "#{@tag}#{@uuid}-anim#{child_index + 1}" : "sfx#{@uuid}a#{child_index + 1}"
+        end
+
+        def child_class_name child_index
+          obfuscate_class_names? ? "sfx#{@uuid}c#{child_index + 1}" : "#{@tag}#{@uuid}-child#{child_index + 1}"
+        end
+
+        def color
+          Renderer.hex(@opt[:color])
+        end
+
+        # Returns the number of children in the special effects - e.g. the number
+        # of snowflakes or sparkles in the animation.  :flakes and :sparks are
+        # technically deprecated.
+        def count
+          (@opt[:sparks] || @opt[:flakes] || @opt[:count]).to_i
+        end
+
+        def equal_distribution qty
+
+          # Space the children generally equally across the width of the
+          # container div.  Random distribution sometimes ends up with
+          # children clumped at one edge or the other.
+          spacing = POSITION_CEIL / qty.to_f
+
+          # Now build up a pool of equally-spaced starting positions.
+          # TODO: This is probably a perfect spot to use inject()
+          start_left = spacing / 2.0
+
+          # This array will hold all of the positions
+          positions = [start_left]
+
+          # Now, for the remaining positions needed, adjust by the
+          # spacing and push onto the list.
+          (qty - 1).times { |f| positions << start_left += spacing }
+
+          positions
+        end
+
+        def height
+          @opt[:height].to_i
+        end
+
+        def max_opacity
+          @opt[OPACITY_MAX].to_f
+        end
+
+        def max_size
+          @opt[SIZE_MAX].to_i
+        end
+
+        def min_opacity
+          @opt[OPACITY_MIN].to_f
+        end
+
+        def max_speed
+          @opt[SPEED_MAX].to_f
+        end
+
+        def min_size
+          @opt[SIZE_MIN].to_i
+        end
+
+        def min_speed
+          @opt[SPEED_MIN].to_f
+        end
+
+        def obfuscate_class_names?
+          false && @ctx.production?
+        end
+
+        def opacity_range
+          (min_opacity..max_opacity)
+        end
+
+        def rand_opacity
+          rand(opacity_range).round(1)
+        end
+
+        def rand_rotation
+          rand(rotation_range).round(1)
+        end
+
+        def rand_size
+          rand(size_range).round(0)
+        end
+
+        def rand_speed
+          rand(speed_range).round(1)
+        end
+
+        def rotation?
+          @opt[:rotate] || @opt[:rotation]
+        end
+
+        def rotation_range
+          (-270..270)
+        end
+
+        def size_range
+          (min_size..max_size)
+        end
+
+        def speed_range
+          (min_speed..max_speed)
+        end
+
+        def src
+          return @src if defined?(@src)
+
+          # Check to see if a source image has been specified for the snowflakes.
+          @src = @opt[:src]
+
+          # Release the image name if one has been provided but doesn't exist in
+          # the project - this will cause the special effect to default to the
+          # non-image default behavior.
+          @src = nil if @src && !@ctx.assert_image_exists(@src)
+
+          @src
+        end
+
+        # Creates a permanent list of positions (as percentages of the wrap container's
+        # total width) which can be used for starting or ending position to equally
+        # space animated elements.
+        def positions_x
+          @positions_x ||= equal_distribution(count)
+        end
+
+        # Creates a permanent list of positions (as percentages of the wrap container's
+        # total height) which can be used for starting or ending position to equally
+        # space animated elements.
+        def positions_y
+          @positions_y ||= equal_distribution(count)
+        end
+
+        def start_time child_index
+          ((time / count) * child_index).round(1)
+        end
+
+        def time
+          @opt[:time].to_f
+        end
+
+        # Amount of time between each child starting its animation to create a
+        # even but varied distribution.
+        def time_interval
+          time / count.to_f
+        end
+
+        # Returns true if CSS animations should be limited to webkit-
+        # powered email clients.
+        def webkit_only?
+          !(@ctx.development? || @ctx.browser?)
+        end
+
+        def wrap_class_name
+          obfuscate_class_names? ? "sfx#{@uuid}w" : "#{@tag}#{@uuid}-wrap"
+        end
+
+      end
+
+      public
+
+      def render tag, opt, ctx
+
+        # If the closing tag was received (e.g. /snow) then close the wrapper
+        # div that was rendered by the opening tag.
+        return '</div>' if tag.start_with?('/')
+
+        # Retrieve the special effects default values (times, number of units, etc.)
+        _defaults = defaults(opt, ctx)
+
+        # Create a special effects context that simplifies working with the
+        # opts, defaults and manages the styles/classes necessary to animate
+        # the special effect.
+        sfx = EffectContext.new(tag, opt, ctx, _defaults)
+
+        # Provide the extending class with an opportunity to configure the
+        # effect context prior to any rendering.
+        config_effect_context sfx
+
+        html = []
+        styles = []
+
+        # If this is the first special effect to be included in the email
+        # we need to disable the CSS animation from Gmail - which only
+        # accepts part of its <styles> leading to unexpected whitespace.
+        # By putting this invalid CSS into the <style> block, Gmail's
+        # very strict parser will exclude the entire block, preventing
+        # the animation from running.
+        # https://emails.hteumeuleu.com/troubleshooting-gmails-responsive-design-support-ad124178bf81#.8jh1vn9mw
+        if ctx.email? && sfx.uuid == 1
+          styles << Inkcite::Renderer::Style.new(".gmail-fix", sfx.ctx, { FONT_SIZE => '3*px' })
+        end
+
+        # Create the <div> that wraps the entire animation.
+        create_wrap_element html, sfx
+
+        # Create the Style that defines the look of the wrapping container
+        create_wrap_style styles, sfx
+
+        # Create the Style that is applied to all children in the animation.
+        create_all_children_style styles, sfx
+
+        # Now create each of the child elements (e.g. the snowflakes) that
+        # will be animated in this effect.  Each child is created and animated
+        # at the same time.
+        create_child_elements html, styles, sfx
+
+        # Push the completed list of styles into the context's stack.
+        ctx.styles << styles.join("\n")
+
+        html.join("\n")
+
+      end
+
+      protected
+
+      # Position min and max preventing animated elements
+      # from leaving the bounds of the container.
+      POSITION_FLOOR = 0
+      POSITION_CEIL = 100
+
+      # Size constraints on the animated children.
+      SIZE_MIN = :'min-size'
+      SIZE_MAX = :'max-size'
+
+      # Speed constraints on the children.
+      SPEED_MIN = :'min-speed'
+      SPEED_MAX = :'max-speed'
+
+      # Opacity constraints on the children
+      OPACITY_MIN = :'min-opacity'
+      OPACITY_MAX = :'max-opacity'
+      OPACITY_CEIL = 1.0
+
+      # The extending class can override this method to perform any
+      # additional configuration on the style that affects all
+      # children in the animation.
+      def config_all_children_style style, sfx
+        # This space left intentionally blank
+      end
+
+      # The extending class must implement this method to customize
+      # and animate each child.
+      def config_child n, child, style, animation, sfx
+        raise 'Classes extending SpecialEffect must implement defaults(child, style, animation, keyframes, sfx)'
+      end
+
+      # The extending class can implement this method to customize
+      # the EffectContext prior to any HTML or CSS generation.
+      def config_effect_context sfx
+        # This space left intentionally blank
+      end
+
+      # The extending class can override this method to perform any
+      # additional configuration on the <div> that wraps the entire
+      # animation.
+      def config_wrap_element div, sfx
+        # This space left intentionally blank
+      end
+
+      # The extending class can override this method to customize
+      # the wrap <div>'s style.
+      def config_wrap_style style, sfx
+        # This space left intentionally blank
+      end
+
+      # The extending class must override this method and return the defaults
+      # for the special effect as a map.
+      def defaults opt, ctx
+        raise 'Classes extending SpecialEffect must implement defaults(opt, ctx)'
+      end
+
+      private
+
+      # Creates the Style that applies to /all/ children.
+      def create_all_children_style styles, sfx
+
+        style = Inkcite::Renderer::Style.new(".#{sfx.all_children_class_name}", sfx.ctx, { :position => :absolute })
+
+        # If no image has been provided, make the background a solid color
+        # otherwise set the background to the image source and fill the
+        # available space.
+        src = sfx.src
+        if src.blank?
+          color = sfx.color
+          style[BACKGROUND_COLOR] = color unless none?(color)
+        else
+          style[BACKGROUND_IMAGE] = "url(#{sfx.ctx.image_url(src)})"
+          style[BACKGROUND_SIZE] = '100%'
+        end
+
+        # Provide the extending class with a chance to apply additional
+        # styles to all children.
+        config_all_children_style style, sfx
+
+        styles << style
+
+      end
+
+      # Creates n-number of child <div> objects and assigns the all-child and each-child
+      # CSS classes to them allowing each to be sized, animated uniquely.
+      def create_child_elements html, styles, sfx
+
+        # Will hold all of the Animations while the children are
+        # assembled and then added to the styles array at the end
+        # so that all keyframes are together in the source.
+        animations = []
+
+        sfx.count.times do |n|
+
+          child_class_name = sfx.child_class_name(n)
+
+          # This is the child HTML element
+          child = Inkcite::Renderer::Element.new('div', { :class => quote("#{sfx.all_children_class_name} #{child_class_name}") })
+
+          # This is the custom style to be applied to the child.
+          style = Inkcite::Renderer::Style.new(".#{child_class_name}", sfx.ctx)
+
+          # This is the animation declaration (timing, duration, etc.) for this child.
+          animation = Inkcite::Animation.new(sfx.animation_class_name(n), sfx.ctx)
+
+          # Provide the extending class with a chance to configure the child
+          # and its style.
+          config_child n, child, style, animation, sfx
+
+          # Now that it is configured, install the animation into the
+          # style - this adds itself with the appropriate browser prefixes.
+          style[:animation] = animation
+
+          # Inject the various pieces into the appropriate lists.
+          html << child.to_s + '</div>'
+          styles << style
+          animations << animation
+
+        end
+
+        # Append all of the Keyframes to the end of the styles, now that
+        # the individual children are configured.
+        animations.each { |a| styles << a.to_keyframe_css }
+
+      end
+
+      # Creates the <div> that wraps the entire animation.  The children of this container
+      # will be animated based on the parameters of the effect.
+      def create_wrap_element html, sfx
+
+        # Initialize the wrap that will hold each of the children and wraps the content
+        # over which the special effect will animate.
+        div = Inkcite::Renderer::Element.new('div', { :class => quote(sfx.wrap_class_name) })
+
+        # Background color gets applied directly to the div so it renders consistently
+        # in all clients - even those that don't support special effects.
+        mix_background div, sfx.opt, sfx.ctx
+
+        # Text alignment within the wrapper
+        mix_text_align div, sfx.opt, sfx.ctx
+
+        # Provide the extending class with a chance to make additional
+        # configuration changes to the wrap element.
+        config_wrap_element div, sfx
+
+        html << div.to_s
+
+      end
+
+      def create_wrap_style styles, sfx
+
+        # Initialize the class declaration that will be applied to the
+        # wrapping container.
+        style = Inkcite::Renderer::Style.new(".#{sfx.wrap_class_name}", sfx.ctx, { :position => :relative, :overflow => :hidden, :width => '100%' })
+
+        # If a specific height has been specified for the wrap class, add
+        # it to the style.
+        height = sfx.height
+        style[:height] = px(height) if height > 0
+
+        # Provide the extending class with a chance to do any additional
+        # customization to this style.
+        config_wrap_style style, sfx
+
+        styles << style
+
+      end
+
+    end
+  end
+end