link.rb in scrivito_sdk-0.70.0.rc1

- old
+ new

@@ -1,26 +1,28 @@
 require 'active_model/naming'
 
 module Scrivito
-  # This class provides an interfaces for handling CMS Links.
-  # To format a link for rendering in an html page, use the +scrivito_path+ or +scrivito_url+ methods.
+  # This class provides an interface for handling CMS links.
+  # To format a link for rendering on an HTML page, use the +scrivito_path+ or +scrivito_url+ methods.
   # @api public
   class Link
 
     extend ActiveModel::Naming
 
-    # Parses a url and returns a {Link} object. Determines internal urls based on the given
+    # Parses a URL and returns a {Link} object. Determines internal URLs based on the given
     # +hostname+ and +port+.
     # @api public
     # @param [String] url
     # @param host [String] the hostname of internal urls
     # @param port [String] the port of internal urls
     def self.parse(url, host, port)
       LinkParser.new(host, port).parse(url)
     end
 
-    # Create a new link obj
+    # Create a new link object.
+    # @example Set the 'current_campaign' link of an object:
+    #   obj.update(current_campaign: Scrivito::Link.new(obj: Obj.find('55dd1ce50ecc41c8')))
     # @api public
     # @param [Hash] link_data
     # @option link_data [String] url
     # @option link_data [Obj] obj
     # @option link_data [String] title
@@ -29,133 +31,139 @@
     # @option link_data [String] fragment
     def initialize(link_data)
       @link_data = link_data.with_indifferent_access
     end
 
-    # The link's external url. Only available for external links.
-    # Warning: Do not output the url directly unless you know what you are doing.
-    # Normally you want to use the +scrivito_path+ or +scrivito_url+ methods to format a link.
+    # The external URL of the link. Only available for external links.
+    # Warning: Do not output the URL directly unless you know what you are doing.
+    # Normally, you want to use the +scrivito_path+ or +scrivito_url+ methods to format a link.
     # @api public
     def url
       @link_data[:url]
     end
 
-    # Set the link's external url. This will lead to an external link.
+    # Set the external URL of the link. This causes the link to become an external link.
     # @api public
     # @param value [String] the url of the link
     def url=(value)
       @link_data[:url] = value
     end
 
-    # Returns the {BasicObj Obj} this link is referencing. May be nil if the
+    # Returns the {BasicObj Obj} this link references. May be +nil+ if the
     # link is external.
     # @api public
     def obj
       @link_data[:obj]
     end
 
-    # Set the {BasicObj Obj} this link is referencing. May be nil if the
-    # link is external.
+    # Set the {BasicObj Obj} this link should reference.
     # @api public
-    # @param value [Obj] the obj this link should be referencing
+    # @param value [Obj] the obj this link should point to
     def obj=(value)
       @link_data[:obj] = value
     end
 
-    # The link's title.
+    # Returns the title of the link.
     # @api public
     def title
       @link_data[:title]
     end
 
-    # Set the link's title.
+    # Set the link title.
     # @api public
-    # @param value [String] the link's title
+    # @param value [String] the title of the link
     def title=(value)
       @link_data[:title] = value
     end
 
-    # Returns the link's query string as in "index.html?query_string".
+    # Returns the query string of the link as in "index.html?query_string".
     # See RFC3986 for details (http://www.ietf.org/rfc/rfc3986.txt).
     # @api public
     def query
       @link_data[:query]
     end
 
-    # Set the link's query string as in "index.html?query_string".
+    # Set the query string of the link as in "index.html?query_string".
     # See RFC3986 for details (http://www.ietf.org/rfc/rfc3986.txt).
     # @api public
     # @param value [String] the query string of the link
     def query=(value)
       @link_data[:query] = value
     end
 
-    # Returns the link's anchor as in "index.html#anchor".
+    # Returns the anchor of the link as in "index.html#anchor".
     # See RFC3986 for details (http://www.ietf.org/rfc/rfc3986.txt).
     # @api public
     def fragment
       @link_data[:fragment]
     end
 
-    # Set the link's anchor as in "index.html#anchor".
+    # Set the anchor of the link as in "index.html#anchor".
     # See RFC3986 for details (http://www.ietf.org/rfc/rfc3986.txt).
     # @api public
-    # @param value [String] the anchor or fragement of the link
+    # @param value [String] the anchor or fragment of the link
     def fragment=(value)
       @link_data[:fragment] = value
     end
 
+    # Returns the link target. "target" refers to the equally-named HTML attribute,
+    # not the link destination.
+    # @api public
     def target
       @link_data[:target]
     end
 
+    # Set the link target. "target" refers to the equally-named HTML attribute,
+    # not the link destination.
+    # @api public
+    # @param value [String] the target of the link
     def target=(value)
       @link_data[:target] = value
     end
 
-    # Returns the file extension (e.g. zip, pdf) of this link's (internal or external) target.
-    # Returns an empty string if the file extension is can not be determined.
+    # Returns the file extension (e.g. zip, pdf) of the (internal or external) destination
+    # of this link.
+    # Returns an empty string if the file extension cannot be determined.
     # @api public
     def file_extension
       if internal?
         obj ? obj.file_extension : ""
       else
         path = URI.parse(url).path rescue nil
         path.blank? ? "" : File.extname(path)[1..-1] || ""
       end
     end
 
-    # Returns the title of this Link if it is set.
-    # Otherwise it returns the display_title of the destination object for internal Links
-    # or the URL for external Links.
+    # Returns the title of this Link if it is set. If not, the +display_title+ of the destination
+    # object is returned for internal links, or the +url+ for external links.
     # @api public
     def display_title
       dt = title
       dt = obj.display_title if dt.blank? && !external?
       dt = url if dt.blank?
       dt
     end
 
-    # The alt description of a +Link+ used for {ScrivitoHelper#scrivito_image_tag}.
+    # The alt description of a +Link+, used by {ScrivitoHelper#scrivito_image_tag}.
     #
-    # By default this method returns the +title+ of this +Link+.
-    # If +title+ is nil and this +Link+ references an {BasicObj Obj}
+    # By default, this method returns the +title+ of this +Link+.
+    # If +title+ is +nil+ and this +Link+ references an {BasicObj Obj}, the
     # +alt_description+ of that {BasicObj Obj} is used.
     #
     # @api public
     def alt_description
       return title if title
       obj.alt_description if internal?
     end
 
-    # Returns true this Link links to a CMS Object.
+    # Returns true if this Link points to a CMS object.
     # @api public
     def internal?
       url.nil?
     end
 
-    # Returns true if this Link links to an external URL.
+    # Returns true if this Link points to an external location.
     # @api public
     def external?
       !internal?
     end
 
@@ -188,14 +196,22 @@
       if internal?
         params[:obj_id] = obj.id
         params[:title] = title if title
         params[:query] = query if query
         params[:fragment] = fragment if fragment
+        params[:target] = target if target
       else
         params[:url] = url
         params[:title] = title if title
+        params[:target] = target if target
       end
 
       params
+    end
+
+    def ==(other)
+      return false unless other.is_a?(Link)
+
+      to_cms_api_linklist_params == other.to_cms_api_linklist_params
     end
   end
 end