delivery-sdk-ruby 0.16.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0058d0fb12f1404bebdc08e2fcb411d4b4e2cc24a5314218f998d3f437797227'
-  data.tar.gz: 2950d33463280e2eb7e2ffa653dd3c92fd28e0b465ad74405bd85730d3d86d82
+  metadata.gz: 6cc5777ca1aad7843166ac84a6af661c21882b20a00d21f93710bf1a06cae304
+  data.tar.gz: 140f1c745d5d38fd59448ff856e2203c2ba5c3c3ad37fc91cfc6410e5d666dba
 SHA512:
-  metadata.gz: 821a6f42b2044340c81dbb9bb1e6b53a8a318374151cbf844fe7b845d66ddb9e671675a95b5663d4f223daeed1a7b1cb745d284a77a21600054939db75142c18
-  data.tar.gz: f1c876ef295aa5b3637de511dbd8f40f1d62df18e89b613969e200f8d8696d6a435a6c947a3b19e04093a072aa005d3ead544b50275c895bbe64fbff98bd629d
+  metadata.gz: c9e45bca4d8dd901a849428ae90a4e3d28e38c06e859f48ffe481dda7fb0960f4dc79569d47368f3e0840052f02339f69aa1bd903db40e5d0a11bc09ff676318
+  data.tar.gz: 9e7e6ee1db6304034f39ed67935ea068d48dbcd1878c9d76a3fe17df5c30d3659f84f8e2ae817112377c850f5b868dec045693dc4da7976fa71773706c69a227

data/lib/delivery/builders/image_transformation_builder.rb

@@ -3,6 +3,11 @@ require 'delivery/query_parameters/query_string'
 module KenticoCloud
   module Delivery
     module Builders
+      # Provides methods for manipulating the URL of an asset to adjust the image's
+      # size, cropping behavior, background color, output format, and quality.
+      #
+      # See https://developer.kenticocloud.com/v1/reference#image-transformation and
+      # https://github.com/Kentico/delivery-sdk-ruby#image-transformation.
       class ImageTransformationBuilder
         FIT_MODE_CLIP = 'clip'.freeze
         FIT_MODE_SCALE = 'scale'.freeze
@@ -26,55 +31,119 @@ module KenticoCloud
         'See https://developer.kenticocloud.com/v1/reference#focal-point-crop'\
         'for more information.'.freeze
         ONE_TO_100 = 'Quality parameter must be between 1 and 100.'.freeze
-        BOOLEAN_PARAM = 'The lossless parameter must be "true," "false," '\
-        '1, or 0.'.freeze
+        BOOLEAN_PARAM = 'The parameter must be a boolean, 0, or 1.'.freeze
 
+        # Constructor. Generally, you obtain an +AssetURL+ object by calling
+        # KenticoCloud::Delivery::Builders::ImageTransformationBuilder.transform
+        # instead of using this constructor.
         def initialize(url)
           @url = url
           @query_string = KenticoCloud::Delivery::QueryParameters::QueryString.new
         end
 
+        # Applies all transformation options to the asset URL.
+        #
+        # * *Returns*:
+        #   - +string+ The full URL to the asset with all query string parameters set
         def url
           @url + @query_string.to_s
         end
 
+        # Sets the width of the image
+        #
+        # * *Args*:
+        #   - *width*
+        #     - +integer+ Width in pixels, between 1 and 8192.
+        #     - +float+ Width in percentage, between 0 and 1.
+        #
+        # * *Returns*:
+        #   - +self+
         def with_width(width)
           @query_string.set_param 'w', width
           self
         end
 
+        # Sets the height of the image
+        #
+        # * *Args*:
+        #   - *height*
+        #     - +integer+ Height in pixels, between 1 and 8192.
+        #     - +float+ Height in percentage, between 0 and 1.
+        #
+        # * *Returns* :
+        #   - +self+
         def with_height(height)
           @query_string.set_param 'h', height
           self
         end
 
+        # Sets the device pixel ratio. Either width or height
+        # (or both) must be set.
+        #
+        # * *Args*:
+        #   - *dpr* (+float+) Pixel ratio between 0 and 5.
+        #
+        # * *Returns*:
+        #   - +self+
         def with_pixel_ratio(dpr)
           @query_string.set_param 'dpr', dpr
           self
         end
 
+        # Defines how the image is constrained while resizing. Either width
+        # or height (or both) must be set.
+        #
+        # * *Args*:
+        #   - *fit* (+string+) Use constants from KenticoCloud::Delivery::Builders::ImageTransformationBuilder
+        #
+        # * *Returns*:
+        #   - +self+
         def with_fit_mode(fit)
           @query_string.set_param 'fit', fit
           self
         end
 
+        # Selects a region of the image to perform transformations on.
         # Setting this will remove focal point cropping from the image,
         # as the two options are incompatible.
-        # @param x
-        # @param y
-        # @param width
-        # @param height
+        #
+        # * *Args*:
+        #   - *x*
+        #     - +integer+ The left border of the rect in pixels
+        #     - +float+ The left border of the rect as a percentage between 0 and 1
+        #   - *y*
+        #     - +integer+ The top border of the rect in pixels
+        #     - +float+ The top border of the rect as a percentage between 0 and 1
+        #   - *width*
+        #     - +integer+ The width of the rect in pixels
+        #     - +float+ The width of the rect as a percentage between 0 and 1
+        #   - *height*
+        #     - +integer+ The height of the rect in pixels
+        #     - +float+ The height of the rect as a percentage between 0 and 1
+        #
+        # * *Returns*:
+        #   - +self+
         def with_rect(x, y, width, height)
           @query_string.remove_param 'fp-x'
           @query_string.remove_param 'fp-y'
           @query_string.remove_param 'fp-z'
-          @query_string.remove_param 'crop', 'focalpoint'
+          @query_string.remove_param 'crop'
           @query_string.set_param 'rect', "#{x},#{y},#{width},#{height}"
           self
         end
 
+        # Sets the point of interest when cropping the image.
         # Setting this will remove the source rectangle region,
-        # as the two options are incompatible.
+        # as the two options are incompatible. It also automatically sets the
+        # crop to "focalpoint" and fit to "crop"
+        #
+        # * *Args*:
+        #   - *x* (+float+) Percentage of the image's width between 0 and 1
+        #   - *y* (+float+) Percentage of the image's height between 0 and 1
+        #   - *z* (+integer+) Amount of zoom to apply. A value of 1 is the default zoom, and each step represents 100% additional zoom.
+        #
+        # * *Returns*:
+        #   - +self+
         def with_focal_point(x, y, z)
           raise ArgumentError, INVALID_PARAMS unless valid_dims?(x, y, z)
 
@@ -82,28 +151,50 @@ module KenticoCloud
           @query_string.set_param 'fp-x', x
           @query_string.set_param 'fp-y', y
           @query_string.set_param 'fp-z', z
+          @query_string.set_param 'fit', ImageTransformationBuilder::FIT_MODE_CROP
           @query_string.set_param 'crop', 'focalpoint'
           self
         end
 
-        def valid_dims?(x, y, z)
-          (x.to_f >= 0.0 && x.to_f <= 1.0) &&
-            (y.to_f >= 0.0 && y.to_f <= 1.0) &&
-            (z.to_i >= 1)
-        end
-
-        # Sets the background color.
-        # @param [String] color a valid 3, 4, 6, or 8 digit hexadecimal color, without the # symbol
+        # Sets the background color of any transparent areas of the image.
+        #
+        # * *Args*:
+        #   - *color* (+string+) A valid 3, 4, 6, or 8 digit hexadecimal color, without the # symbol
+        #
+        # * *Returns*:
+        #   - +self+
         def with_background_color(color)
           @query_string.set_param 'bg', color
           self
         end
 
+        # Sets the output format of the request for the image.
+        #
+        # * *Args*:
+        #   - *format* (+string+) Use constants from KenticoCloud::Delivery::Builders::ImageTransformationBuilder
+        #
+        # * *Returns*:
+        #   - +self+
         def with_output_format(format)
           @query_string.set_param 'fm', format
           self
         end
 
+        # Configure the amount of compression for lossy file formats. Lower quality
+        # images will have a smaller file size. Only affects *jpg*, *pjpg*, and
+        # *webp* files.
+        #
+        # When no quality is specified for an image transformation, the default
+        # value of 85 is used.
+        #
+        # * *Args*:
+        #   - *quality* (+integer+) The quality of the image between 1 and 100
+        #
+        # * *Returns*:
+        #   - +self+
+        #
+        # * *Raises*:
+        #   - +ArgumentError+ if +quality+ is not between 1 and 100 inclusive
         def with_quality(quality)
           raise ArgumentError, ONE_TO_100 unless quality.to_i >= 1 && quality.to_i <= 100
 
@@ -111,7 +202,20 @@ module KenticoCloud
           self
         end
 
-        # Sets lossless to true or false. If true, automatically sets the format to WebP
+        # Sets the lossless parameter. If +true+, automatically sets the format
+        # to WebP.
+        #
+        # * *Args*:
+        #   - *lossless*
+        #     - +integer+ Either 1 or 0
+        #     - +bool+ Either +true+ or +false+
+        #     - +string+ Either 'true' or 'false'
+        #
+        # * *Returns*:
+        #   - +self+
+        #
+        # * *Raises*:
+        #   - +ArgumentError+ if +lossless+ cannot be parsed as a boolean
         def with_lossless(lossless)
           lossless = lossless.to_s.downcase
           raise ArgumentError, BOOLEAN_PARAM unless bool? lossless
@@ -121,15 +225,25 @@ module KenticoCloud
           self
         end
 
-        def bool?(value)
-          (value == 'true') ||
-            (value == 'false') ||
-            (value == '0') ||
-            (value == '1')
-        end
-
+        # Enables or disables automatic format selection. If enabled, it will
+        # override the format parameter and deliver WebP instead. If the browser
+        # does not support WebP, the value of the format parameter will be used.
+        #
+        # * *Args*:
+        #   - *auto*
+        #     - +integer+ Either 1 or 0
+        #     - +bool+ Either +true+ or +false+
+        #     - +string+ Either 'true' or 'false'
+        #
+        # * *Returns*:
+        #   - +self+
+        #
+        # * *Raises*:
+        #   - +ArgumentError+ if +auto+ cannot be parsed as a boolean
         def with_auto_format_selection(auto)
           auto = auto.to_s.downcase
+          raise ArgumentError, BOOLEAN_PARAM unless bool? auto
+
           if %w[true 1].include? auto
             @query_string.set_param 'auto', 'format'
           else
@@ -137,6 +251,18 @@ module KenticoCloud
           end
           self
         end
+
+        private
+
+        def valid_dims?(x, y, z)
+          (x.to_f >= 0.0 && x.to_f <= 1.0) &&
+            (y.to_f >= 0.0 && y.to_f <= 1.0) &&
+            (z.to_i >= 1)
+        end
+
+        def bool?(value)
+          %w[true false 0 1].include? value
+        end
       end
     end
   end

data/lib/delivery/builders/url_builder.rb

@@ -1,7 +1,7 @@
 module KenticoCloud
   module Delivery
     module Builders
-      # Generates the URL required for Delivery REST API
+      # Internal class which generates the URL required for Delivery REST API
       class UrlBuilder
         URL_TEMPLATE_BASE = 'https://deliver.kenticocloud.com/%s'.freeze
         URL_TEMPLATE_PREVIEW = 'https://preview-deliver.kenticocloud.com/%s'.freeze
@@ -17,6 +17,14 @@ module KenticoCloud
         MSG_LONG_QUERY = 'The request url is too long. Split your query into multiple calls.'.freeze
 
         class << self
+          # Returns the proper domain for the request along with the
+          # query string parameters configured by the +DeliveryQuery+.
+          #
+          # * *Args*:
+          #   - *query* ( KenticoCloud::Delivery::DeliveryQuery )
+          #
+          # * *Returns*:
+          #   - +string+ The full URL for a Delivery request
           def provide_url(query)
             url = provide_base_url(query)
             url += provide_path_part(query)
@@ -28,39 +36,71 @@ module KenticoCloud
             end
           end
 
+          # Checks whether the provided URL is too long and raises an error if so.
+          #
+          # * *Args*:
+          #   - *url* (+string+) A full Delivery URL
+          #
+          # * *Raises*:
+          #   - +UriFormatException+ if the URL is 65,519 characters or more
           def validate_url(url)
             raise UriFormatException, MSG_LONG_QUERY if url.length > URL_MAX_LENGTH
           end
 
           private
 
-          # Returns relative path part of URL depending on query type
+          # Returns relative path part of URL depending on query type.
+          #
+          # * *Args*:
+          #   - *query* ( KenticoCloud::Delivery::DeliveryQuery )
+          #
+          # * *Returns*:
+          #   - +string+ The URL path part (without protocol or domain)
           def provide_path_part(query)
             case query.query_type
             when KenticoCloud::Delivery::QUERY_TYPE_ITEMS
-              if query.code_name.nil?
-                URL_TEMPLATE_ITEMS
-              else
-                format(URL_TEMPLATE_ITEM, query.code_name)
-              end
+              provide_item query
             when KenticoCloud::Delivery::QUERY_TYPE_TYPES
-              if query.code_name.nil?
-                URL_TEMPLATE_TYPES
-              else
-                format(URL_TEMPLATE_TYPE, query.code_name)
-              end
+              provide_type query
             when KenticoCloud::Delivery::QUERY_TYPE_TAXONOMIES
-              if query.code_name.nil?
-                URL_TEMPLATE_TAXONOMIES
-              else
-                format(URL_TEMPLATE_TAXONOMY, query.code_name)
-              end
+              provide_taxonomy query
             when KenticoCloud::Delivery::QUERY_TYPE_ELEMENT
               format(URL_TEMPLATE_ELEMENTS, query.content_type, query.code_name)
             end
           end
 
-          # Returns the protocol and domain with project ID
+          def provide_item(query)
+            if query.code_name.nil?
+              URL_TEMPLATE_ITEMS
+            else
+              format(URL_TEMPLATE_ITEM, query.code_name)
+            end
+          end
+
+          def provide_taxonomy(query)
+            if query.code_name.nil?
+              URL_TEMPLATE_TAXONOMIES
+            else
+              format(URL_TEMPLATE_TAXONOMY, query.code_name)
+            end
+          end
+
+          def provide_type(query)
+            if query.code_name.nil?
+              URL_TEMPLATE_TYPES
+            else
+              format(URL_TEMPLATE_TYPE, query.code_name)
+            end
+          end
+
+          # Returns the protocol and domain with project ID. Domain changes
+          # according to the query's +use_preview+ attribute.
+          #
+          # * *Args*:
+          #   - *query* ( KenticoCloud::Delivery::DeliveryQuery )
+          #
+          # * *Returns*:
+          #   - +string+ The URL with the project ID
           def provide_base_url(query)
             if query.use_preview
               format(URL_TEMPLATE_PREVIEW, query.project_id)

data/lib/delivery/client/delivery_client.rb

@@ -14,6 +14,15 @@ module KenticoCloud
     class DeliveryClient
       attr_accessor :use_preview
 
+      # Constructor. Accepts a hash with the options for client.
+      #
+      # * *Args*:
+      #   - *config* (+Hash+) May contain the following keys:
+      #     - project_id (+string+) _required_
+      #     - preview_key (+string+)
+      #     - secure_key (+string+)
+      #     - content_link_url_resolver ( KenticoCloud::Delivery::Resolvers::ContentLinkResolver )
+      #     - inline_content_item_resolver ( KenticoCloud::Delivery::Resolvers::InlineContentItemResolver )
       def initialize(config)
         @project_id = config.fetch(:project_id)
         @preview_key = config.fetch(:preview_key, nil)
@@ -23,12 +32,23 @@ module KenticoCloud
         self.use_preview = !@preview_key.nil?
       end
 
+      # Return all content types of the project
+      #
+      # * *Returns*:
+      #   - KenticoCloud::Delivery::DeliveryQuery
       def types
         DeliveryQuery.new project_id: @project_id,
                           secure_key: @secure_key,
                           query_type: QUERY_TYPE_TYPES
       end
 
+      # Return a single content type of the project
+      #
+      # * *Args*:
+      #   - *code_name* (+string+) Code name of the desired content type
+      #
+      # * *Returns*:
+      #   - KenticoCloud::Delivery::DeliveryQuery
       def type(code_name)
         DeliveryQuery.new project_id: @project_id,
                           secure_key: @secure_key,
@@ -36,6 +56,13 @@ module KenticoCloud
                           query_type: QUERY_TYPE_TYPES
       end
 
+      # Return all content items of the project
+      #
+      # * *Args*:
+      #   - *query_parameters* (+Array+) _optional_ One or more KenticoCloud::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
+      #
+      # * *Returns*:
+      #   - KenticoCloud::Delivery::DeliveryQuery
       def items(query_parameters = [])
         q = DeliveryQuery.new project_id: @project_id,
                               secure_key: @secure_key,
@@ -48,6 +75,14 @@ module KenticoCloud
         q
       end
 
+      # Return a single content item of the project
+      #
+      # * *Args*:
+      #   - *code_name* (+string+) The code name of the desired content item
+      #   - *query_parameters* (+Array+) _optional_ One or more KenticoCloud::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
+      #
+      # * *Returns*:
+      #   - KenticoCloud::Delivery::DeliveryQuery
       def item(code_name, query_parameters = [])
         q = DeliveryQuery.new project_id: @project_id,
                               secure_key: @secure_key,
@@ -61,6 +96,13 @@ module KenticoCloud
         q
       end
 
+      # Return all taxonomy groups of the project
+      #
+      # * *Args*:
+      #   - *query_parameters* (+Array+) _optional_ One or more KenticoCloud::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
+      #
+      # * *Returns*:
+      #   - KenticoCloud::Delivery::DeliveryQuery
       def taxonomies(query_parameters = [])
         DeliveryQuery.new project_id: @project_id,
                           secure_key: @secure_key,
@@ -68,6 +110,13 @@ module KenticoCloud
                           query_type: QUERY_TYPE_TAXONOMIES
       end
 
+      # Return a single taxonomy group of the project
+      #
+      # * *Args*:
+      #   - *code_name* (+string+) The code name of the desired taxonomy group
+      #
+      # * *Returns*:
+      #   - KenticoCloud::Delivery::DeliveryQuery
       def taxonomy(code_name)
         DeliveryQuery.new project_id: @project_id,
                           secure_key: @secure_key,
@@ -75,6 +124,14 @@ module KenticoCloud
                           query_type: QUERY_TYPE_TAXONOMIES
       end
 
+      # Return a single element of a content type
+      #
+      # * *Args*:
+      #   - *content_type* (+string+) The code name of the content type containing the element
+      #   - *element* (+string+) The code name of the desired element
+      #
+      # * *Returns*:
+      #   - KenticoCloud::Delivery::DeliveryQuery
       def element(content_type, element)
         DeliveryQuery.new project_id: @project_id,
                           secure_key: @secure_key,