delivery-sdk-ruby 0.16.0 → 1.0.0

data/lib/delivery/models/pagination.rb

@@ -1,9 +1,13 @@
 module KenticoCloud
   module Delivery
-    # Holds pagination data from a DeliveryItemListingResponse
+    # Holds pagination data from listing responses
     class Pagination
       attr_accessor :skip, :limit, :count, :next_page
 
+      # Constructor.
+      #
+      # * *Args*:
+      #   - *json* (+JSON+) The 'pagination' node of a listing reponse's JSON object 
       def initialize(json)
         self.skip = json['skip']
         self.limit = json['limit']

data/lib/delivery/models/taxonomy_group.rb

@@ -1,7 +1,10 @@
 module KenticoCloud
   module Delivery
-    # JSON data of a taxonomy group parsed as OpenStruct objects for dynamic use
     class TaxonomyGroup
+      # Parses the 'terms' JSON node as a dynamic OpenStruct object.
+      #
+      # * *Returns*:
+      #   - +OpenStruct+ The terms of the taxonomy group as a dynamic object
       def terms
         @terms unless @terms.nil?
         @terms = JSON.parse(
@@ -10,6 +13,10 @@ module KenticoCloud
         )
       end
 
+      # Parses the 'system' JSON node as a dynamic OpenStruct object.
+      #
+      # * *Returns*:
+      #   - +OpenStruct+ The system properties of the taxonomy group
       def system
         @system unless @system.nil?
         @system = JSON.parse(
@@ -18,6 +25,10 @@ module KenticoCloud
         )
       end
 
+      # Constructor.
+      #
+      # * *Args*:
+      #   - *json* (+JSON+) A JSON node representing a taxonomy group
       def initialize(source)
         @source = source
       end

data/lib/delivery/query_parameters/filters.rb

@@ -4,7 +4,14 @@ module KenticoCloud
   module Delivery
     module QueryParameters
       # Provides the base class for filter implementations.
+      # See https://developer.kenticocloud.com/v1/reference#content-filtering
       class Filter < ParameterBase
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *key* (+string+) The field to filter upon
+        #   - *operator* (+string+) The Kentico Cloud filter being applied to the field, in brackets
+        #   - *values* (+Object+) One or more values which will appear as the value of the query string parameter
         def initialize(key, operator, values)
           super(key, operator, values)
         end
@@ -19,6 +26,12 @@ class String
   # element or system attribute has a value that contains all the specified
   # values. This filter is applicable to array values only, such as sitemap
   # location or value of Linked Items, Taxonomy and Multiple choice content elements.
+  #
+  # * *Args*:
+  #   - +Object+ One or more objects representing the values that must appear in the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def all(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[all]', *args)
   end
@@ -27,6 +40,12 @@ class String
   # element or system attribute has a value that contains any the specified
   # values. This filter is applicable to array values only, such as sitemap
   # location or value of Linked Items, Taxonomy and Multiple choice content elements.
+  #
+  # * *Args*:
+  #   - +Object+ One or more objects representing the values that may appear in the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def any(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[any]', *args)
   end
@@ -35,12 +54,24 @@ class String
   # or system attribute has a value that contains the specified value.
   # This filter is applicable to array values only, such as sitemap location or value
   # of Linked Items, Taxonomy and Multiple choice content elements.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the value that must appear in the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def contains(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[contains]', *args)
   end
 
   # Represents a filter that matches a content item if the specified
   # content element or system attribute has the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the value that must equal the value in the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def eq(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '', *args)
   end
@@ -48,6 +79,12 @@ class String
   # Represents a filter that matches a content item if the specified content
   # element or system attribute has a value that is greater than the
   # specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the lowest possible value of the field, non-inclusive
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def gt(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[gt]', *args)
   end
@@ -55,6 +92,12 @@ class String
   # Represents a filter that matches a content item if the specified content
   # element or system attribute has a value that is greater than or equal to
   # the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the lowest possible value of the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def gt_or_eq(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[gte]', *args)
   end
@@ -62,6 +105,12 @@ class String
   # Represents a filter that matches a content item if the specified
   # content element or system attribute has a value that matches a
   # value in the specified list.
+  #
+  # * *Args*:
+  #   - +Object+ One or more objects representing the required values of the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def in(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[in]', *args)
   end
@@ -69,6 +118,12 @@ class String
   # Represents a filter that matches a content item if the specified content
   # element or system attribute has a value that is less than the
   # specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the highest possible value of the field, non-inclusive
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def lt(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[lt]', *args)
   end
@@ -76,6 +131,12 @@ class String
   # Represents a filter that matches a content item if the specified content
   # element or system attribute has a value that is less than or equal to
   # the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the highest possible value of the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def lt_or_eq(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[lte]', *args)
   end
@@ -83,6 +144,12 @@ class String
   # Represents a filter that matches a content item if the specified
   # content element or system attribute has a value that falls within
   # the specified range of values (both inclusive).
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the lowest and highest possible values of the field
+  #
+  # * *Returns*:
+  #   - KenticoCloud::Delivery::QueryParameters::Filter
   def range(*args)
     KenticoCloud::Delivery::QueryParameters::Filter.new(self, '[range]', *args)
   end

data/lib/delivery/query_parameters/parameter_base.rb

@@ -1,14 +1,18 @@
 module KenticoCloud
   module Delivery
-    # Contains static methods for adding parameters to a DeliveryQuery
-    # as well as the Filter class.
     module QueryParameters
-      # Base class for all parameters added to a DeliveryQuery using the
-      # .parameters method. All parameters appear in the query string.
+      # Base class for all parameters added to a DeliveryQuery. All
+      # QueryParameters will appear in the query string.
       class ParameterBase
         attr_accessor :key
         SEPARATOR = CGI.escape(',')
 
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *key* (+string+) The field to filter upon
+        #   - *operator* (+string+) The Kentico Cloud filter being applied to the field, in brackets
+        #   - *values* (+Object+) One or more values which will appear as the value of the query string parameter
         def initialize(key, operator, values)
           self.key = key
           values = [values] unless values.respond_to? :each
@@ -16,6 +20,12 @@ module KenticoCloud
           @operator = operator
         end
 
+        # Converts the object into a valid query string parameter for use in
+        # a request to Delivery. The key, operator, and values are all escaped
+        # and if there are multiple values, they are joined with commas.
+        #
+        # * *Returns*:
+        #   - +string+ A query string parameter without any additional characters (e.g. '&')
         def provide_query_string_parameter
           escaped_values = []
           @values.each { |n| escaped_values << CGI.escape(n.to_s) }

data/lib/delivery/query_parameters/query_string.rb

@@ -3,15 +3,18 @@ require 'delivery/query_parameters/parameter_base'
 module KenticoCloud
   module Delivery
     module QueryParameters
+      # Represents the entire query string for a request to Delivery.
       class QueryString
         def initialize
           @params = []
         end
 
         # Adds a parameter to the query string
-        # @param [String] param Either a string representing the key for the parameter, or a complete ParameterBase object
-        # @param [String] values A string or array of strings representing the values for the parameter
-        # @param [String] operator Kentico Cloud filtering parameter, placed after the key, before the equal sign
+        #
+        # * *Args*:
+        #   - *param* (+Object+) Either a string representing the key for the parameter, or a complete KenticoCloud::Delivery::QueryParameters::ParameterBase object
+        #   - *values* (+string+) A string or array of strings representing the values for the parameter
+        #   - *operator* (+string+) Kentico Cloud filtering parameter, placed after the key, before the equal sign
         def set_param(param, values = '', operator = '')
           parameter_base =
             if param.is_a? String
@@ -30,18 +33,40 @@ module KenticoCloud
           @params << parameter_base
         end
 
+        # Removes all parameters from the query string with a matching key.
+        #
+        # * *Args*:
+        #   - *key* (+string+) Parameter key
         def remove_param(key)
           @params.delete_if { |i| i.key.eql? key }
         end
 
+        # Returns all parameters from the query string with a matching key.
+        #
+        # * *Args*:
+        #   - *key* (+string+) Parameter key
+        #
+        # * *Returns*:
+        #   - +Object+ One or more KenticoCloud::Delivery::QueryParameters::ParameterBase objects
         def param(key)
           @params.select { |p| p.key.eql? key }
         end
 
+        # Checks whether there are any parameters defined.
+        #
+        # * *Returns*:
+        #   - +bool+ True if there are no parameters set.
         def empty?
           @params.empty?
         end
 
+        # Generates a full query string based on the set parameters, with the
+        # required '?' character at the start. Accomplished by calling the
+        # KenticoCloud::Delivery::QueryParameters::ParameterBase.provide_query_string_parameter
+        # method for each parameter.
+        #
+        # * *Returns*:
+        #   - +string+ A complete query string
         def to_s
           '?' + @params.map(&:provide_query_string_parameter).join('&')
         end

data/lib/delivery/resolvers/content_link_resolver.rb

@@ -4,15 +4,21 @@ module KenticoCloud
   module Delivery
     module Resolvers
       # Locates <a data-item-id=""> tags in content and calls a user-defined method
-      # to supply the href for content item links
+      # to supply the href for content item links.
+      # See https://github.com/Kentico/delivery-sdk-ruby#resolving-links
       class ContentLinkResolver
         def initialize(callback = nil)
           @callback = callback
         end
 
-        # Resolves all links in the content
-        # @param [String] content The string value stored in the element
-        # @param [Array] links The collection of source links from the JSON response
+        # Resolves all links in the content.
+        #
+        # * *Args*:
+        #   - *content* (+string+) The string value stored in the element
+        #   - *links* (+Array+) The collection of links from an element's 'links' JSON node
+        #
+        # * *Returns*:
+        #   - +string+ The original content passed, with all links resolved
         def resolve(content, links)
           doc = Nokogiri::HTML.parse(content).xpath('//body')
           links = links.map { |link| ContentLink.new link }
@@ -26,7 +32,14 @@ module KenticoCloud
 
         # Accepts a tag found in the content and tries to locate matching
         # source link from JSON response. If found, resolves URL and returns
-        # the tag with generated HREF
+        # the tag with generated HREF.
+        #
+        # * *Args*:
+        #   - *tag* (+string+) A <a data-item-id=""> tag found in the content
+        #   - *links* (+Array+) The collection of links from an element's 'links' JSON node, converted to KenticoCloud::Delivery::Resolvers::ContentLink objects
+        #
+        # * *Returns*:
+        #   - +string+ The <a data-item-id=""> tag with an HREF generated by the +provide_url+ method
         def resolve_tag(tag, links)
           matches = links.select { |link| link.id == tag['data-item-id'].to_s }
           url = provide_url matches
@@ -34,7 +47,14 @@ module KenticoCloud
           tag
         end
 
-        # Returns a url if a link was found in source links, otherwise returns 404
+        # Uses the +resolve_link+ method to generate a URL for a ContentLink
+        # object.
+        #
+        # * *Args*:
+        #   - *matches* (+Array+) The ContentLink objects with an ID matching a particular <a data-item-id=""> tag
+        #
+        # * *Returns*:
+        #   - +string+ A url if a link was found in source links, otherwise '/404'
         def provide_url(matches)
           if !matches.empty?
             if @callback.nil?
@@ -52,6 +72,10 @@ module KenticoCloud
       class ContentLink
         attr_accessor :code_name, :type, :url_slug, :id
 
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *link* (+JSON+) One link from an element's 'links' JSON node
         def initialize(link)
           self.id = link[0]
           self.code_name = link[1]['codename']

data/lib/delivery/resolvers/inline_content_item_resolver.rb

@@ -3,16 +3,22 @@ require 'nokogiri'
 module KenticoCloud
   module Delivery
     module Resolvers
-      # Locates <object data-type="item"> tags in content and calls a user-defined method
-      # to supply the HTML output for the content item
+      # Locates <object data-type="item"> tags in content and calls a user-defined
+      # method to supply the output for the content item.
+      # See https://github.com/Kentico/delivery-sdk-ruby#resolving-inline-content
       class InlineContentItemResolver
         def initialize(callback = nil)
           @callback = callback
         end
 
-        # Resolves all inline content items in the content
-        # @param [String] content The string value stored in the element
-        # @param [Array] inline_items ContentItems referenced by the content
+        # Resolves all inline content items in the content.
+        #
+        # * *Args*:
+        #   - *content* (+string+) The string value stored in the element
+        #   - *inline_items* (+Array+) ContentItems referenced by the content from the 'modular_content' JSON node
+        #
+        # * *Returns*:
+        #   - +string+ The original content passed, with all <object data-type="item"> replaced with custom output
         def resolve(content, inline_items)
           doc = Nokogiri::HTML.parse(content).xpath('//body')
           tags = doc.xpath('//object[@type="application/kenticocloud"][@data-type="item"]')
@@ -32,11 +38,26 @@ module KenticoCloud
 
         # Accepts a tag found in the content and tries to locate matching
         # ContentItem from JSON response.
+        #
+        # * *Args*:
+        #   - *tag* (+string+) A <object data-type="item"> tag found in the content
+        #   - *inline_items* (+Array+) ContentItems referenced by the content from the 'modular_content' JSON node
+        #
+        # * *Returns*:
+        #   - +string+ The custom output generated by the +provide_output+ method
         def resolve_tag(tag, inline_items)
           matches = inline_items.select { |item| item.system.codename == tag['data-codename'].to_s }
           provide_output matches
         end
 
+        # Generates custom output for a content item using the +resolve_item+
+        # method.
+        #
+        # * *Args*:
+        #   - *matches* (+Array+) The ContentItems from the 'modular_content' JSON node which match the code name of a particular <object data-type="item"> tag
+        #
+        # * *Returns*:
+        #   - +string+ The custom output generated by the +resolve_item+ method
         def provide_output(matches)
           if !matches.empty?
             if @callback.nil?

data/lib/delivery/resolvers/linked_item_resolver.rb

@@ -1,29 +1,34 @@
 module KenticoCloud
   module Delivery
-    # Resolves a content item by its codename
-    # It contains the modular content of item/items response
-    class LinkedItemResolver
-      def initialize(modular_content, content_link_url_resolver, inline_content_item_resolver)
-        @modular_content = modular_content
-        @content_link_url_resolver = content_link_url_resolver
-        @inline_content_item_resolver = inline_content_item_resolver
-        @resolved_items = {}
-      end
+    module Resolvers
+      # Resolves a content item by its codename. It contains the modular content
+      # of item/items response.
+      class LinkedItemResolver
+        def initialize(modular_content, content_link_url_resolver, inline_content_item_resolver)
+          @modular_content = modular_content
+          @content_link_url_resolver = content_link_url_resolver
+          @inline_content_item_resolver = inline_content_item_resolver
+          @resolved_items = {}
+        end
 
-      # Resolves a content item
-      # If the link for a codename was resolved before,
-      # it returns the same instance of Content Item
-      # @param [String] codename Codename of the content item
-      # @return [ContentItem]
-      def resolve(codename)
-        @resolved_items[codename] ||= resolve_item(codename)
-      end
+        # Resolves a content item. If the link for a codename was resolved
+        # before, it returns the same instance of ContentItem.
+        #
+        # * *Args*:
+        #   - *codename* (+string+) Codename of the content item
+        #
+        # * *Return*:
+        #   - KenticoCloud::Delivery::ContentItem
+        def resolve(codename)
+          @resolved_items[codename] ||= resolve_item(codename)
+        end
 
-      private
+        private
 
-      def resolve_item(codename)
-        item = @modular_content.values.find { |i| i['system']['codename'] == codename }
-        ContentItem.new JSON.parse(JSON.generate(item)), @content_link_url_resolver, @inline_content_item_resolver, self
+        def resolve_item(codename)
+          item = @modular_content.values.find { |i| i['system']['codename'] == codename }
+          ContentItem.new JSON.parse(JSON.generate(item)), @content_link_url_resolver, @inline_content_item_resolver, self
+        end
       end
     end
   end