meta-tags 2.22.3 → 2.24.0

data/lib/meta_tags/renderer.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 module MetaTags
-  # This class is used by MetaTags gems to render HTML meta tags into page.
+  # This class is used by the MetaTags gem to render HTML meta tags on a page.
   class Renderer
     attr_reader :meta_tags, :normalized_meta_tags
 
-    # Initialized a new instance of Renderer.
-    #
-    # @param [MetaTagsCollection] meta_tags meta tags object to render.
+    # Initializes a new instance of Renderer.
     #
+    # @param meta_tags [MetaTagsCollection] meta tags object to render.
     def initialize(meta_tags)
       @meta_tags = meta_tags
       @normalized_meta_tags = {}
@@ -16,7 +15,7 @@ module MetaTags
 
     # Renders meta tags on the page.
     #
-    # @param [ActionView::Base] view Rails view object.
+    # @param view [ActionView::Base] Rails view object.
     def render(view)
       tags = [] # : Array[Tag]
 
@@ -43,8 +42,7 @@ module MetaTags
 
     # Renders charset tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_charset(tags)
       charset = meta_tags.extract(:charset)
       tags << Tag.new(:meta, charset: charset) if charset.present?
@@ -52,8 +50,7 @@ module MetaTags
 
     # Renders title tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_title(tags)
       normalized_meta_tags[:title] = meta_tags.page_title
       normalized_meta_tags[:site] = meta_tags[:site]
@@ -68,8 +65,7 @@ module MetaTags
 
     # Renders icon(s) tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_icon(tags)
       icon = meta_tags.extract(:icon)
       return unless icon
@@ -81,16 +77,16 @@ module MetaTags
 
       icon.each do |icon_params|
         icon_params = {rel: "icon", type: "image/x-icon"}.with_indifferent_access.merge(icon_params)
-        tags << Tag.new(:link, icon_params)
+        tags << Tag.new(:link, icon_params) if icon_params[:href].present?
       end
     end
 
     # Renders meta tag with normalization (should have a corresponding normalize_
     # method in TextNormalizer).
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param name [Symbol] meta tag name to normalize and render.
     # @see TextNormalizer
-    #
     def render_with_normalization(tags, name)
       value = TextNormalizer.public_send(:"normalize_#{name}", meta_tags.extract(name))
       normalized_meta_tags[name] = value
@@ -99,8 +95,7 @@ module MetaTags
 
     # Renders noindex and nofollow meta tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_noindex(tags)
       meta_tags.extract_robots.each do |name, content|
         tags << Tag.new(:meta, name: name, content: content) if content.present?
@@ -109,8 +104,7 @@ module MetaTags
 
     # Renders refresh meta tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_refresh(tags)
       refresh = meta_tags.extract(:refresh)
       tags << Tag.new(:meta, "http-equiv" => "refresh", :content => refresh.to_s) if refresh.present?
@@ -118,8 +112,7 @@ module MetaTags
 
     # Renders alternate link tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_alternate(tags)
       alternate = meta_tags.extract(:alternate)
       return unless alternate
@@ -130,15 +123,15 @@ module MetaTags
         end
       elsif alternate.is_a?(Array)
         alternate.each do |link_params|
-          tags << Tag.new(:link, {rel: "alternate"}.with_indifferent_access.merge(link_params))
+          link_params = {rel: "alternate"}.with_indifferent_access.merge(link_params)
+          tags << Tag.new(:link, link_params) if link_params[:href].present?
         end
       end
     end
 
-    # Renders open_search link tag.
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
+    # Renders the OpenSearch link tag.
     #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_open_search(tags)
       open_search = meta_tags.extract(:open_search)
       return unless open_search
@@ -152,8 +145,7 @@ module MetaTags
 
     # Renders links.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_links(tags)
       [:amphtml, :prev, :next, :image_src, :manifest].each do |tag_name|
         href = meta_tags.extract(tag_name)
@@ -164,13 +156,12 @@ module MetaTags
       end
     end
 
-    # Renders canonical link
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
+    # Renders the canonical link.
     #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_canonical_link(tags)
-      href = meta_tags.extract(:canonical) # extract, so its not used anywhere else
-      return if MetaTags.config.skip_canonical_links_on_noindex && meta_tags[:noindex]
+      href = meta_tags.extract(:canonical) # extract, so it's not used anywhere else
+      return if MetaTags.config.skip_canonical_links_on_noindex && meta_tags.noindex?
       return if href.blank?
 
       @normalized_meta_tags[:canonical] = href
@@ -179,30 +170,28 @@ module MetaTags
 
     # Renders complex hash objects.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
-    def render_hashes(tags, **opts)
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    def render_hashes(tags)
       meta_tags.meta_tags.each_key do |property|
-        render_hash(tags, property, **opts)
+        render_hash(tags, property)
       end
     end
 
     # Renders a complex hash object by key.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
-    def render_hash(tags, key, **opts)
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param key [String, Symbol] top-level meta tag key.
+    def render_hash(tags, key)
       data = meta_tags.meta_tags[key]
       return unless data.is_a?(Hash)
 
-      process_hash(tags, key, data, **opts)
+      process_hash(tags, key, data)
       meta_tags.extract(key)
     end
 
     # Renders custom meta tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_custom(tags)
       meta_tags.meta_tags.each do |name, data|
         Array(data).each do |val|
@@ -212,85 +201,136 @@ module MetaTags
       end
     end
 
-    # Recursive method to process all the hashes and arrays on meta tags
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] property a Hash or a String to render as meta tag.
-    # @param [Hash, Array, String, Symbol] content text content or a symbol reference to
-    # top-level meta tag.
+    # Recursive method to process all hashes and arrays in meta tags.
     #
-    def process_tree(tags, property, content, itemprop: nil, **opts)
-      method = case content
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param property [String, Symbol] the meta tag property name.
+    # @param content [Hash, Array, String, Symbol] text content or a symbol
+    #   reference to a top-level meta tag.
+    # @param itemprop [String, Symbol, nil] value of the itemprop attribute.
+    def process_tree(tags, property, content, itemprop: nil)
+      case content
       when Hash
-        :process_hash
+        process_hash(tags, property, content, itemprop: itemprop)
       when Array
-        :process_array
+        process_array(tags, property, content, itemprop: itemprop)
       else
-        iprop = itemprop
-        :render_tag
+        if content.is_a?(Symbol) && MetaTags.config.resolve_symbolic_references_in_arrays
+          process_reference(tags, property, content, itemprop: itemprop)
+        else
+          render_tag(tags, property, content, itemprop: itemprop)
+        end
       end
-      __send__(method, tags, property, content, itemprop: iprop, **opts)
     end
 
-    # Recursive method to process a hash with meta tags
+    # Recursive method to process a hash of meta tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] property a Hash or a String to render as meta tag.
-    # @param [Hash] content nested meta tag attributes.
-    #
-    def process_hash(tags, property, content, **opts)
-      itemprop = content.delete(:itemprop)
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param property [String, Symbol] the meta tag property name.
+    # @param content [Hash] nested meta tag attributes.
+    # @param itemprop [String, Symbol, nil] inherited itemprop value.
+    def process_hash(tags, property, content, itemprop: nil)
+      itemprop_key = content.key?(:itemprop) ? :itemprop : "itemprop"
+      current_itemprop = content.key?(itemprop_key) ? content[itemprop_key] : itemprop
+
       content.each do |key, value|
+        next if key.to_s == "itemprop"
+
         if key.to_s == "_"
-          iprop = itemprop
           key = property
+          next_itemprop = current_itemprop
         else
           key = "#{property}:#{key}"
+          next_itemprop = nil
         end
 
-        normalized_value = if value.is_a?(Symbol)
-          normalized_meta_tags[value]
+        if value.is_a?(Symbol)
+          process_reference(tags, key, value, itemprop: next_itemprop)
         else
-          value
+          process_tree(tags, key, value, itemprop: next_itemprop)
         end
-        process_tree(tags, key, normalized_value, **opts.merge(itemprop: iprop))
       end
     end
 
-    # Recursive method to process a hash with meta tags
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] property a Hash or a String to render as meta tag.
-    # @param [Array] content array of nested meta tag attributes or values.
-    #
-    def process_array(tags, property, content, **opts)
-      content.each { |v| process_tree(tags, property, v, **opts) }
+    # Recursive method to process an array of meta tags.
+    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param property [String, Symbol] the meta tag property name.
+    # @param content [Array] array of nested meta tag attributes or values.
+    # @param itemprop [String, Symbol, nil] value of the itemprop attribute.
+    def process_array(tags, property, content, itemprop: nil)
+      unless MetaTags.config.resolve_symbolic_references_in_arrays
+        symbol_reference = content.find { |value| value.is_a?(Symbol) }
+        if symbol_reference
+          MetaTags.deprecator.warn(
+            "Passing #{symbol_reference.inspect} directly inside a nested meta tag Array is deprecated. " \
+              "It is rendered literally in MetaTags 2.x but will be interpreted as a mirrored reference in MetaTags 3.0. " \
+              "Set MetaTags.config.resolve_symbolic_references_in_arrays = true to opt in now; this behavior will " \
+              "become the default in MetaTags 3.0. Use a String to keep a literal value."
+          )
+        end
+      end
+
+      content.each { |value| process_tree(tags, property, value, itemprop: itemprop) }
     end
 
-    # Recursive method to process a hash with meta tags
+    # Resolves a Symbol reference and processes its normalized value once.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] name a Hash or a String to render as meta tag.
-    # @param [String, Symbol] value text content or a symbol reference to
-    # top-level meta tag.
-    # @param [String, Symbol] itemprop value of the itemprop attribute.
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param property [String, Symbol] the meta tag property name.
+    # @param reference [Symbol] normalized top-level meta tag reference.
+    # @param itemprop [String, Symbol, nil] value of the itemprop attribute.
+    def process_reference(tags, property, reference, itemprop: nil)
+      content = normalized_meta_tags[reference]
+      case content
+      when Hash
+        process_hash(tags, property, content, itemprop: itemprop)
+      when Array
+        process_array(tags, property, content, itemprop: itemprop)
+      else
+        render_tag(tags, property, content, itemprop: itemprop)
+      end
+    end
+
+    # Renders a single meta tag.
     #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param name [String, Symbol] the meta tag name.
+    # @param value [String, Symbol] text content or a symbol reference to a
+    #   top-level meta tag.
+    # @param itemprop [String, Symbol, nil] value of the itemprop attribute.
     def render_tag(tags, name, value, itemprop: nil)
       name_key ||= configured_name_key(name)
       tags << Tag.new(:meta, name_key => name.to_s, :content => value, :itemprop => itemprop) if value.present?
     end
 
-    # Returns meta tag property name for a give meta tag based on the
+    # Returns the meta tag property name for a given meta tag based on the
     # configured list of property tags in MetaTags::Configuration#property_tags.
     #
-    # @param [String, Symbol] name tag key.
+    # @param name [String, Symbol] tag key.
     # @return [Symbol] meta tag attribute name (:property or :name).
-    #
     def configured_name_key(name)
+      name = name.to_s
       is_property_tag = MetaTags.config.property_tags.any? do |tag_name|
-        name.to_s.match(/^#{Regexp.escape(tag_name.to_s)}\b/)
+        property_tag?(name, tag_name.to_s)
       end
       is_property_tag ? :property : :name
     end
+
+    # Returns true when a configured property tag matches the exact meta tag
+    # name or the start of a colon-delimited namespace.
+    #
+    # @param name [String] rendered meta tag name.
+    # @param tag_name [String] configured property tag name or namespace prefix.
+    # @return [Boolean]
+    def property_tag?(name, tag_name)
+      return false unless name.start_with?(tag_name)
+
+      tag_name_length = tag_name.bytesize
+      return true if name.bytesize == tag_name_length
+      return true if tag_name.getbyte(tag_name_length - 1) == 58
+
+      name.getbyte(tag_name_length) == 58
+    end
   end
 end

data/lib/meta_tags/tag.rb

@@ -7,26 +7,28 @@ module MetaTags
 
     # Initializes a new instance of Tag class.
     #
-    # @param [String, Symbol] name HTML tag name
-    # @param [Hash] attributes list of HTML tag attributes
-    #
+    # @param name [String, Symbol] HTML tag name.
+    # @param attributes [Hash] list of HTML tag attributes.
     def initialize(name, attributes = {})
       @name = name.to_s
       @attributes = attributes
     end
 
-    # Render tag into a Rails view.
+    # Renders the tag in a Rails view.
     #
-    # @param [ActionView::Base] view instance of a Rails view.
+    # @param view [ActionView::Base] instance of a Rails view.
     # @return [String] HTML string for the tag.
-    #
     def render(view)
-      view.tag(name, prepare_attributes(attributes), MetaTags.config.open_meta_tags?)
+      view.tag(name, serialize_iso8601_attributes(attributes), MetaTags.config.open_meta_tags?)
     end
 
     protected
 
-    def prepare_attributes(attributes)
+    # Serializes attribute values that support ISO 8601 formatting.
+    #
+    # @param attributes [Hash] HTML tag attributes.
+    # @return [Hash] normalized HTML tag attributes.
+    def serialize_iso8601_attributes(attributes)
       attributes.each do |key, value|
         attributes[key] = value.iso8601 if value.respond_to?(:iso8601)
       end

data/lib/meta_tags/text_normalizer.rb

@@ -1,18 +1,17 @@
 # frozen_string_literal: true
 
 module MetaTags
-  # Module contains helpers that normalize text meta tag values.
+  # This module contains helpers that normalize text meta tag values.
   module TextNormalizer
     extend self
 
     # Normalize title value.
     #
-    # @param [String] site_title site title.
-    # @param [Array<String>] title title string.
-    # @param [String] separator a string to join title parts with.
-    # @param [true,false] reverse whether title should be reversed.
+    # @param site_title [String] site title.
+    # @param title [Array<String>] title segments.
+    # @param separator [String] a string to join title parts with.
+    # @param reverse [Boolean] whether title should be reversed.
     # @return [String] title with HTML tags removed.
-    #
     def normalize_title(site_title, title, separator, reverse = false)
       clean_title = cleanup_strings(title)
       clean_title.reverse! if reverse
@@ -35,13 +34,12 @@ module MetaTags
 
     # Normalize description value.
     #
-    # @param [String] description description string.
-    # @return [String] text with tags removed, squashed spaces, truncated
-    # to 200 characters.
-    #
+    # @param description [String] description string.
+    # @return [String] text with tags removed, squashed spaces, and truncated
+    #   to the configured description limit.
     def normalize_description(description)
       # description could be another object not a string, but since it probably
-      # serves the same purpose we could just as it to convert itself to str
+      # serves the same purpose, we can ask it to convert itself to a string
       # and continue from there
       description = cleanup_string(description)
       return "" if description.blank?
@@ -51,9 +49,8 @@ module MetaTags
 
     # Normalize keywords value.
     #
-    # @param [String, Array<String>] keywords list of keywords as a string or Array.
+    # @param keywords [String, Array<String>] list of keywords as a string or Array.
     # @return [String] list of keywords joined with comma, with tags removed.
-    #
     def normalize_keywords(keywords)
       keywords = cleanup_strings(keywords)
       return "" if keywords.blank?
@@ -68,16 +65,14 @@ module MetaTags
     # Easy way to get access to Rails helpers.
     #
     # @return [ActionView::Base] proxy object to access Rails helpers.
-    #
     def helpers
       ActionController::Base.helpers
     end
 
-    # Strips all HTML tags from the +html+, including comments.
-    #
-    # @param [String] string HTML string.
-    # @return [String] html_safe string with no HTML tags.
+    # Strips all HTML tags from +string+, including comments.
     #
+    # @param string [String] HTML string.
+    # @return [String] HTML-safe string with no HTML tags.
     def strip_tags(string)
       if defined?(Loofah)
         # Instead of strip_tags we will use Loofah to strip tags from now on
@@ -87,25 +82,24 @@ module MetaTags
       end
     end
 
-    # This method returns a html safe string similar to what <tt>Array#join</tt>
+    # This method returns an HTML-safe string similar to what <tt>Array#join</tt>
     # would return. All items in the array, including the supplied separator, are
-    # html escaped unless they are html safe, and the returned string is marked
-    # as html safe.
+    # HTML-escaped unless they are HTML-safe, and the returned string is marked
+    # as HTML-safe.
     #
-    # @param [Array<String>] array list of strings to join.
-    # @param [String] sep separator to join strings with.
+    # @param array [Array<String>] list of strings to join.
+    # @param sep [String] separator to join strings with.
     # @return [String] input strings joined together using a given separator.
-    #
     def safe_join(array, sep = $OFS)
       helpers.safe_join(array, sep)
     end
 
     # Removes HTML tags and squashes down all the spaces.
     #
-    # @param [String, nil] string input string.
-    # @return [String] input string with no HTML tags and consequent white
-    # space characters squashed into a single space.
-    #
+    # @param string [String, nil] input string.
+    # @param strip [Boolean] whether to trim leading and trailing whitespace.
+    # @return [String] input string with no HTML tags and consecutive
+    #   whitespace characters squashed into a single space.
     def cleanup_string(string, strip: true)
       return "" if string.nil?
       raise ArgumentError, "Expected a string or an object that implements #to_str" unless string.respond_to?(:to_str)
@@ -118,24 +112,24 @@ module MetaTags
       s
     end
 
-    # Cleans multiple strings up.
+    # Cleans up multiple strings.
     #
-    # @param [String, Array<String>] strings input string(s).
+    # @param strings [String, Array<String>] input string(s).
+    # @param strip [Boolean] whether to trim leading and trailing whitespace.
     # @return [Array<String>] clean strings.
     # @see cleanup_string
-    #
     def cleanup_strings(strings, strip: true)
       strings = Array(strings).flatten.map! { |s| cleanup_string(s, strip: strip) }
       strings.reject!(&:blank?)
       strings
     end
 
-    # Truncates a string to a specific limit. Return string without truncation when limit 0 or nil
+    # Truncates a string to a specific limit. Returns the string without
+    # truncation when the limit is 0 or nil.
     #
-    # @param [String] string input strings.
-    # @param [Integer,nil] limit characters number to truncate to.
+    # @param string [String] input string.
+    # @param limit [Integer, nil] number of characters to truncate to.
     # @return [String] truncated string.
-    #
     def truncate(string, limit = nil)
       return string if limit.to_i == 0
 
@@ -150,22 +144,22 @@ module MetaTags
 
     # Truncates an array of strings to a specific limit.
     #
-    # @param [Array<String>] string_array input strings.
-    # @param [Integer,nil] limit characters number to truncate to.
-    # @param [String] separator separator that will be used to join array later.
+    # @param string_array [Array<String>] input strings.
+    # @param limit [Integer, nil] number of characters to truncate to.
+    # @param separator [String] separator that will be used to join the array later.
     # @return [Array<String>] truncated array of strings.
-    #
     def truncate_array(string_array, limit = nil, separator = "")
       return string_array if limit.nil? || limit <= 0
 
       length = 0
+      preserve_items = string_array.size > 1 && MetaTags.config.truncate_array_items_at_boundaries
       result = [] # : Array[String]
 
       string_array.each do |string|
         limit_left = calculate_limit_left(limit, length, result, separator)
 
         if string.length > limit_left
-          result << truncate(string, limit_left)
+          result << truncate(string, limit_left) if !preserve_items || result.empty?
           break string_array
         end
 
@@ -181,10 +175,23 @@ module MetaTags
 
     private
 
+    # Calculates how many characters are left for the next segment.
+    #
+    # @param limit [Integer] total truncation limit.
+    # @param length [Integer] current accumulated length.
+    # @param result [Array<String>] accumulated string segments.
+    # @param separator [String] separator inserted between segments.
+    # @return [Integer] remaining number of characters.
     def calculate_limit_left(limit, length, result, separator)
       limit - length - (result.any? ? separator.length : 0)
     end
 
+    # Truncates the site title and page title segments to the configured limit.
+    #
+    # @param site_title [String] site title.
+    # @param title [Array<String>] page title segments.
+    # @param separator [String] separator used between segments.
+    # @return [Array] truncated site title and title segments.
     def truncate_title(site_title, title, separator)
       global_limit = MetaTags.config.title_limit.to_i
       if global_limit > 0
@@ -199,6 +206,13 @@ module MetaTags
       [site_title, title]
     end
 
+    # Calculates the title length limits for the site title and page title.
+    #
+    # @param site_title [String] site title.
+    # @param title [Array<String>] page title segments.
+    # @param separator [String] separator used between segments.
+    # @param global_limit [Integer] total allowed title length.
+    # @return [Array<Integer>] site title limit and page title limit.
     def calculate_title_limits(site_title, title, separator, global_limit)
       # What should we truncate first: site title or page title?
       main_title = MetaTags.config.truncate_site_title_first ? title : [site_title]

data/lib/meta_tags/version.rb

@@ -2,6 +2,6 @@
 
 module MetaTags
   # Gem version.
-  VERSION = "2.22.3"
+  VERSION = "2.24.0"
   public_constant :VERSION
 end