inkcite 1.0.0

data/lib/inkcite/renderer/image.rb

@@ -0,0 +1,95 @@
+module Inkcite
+  module Renderer
+    class Image < ImageBase
+
+      def render tag, opt, ctx
+
+        img = Element.new('img', { :border => 0 })
+
+        # Ensure that height and width are defined in the image's attributes.
+        mix_dimensions img, opt
+
+        # Get the fully-qualified URL to the image or placeholder image if it's
+        # missing from the images directory.
+        img[:src] = image_url(opt[:src], opt, ctx)
+
+        mix_background img, opt
+
+        # Check to see if there is alt text specified for this image.  We are
+        # testing against nil because sometimes the author desires an empty
+        # alt-text attribute.
+        alt = opt[:alt]
+        if alt
+
+          # Ensure that the alt-tag has quotes around it.
+          img[:alt] = quote(alt)
+
+          # The rest of this logic is only appropriate if the alt text
+          # is not blank.
+          unless alt.blank?
+
+            # Copy the text to the title attribute if enabled for this issue
+            img[:title] = img[:alt] if ctx.is_enabled?(COPY_ALT_TO_TITLE)
+
+            # All images with alt text inherit small font unless otherwise specified.
+            opt[:font] ||= 'small'
+
+            mix_font img, opt, ctx
+
+          end
+
+        end
+
+        # Images default to block display to prevent unexpected margins in Gmail
+        # http://www.campaignmonitor.com/blog/post/3132/how-to-stop-gmail-from-adding-a-margin-to-your-images/
+        display = opt[:display] || BLOCK
+        img.style[:display] = display unless display == DEFAULT
+
+        # True if the designer wants this image to flow inline.  When true it
+        # vertically aligns the image with the text.
+        inline = (display == INLINE)
+
+        align = opt[:align] || ('absmiddle' if inline)
+        img[:align] = align unless align.blank?
+
+        valign = opt[:valign] || ('middle' if inline)
+        img.style[VERTICAL_ALIGN] = valign unless valign.blank?
+
+        mobile_src = opt[:'mobile-src']
+        unless mobile_src.blank?
+
+          # Get a unique CSS class name that will be used to swap in the alternate
+          # image on mobile.
+          klass = klass_name(mobile_src, ctx)
+
+          # Fully-qualify the image URL.
+          mobile_src = image_url(mobile_src, opt, ctx)
+
+          # Add a responsive rule that replaces the image with a different source
+          # with the same dimensions.  Warning, this isn't supported on earlier
+          # versions of iOS 6 and Android 4.
+          # http://www.emailonacid.com/forum/viewthread/404/
+          ctx.media_query << img.add_rule(Rule.new(tag, klass, "content: url(#{mobile_src}) !important;"))
+
+        end
+
+        mobile = opt[:mobile]
+
+        # Check to see if this image is inside of a mobile-image declaration.
+        # If so, the image defaults to hide on mobile.
+        mobile = HIDE if mobile.blank? && !ctx.parent_opts(:mobile_image).blank?
+
+        mix_responsive img, opt, ctx, mobile
+
+        img.to_s
+      end
+
+      private
+
+      # Name of the property controlling whether or not the alt text should
+      # be copied to the title field.
+      COPY_ALT_TO_TITLE = :'copy-alt-to-title'
+
+    end
+  end
+end

data/lib/inkcite/renderer/image_base.rb

@@ -0,0 +1,82 @@
+module Inkcite
+  module Renderer
+    class ImageBase < Responsive
+
+      protected
+
+      # Display mode constants
+      BLOCK   = 'block'
+      DEFAULT = 'default'
+      INLINE  = 'inline'
+
+      def image_url _src, opt, ctx
+
+        src = _src
+
+        # True if dimensions are missing.
+        missing_dimensions = missing_dimensions?(opt)
+
+        # Fully-qualify the image path for this version of the email unless it
+        # is already includes a full address.
+        unless src.include?('://')
+
+          # Verify that the image exists.
+          if ctx.assert_image_exists(src) || ctx.is_disabled?(Inkcite::Email::IMAGE_PLACEHOLDERS)
+
+            if missing_dimensions
+              # TODO read the image dimensions from the file and auto-populate
+              # the width and height fields.
+            end
+
+            # Convert the source (e.g. "cover.jpg") into a fully-qualified reference
+            # to the image.  In development this may be images/cover.jpg but in the
+            # other environments this would likely be a full URL to the image where it
+            # is being hosted.
+            src = ctx.image_url(src)
+
+          elsif DIMENSIONS.all? { |dim| opt[dim].to_i > MINIMUM_DIMENSION_FOR_PLACEHOLDER }
+
+            # As a convenience, replace missing images with placehold.it as long as they
+            # meet the minimum dimensions.  No need to spam the design with tiny, tiny
+            # placeholders.
+            src = "http://placehold.it/#{opt[:width]}x#{opt[:height]}#{File.extname(src)}"
+
+            # Check to see if the designer specified FPO text for this placeholder -
+            # otherwise default to the dimensions of the image.
+            fpo = opt[:fpo]
+            src << "&text=#{URI::encode(fpo)}" unless fpo.blank?
+
+          end
+
+        end
+
+        # Don't let an image go into production without dimensions.  Using the original
+        # src so that we don't display the verbose qualified URL to the developer.
+        ctx.error('Missing image dimensions', { :src => _src }) if missing_dimensions
+
+        quote(src)
+      end
+
+      def klass_name src, ctx
+        klass = "i%02d" % ctx.unique_id(:i)
+      end
+
+      def missing_dimensions? att
+        DIMENSIONS.any? { |dim| att[dim].to_i <= 0 }
+      end
+
+      def mix_dimensions img, opt
+        DIMENSIONS.each { |dim| img[dim] = opt[dim].to_i }
+      end
+
+      private
+
+      # Both the height and width of the image must exceed this amount in order
+      # to get a placehold.it automatically inserted.  Otherwise only an error
+      # is raised for missing images.
+      MINIMUM_DIMENSION_FOR_PLACEHOLDER = 25
+
+    end
+  end
+end
+

data/lib/inkcite/renderer/in_browser.rb

@@ -0,0 +1,38 @@
+
+module Inkcite
+  module Renderer
+    class InBrowser < Base
+
+      def render tag, opt, ctx
+
+        # You can only view in-browser if we're viewing an email.
+        return nil unless ctx.email?
+
+        url = ctx[Inkcite::Email::VIEW_IN_BROWSER_URL]
+        return nil if url.blank?
+
+        browser_view = ctx.email.view(ctx.environment, :browser, ctx.version)
+
+        # Make sure we're converting any embedded values in the host URL
+        url = Renderer.render(url, browser_view)
+
+        # Optional link override color.
+        color = opt[:color]
+
+        # Optional call-to-action override - otherwise defaults to view in browser.
+        cta = opt[:cta] || 'View in Browser'
+
+        id = opt[:id] || 'in-browser'
+
+        html = "{a id=\"#{id}\" href=\"#{url}\""
+        html << " color=\"#{color}\"" unless color.blank?
+        html << '}'
+        html << cta
+        html << '{/a}'
+
+        html
+      end
+
+    end
+  end
+end

data/lib/inkcite/renderer/like.rb

@@ -0,0 +1,73 @@
+module Inkcite
+  module Renderer
+    class Like < Base
+
+      def render tag, opt, ctx
+
+        # Handle the case where we're building the hosted version of the email and
+        # JavaScript is used to trigger the Facebook like dialog.
+        if ctx.browser?
+
+          return '{/a}' if tag == '/like'
+
+          page = opt[:page]
+          if page.blank?
+            ctx.error("Like tag missing 'page' attribute")
+
+          else
+
+            brand = opt[:brand] || 'Us'
+
+            # Add an externally-hosted script to the context.
+            ctx.scripts << URI.parse('http://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js')
+
+            # Add the java script to be embedded.
+            ctx.scripts << URI.parse('file://facebook-like.js')
+
+            # Add the Facebook like stylesheet.
+            ctx.styles << URI.parse('file://facebook-like.css')
+
+            ctx.footer << <<-eos
+              <div id="dialog-wrap">
+                <div id="dialog">
+                  <h2>Like #{brand} on Facebook</h2>
+                  <div id="dialog-content" class='loading'>
+                    <div class="fb-like" data-href="http://www.facebook.com/#{page}" data-send="true" data-height="100" data-width="450" data-show-faces="true"></div>
+                  </div>
+                  <div id="dialog-buttons">
+                    <a href=# onclick="return closeLike();"><span>Close</span></a>
+                  </div>
+                </div>
+              </div>
+
+              <div id="fb-root"></div>
+            eos
+
+          end
+
+          '{a href=# onclick="return openLike();"}'
+
+        else
+
+          url = ctx[Inkcite::Email::VIEW_IN_BROWSER_URL]
+          unless url.blank?
+
+            return '{/a}' if tag == '/like'
+
+            # Otherwise, link to the hosted version of the email with the like hash tag
+            # to trigger like automatically on arrival.
+            href = Inkcite::Renderer.render(ctx[Inkcite::Email::VIEW_IN_BROWSER_URL] + '#like', ctx)
+
+            id = opt[:id]
+
+            "{a id=\"#{id}\" href=\"#{href}\"}"
+          end
+
+        end
+
+      end
+
+    end
+  end
+end
+

data/lib/inkcite/renderer/link.rb

@@ -0,0 +1,243 @@
+module Inkcite
+  module Renderer
+    class Link < Responsive
+
+      def render tag, opt, ctx
+
+        tag_stack = ctx.tag_stack(:a)
+
+        if tag == '/a'
+
+          # Grab the attributes of the opening tag.
+          opening = tag_stack.pop
+
+          # Nothing to do in the
+          return '' if ctx.text?
+
+          html = '</a>'
+
+          # Check to see if the declaration has been marked as a block
+          # element and if so, close the div.
+          html << '</div>' if opening[:block]
+
+          return html
+        end
+
+        # Push the link's options onto the tag stack so that we can have
+        # access to its attributes when we close it.
+        tag_stack << opt
+
+        # Get the currently open table cell and see if link color is
+        # overridden in there.
+        td_parent = ctx.tag_stack(:td).opts
+        table_parent = ctx.tag_stack(:table).opts
+
+        # Choose a color from the parameters or inherit from the parent td, table or context.
+        opt[:color] = detect(opt[:color], td_parent[:link], table_parent[:link], ctx[LINK_COLOR])
+
+        a = Element.new('a')
+
+        mix_font a, opt, ctx
+
+        id   = opt[:id]
+        href = opt[:href]
+
+        # True if the href is missing.  If so, we may try to look it up by it's ID
+        # or we'll insert a default TBD link.
+        missing = href.blank?
+
+        # True if it's a link deeper into the content.
+        hash = !missing && href.starts_with?(POUND_SIGN)
+
+        # True if this is a mailto link.
+        mailto = !missing && !hash && href.starts_with?(MAILTO)
+
+        # Only perform special processing on the link if it's TBD or not a link to
+        # something in the page.
+        unless hash || mailto
+
+          if id.blank?
+
+            # Generate a placeholder ID and warn the user about it.
+            id = "link#{ctx.links.size + 1}"
+            ctx.error 'Link missing ID', { :href => href }
+
+          else
+
+            # Check to see if we've encountered an auto-incrementing link ID (e.g. event++)
+            # Replace the ++ with a unique count for this ID prefix.
+            id = id.gsub(PLUS_PLUS, ctx.unique_id(id).to_s) if id.end_with?(PLUS_PLUS)
+
+          end
+
+          # Get the HREF that we have previously encountered for this ID.  When not blank
+          # we'll sanity check that the URL is the same.
+          last_href = ctx.links[id]
+
+          if missing
+
+            # If we don't have a URL, check to see if we've encountered this
+            href = last_href || ctx[MISSING_LINK_HREF]
+
+            ctx.error "Link missing href", { :id => id } unless last_href
+
+          else
+
+            # Optionally tag the link's query string for post-send log analytics.
+            href = add_tagging(id, href, ctx)
+
+            if last_href.blank?
+
+              # Associate the href with it's ID in case we bump into this link again.
+              ctx.links[id] = href
+
+            elsif last_href != href
+
+              # It saves everyone a lot of time if you alert them that an ID appears multiple times
+              # in the email and with mismatched URLs.
+              ctx.error "Link href mismatch", { :id => id, :expected => last_href, :found => href }
+
+            end
+
+          end
+
+          # Optionally replace the href with an ESP trackable url.  Gotta do this after
+          # the link has been stored in the context because we don't want trackable
+          # URLs interfering with the links file.
+          href = add_tracking(id, href, ctx)
+
+          a[:target] = BLANK
+
+        end
+
+        # Make sure that these types of links have quotes.
+        href = quote(href) unless ctx.text?
+
+        # Set the href attribute to the resolved href.
+        a[:href] = href
+
+        # Links never get any text decoration.
+        a.style[TEXT_DECORATION] = NONE
+
+        if ctx.browser?
+
+          # Programmatically we can install onclick listeners for hosted versions.
+          # Check to see if one is specified and the Javascript is permitted in
+          # this version.
+          onclick = opt[:onclick]
+          a[:onclick] = quote(onclick) unless onclick.blank?
+
+        end
+
+        html = ''
+
+        if ctx.text?
+          html << a[:href]
+
+        else
+
+          klass = opt[:class]
+          a.classes << klass unless klass.blank?
+
+          mix_responsive a, opt, ctx
+
+          # Some responsive modes (e.g. button) change the display type from in-line
+          # to block.  This change can cause unexpected whitespace or other unexpected
+          # layout changes.  Outlook doesn't support block display on link elements
+          # so the best workaround is simply to wrap the element in <div> tags.
+          if a.responsive_styles.any?(&:block?)
+            html << '<div>'
+
+            # Remember that we made this element block-display so that we can append
+            # the extra div when we close the tag.
+            opt[:block] = true
+
+          end
+
+          html << a.to_s
+
+        end
+
+        html
+      end
+
+      private
+
+      # Property controlling where missing links are pointed.
+      MISSING_LINK_HREF = :'missing-link-url'
+
+      # The configuration name of the field that holds the query parameter that
+      # will be tacked onto the end of all links.
+      TAG_LINKS = :'tag-links'
+
+      # The configuration name of the field that holds the domain name(s) for
+      # links that will be tagged.
+      TAG_LINKS_DOMAIN = :'tag-links-domain'
+
+      # The property name used to indicate that links in this email should be
+      # replaced with [trackable URLs].
+      TRACK_LINKS = :'track-links'
+
+      # Value to open links in a new window.
+      BLANK = '_blank'
+
+      MAILTO = 'mailto:'
+
+      # Signifies an auto-incrementing link ID.
+      PLUS_PLUS = '++'
+
+      def add_tagging id, href, ctx
+
+        # Check to see if we're tagging links.
+        tag = ctx[TAG_LINKS]
+        unless tag.blank?
+
+          # Blank tag domain means tag all the links - otherwise, make sure the
+          # href matches the desired domain name.
+          tag_domain = ctx[TAG_LINKS_DOMAIN]
+          if tag_domain.blank? || href =~ /^https?:\/\/[^\/]*#{tag_domain}/
+
+            # Prepend it with a question mark or an ampersand depending on the current
+            # state of the lin.
+            stag = href.include?('?') ? '&' : '?'
+            stag << replace_tag(tag, id, ctx)
+
+            # Inject before the pound sign if present - otherwise, just tack it on
+            # to the end of the href.
+            if hash = href.index(POUND_SIGN)
+              href[hash..0] = stag
+            else
+              href << stag
+            end
+
+          end
+
+        end
+
+        href
+      end
+
+      def add_tracking id, href, ctx
+
+        # Check to see if a trackable link string has been defined.
+        tracking = ctx[Inkcite::Email::TRACK_LINKS]
+
+        # Replace the fully-qualified URL with a tracking tag - presuming that the
+        # ESP will replace this href with it's own trackable URL at deployment.
+        href = URI.encode(replace_tag(tracking, id, ctx)) unless tracking.blank?
+
+        href
+      end
+
+      def replace_tag tag, id, ctx
+
+        # Inject the link's ID into the tag - that's the only value that can't
+        # be resolved from the context.
+        tag = tag.gsub('{id}', id)
+
+        Inkcite::Renderer.render(tag, ctx)
+      end
+
+    end
+  end
+end