delivery-sdk-ruby 0.11.4 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93bedb0d59952488e4abf5736db0442a9fae71a990b454e843ce3781f23e357d
-  data.tar.gz: d6057dfc9b64c77131675037a7dcf9d29cd9c123908c2e318c65446b970d9e47
+  metadata.gz: 3af4e9e0b215b8ddfad6bef517543de085c0cfc86bd3da5e8139f63fa3c71d4c
+  data.tar.gz: 52f4765ebccf5b02a7c9c1410500a5e03022b789957c31c5d195150e83134ab3
 SHA512:
-  metadata.gz: 8cef13a61db0fe6fbbed38a9a2b31a9fcf318e82038a9a2111aee12aaacdee085f733cbf855725f543c06726528a3bbdde99ff2914a114cbbae76dda5f0c533c
-  data.tar.gz: 406c66405ea177a8b79dafa22f2d7b2fe8c74c31515884c88597146498251a789ad6d8f3f0f1fea9171d435f4b24867a6ac0a3cca9d1babfbd6a761f2f8d743c
+  metadata.gz: 3d09788c7f7cae943c864232babe39eee5d47c3c8f9857e3b4c2b6ce7fa19dca55074b0d170fb105574ea20a5a375bbc31bc35503c1dbcd76906e2ba78fc976b
+  data.tar.gz: 36a186c3972f83f5836ca29dedd28c6deeed6e7ee4b0fe97bb0478c9dcec5dba55d51906708dacf5014cbd187bed2989ed6bd5a26a6f3ca5788cc1b4597bc187

data/README.md

@@ -5,9 +5,27 @@
 
 The Delivery Ruby SDK can be used in Ruby/Rails projects to retrieve content from Kentico Cloud. This is a community project and not an official Kentico SDK. If you find a bug in the SDK or have a feature request, please submit a GitHub issue.
 
+## Demo Rails application
+
+This repository contains a very basic Rails application that you can run locally to see how the SDK can be used. To run the Dancing Goat demo application, clone this repository and open `/dancing_goat/app/controllers/application_controller.rb`. Add your project ID to the file here:
+
+```ruby
+class ApplicationController < ActionController::Base
+  PROJECT_ID = '<your-project-id>'.freeze
+```
+
+If you don't have the sample project installed in Kentico Cloud, you can generate a new project [here](https://app.kenticocloud.com/sample-project-generator). Save the file, then open a terminal in the `/dancing_goat` directory and run the following commands:
+
+```
+bundle install
+rails server
+```
+
+The site should be accessible at localhost:3000.
+
 ## Installation
 
-Add the gem to your Gemfile:
+To use the SDK in your own project, add the gem to your Gemfile:
 
 ```ruby
 gem 'delivery-sdk-ruby'
@@ -339,6 +357,33 @@ delivery_client.items
                .with_inline_content_item_resolver MyItemResolver.new
 ```
 
+## Image transformation
+
+When you've obtained the URL for an asset, you can use our [Image Transformation API](https://developer.kenticocloud.com/v1/reference#image-transformation) to make on-the-fly modifications to the image. To do this, use the static `.transform` method of `Delivery::Builders::ImageTransformationBuilder`, then call the transformation methods. When you're done, call the `.url` method to get the new URL:
+
+```ruby
+url = response.item.get_assets('teaser_image').first.url
+url = Delivery::Builders::ImageTransformationBuilder.transform(url)
+                                                    # methods...
+                                                    .url
+```
+
+The available methods are:
+
+|Method|Possible values|REST example
+|--|--|--|
+|`.with_width`| positive integer, or float between 0 and 1| ?w=200
+|`.with_height`| positive integer, or float between 0 and 1| ?h=200
+|`.with_pixel_ratio`| float greater than 0 but less than 5| ?dpr=1.5
+|`.with_fit_mode`| contstants available at Delivery::Builders::ImageTransformationBuilder <ul><li>FITMODE_CROP</li><li>FITMODE_CLIP</li><li>FITMODE_SCALE</li></ul>| ?fit=crop
+|`.with_rect`| 4 integer values representing pixels or floats representing percentages|rect=100,100,0.7,0.7
+|`.with_focal_point`| 2 floats between 0 and 1 and one integer between 1 and 100| ?fp-x=0.2&fp-y=0.7&fp-z=5
+|`.with_background_color`| string containing 3, 4, 6, or 8 characters | ?bg=7A0099EE
+|`.with_output_format`| contstants available at Delivery::Builders::ImageTransformationBuilder <ul><li>FORMAT_GIF</li><li>FORMAT_PNG</li><li>FORMAT_PNG8</li><li>FORMAT_JPG</li><li>FORMAT_PJPG</li><li>FORMAT_WEBP</li></ul> | ?fm=webp
+|`.with_quality`| integer between 1 to 100 | ?quality=50
+|`.with_lossless`| 'true', 'false', 0, or 1| ?lossless=1
+|`.with_auto_format_selection`| 'true', 'false', 0, or 1 | ?auto=format
+
 ## Feedback & Contributing
 
 Check out the [contributing](https://github.com/Kentico/delivery-sdk-ruby/blob/master/CONTRIBUTING.md) page to see the best places to file issues, start discussions, and begin contributing.

data/lib/delivery-sdk-ruby.rb

@@ -9,3 +9,4 @@ require File.dirname(__FILE__) + '/delivery/responses/delivery_type_listing_resp
 require File.dirname(__FILE__) + '/delivery/responses/delivery_type_response'
 require File.dirname(__FILE__) + '/delivery/resolvers/content_link_resolver'
 require File.dirname(__FILE__) + '/delivery/resolvers/inline_content_item_resolver'
+require File.dirname(__FILE__) + '/delivery/builders/image_transformation_builder'

data/lib/delivery/builders/image_transformation_builder.rb

@@ -0,0 +1,141 @@
+require 'delivery/query_parameters/query_string'
+
+module Delivery
+  module Builders
+    class ImageTransformationBuilder
+      FIT_MODE_CLIP = 'clip'.freeze
+      FIT_MODE_SCALE = 'scale'.freeze
+      FIT_MODE_CROP = 'crop'.freeze
+      FORMAT_GIF = 'gif'.freeze
+      FORMAT_PNG = 'png'.freeze
+      FORMAT_PNG8 = 'png8'.freeze
+      FORMAT_JPG = 'jpg'.freeze
+      FORMAT_PJPG = 'pjpg'.freeze
+      FORMAT_WEBP = 'webp'.freeze
+
+      class << self
+        def transform(url)
+          AssetURL.new url
+        end
+      end
+    end
+
+    class AssetURL
+      INVALID_PARAMS = 'One or more of the parameters is invalid. '\
+      '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
+
+      def initialize(url)
+        @url = url
+        @query_string = Delivery::QueryParameters::QueryString.new
+      end
+
+      def url
+        @url + @query_string.to_s
+      end
+
+      def with_width(width)
+        @query_string.set_param 'w', width
+        self
+      end
+
+      def with_height(height)
+        @query_string.set_param 'h', height
+        self
+      end
+
+      def with_pixel_ratio(dpr)
+        @query_string.set_param 'dpr', dpr
+        self
+      end
+
+      def with_fit_mode(fit)
+        @query_string.set_param 'fit', fit
+        self
+      end
+
+      # Setting this will remove focal point cropping from the image,
+      # as the two options are incompatible.
+      # @param x
+      # @param y
+      # @param width
+      # @param height
+      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.set_param 'rect', "#{x},#{y},#{width},#{height}"
+        self
+      end
+
+      # Setting this will remove the source rectangle region,
+      # as the two options are incompatible.
+      def with_focal_point(x, y, z)
+        raise ArgumentError, INVALID_PARAMS unless valid_dims?(x, y, z)
+
+        @query_string.remove_param 'rect'
+        @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 '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
+      def with_background_color(color)
+        @query_string.set_param 'bg', color
+        self
+      end
+
+      def with_output_format(format)
+        @query_string.set_param 'fm', format
+        self
+      end
+
+      def with_quality(quality)
+        raise ArgumentError, ONE_TO_100 unless quality.to_i >= 1 && quality.to_i <= 100
+
+        @query_string.set_param 'q', quality
+        self
+      end
+
+      # Sets lossless to true or false. If true, automatically sets the format to WebP
+      def with_lossless(lossless)
+        lossless = lossless.to_s.downcase
+        raise ArgumentError, BOOLEAN_PARAM unless bool? lossless
+
+        @query_string.set_param 'lossless', lossless
+        @query_string.set_param 'fm', Delivery::Builders::ImageTransformationBuilder::FORMAT_WEBP if %w[true 1].include? lossless
+        self
+      end
+
+      def bool?(value)
+        (value == 'true') ||
+          (value == 'false') ||
+          (value == '0') ||
+          (value == '1')
+      end
+
+      def with_auto_format_selection(auto)
+        auto = auto.to_s.downcase
+        if %w[true 1].include? auto
+          @query_string.set_param 'auto', 'format'
+        else
+          @query_string.remove_param 'auto'
+        end
+        self
+      end
+    end
+  end
+end

data/lib/delivery/builders/url_builder.rb

@@ -0,0 +1,65 @@
+module Delivery
+  module Builders
+    # 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
+      URL_TEMPLATE_ITEM = '/items/%s'.freeze
+      URL_TEMPLATE_ITEMS = '/items'.freeze
+      URL_TEMPLATE_TYPE = '/types/%s'.freeze
+      URL_TEMPLATE_TYPES = '/types'.freeze
+      URL_TEMPLATE_ELEMENTS = '/types/%s/elements/%s'.freeze
+      URL_TEMPLATE_TAXONOMY = '/taxonomies/%s'.freeze
+      URL_TEMPLATE_TAXONOMIES = '/taxonomies'.freeze
+
+      URL_MAX_LENGTH = 65_519
+      MSG_LONG_QUERY = 'The request url is too long. Split your query into multiple calls.'.freeze
+
+      class << self
+        def provide_url(query)
+          url = provide_base_url(query)
+          url += provide_path_part(query)
+
+          if query.query_string.empty?
+            url
+          else
+            url + query.query_string.to_s
+          end
+        end
+
+        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
+        def provide_path_part(query)
+          case query.query_type
+          when Delivery::QUERY_TYPE_ITEMS
+            if query.code_name.nil?
+              URL_TEMPLATE_ITEMS
+            else
+              format(URL_TEMPLATE_ITEM, query.code_name)
+            end
+          when Delivery::QUERY_TYPE_TYPES
+            if query.code_name.nil?
+              URL_TEMPLATE_TYPES
+            else
+              format(URL_TEMPLATE_TYPE, query.code_name)
+            end
+          end
+        end
+
+        # Returns the protocol and domain with project ID
+        def provide_base_url(query)
+          if query.use_preview
+            format(URL_TEMPLATE_PREVIEW, query.project_id)
+          else
+            format(URL_TEMPLATE_BASE, query.project_id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/client/delivery_query.rb

@@ -1,5 +1,6 @@
 require 'rest-client'
-require 'delivery/client/url_provider'
+require 'delivery/builders/url_builder'
+require 'delivery/query_parameters/query_string'
 
 module Delivery
   # Responsible for translating query parameters into the
@@ -15,11 +16,11 @@ module Delivery
                   :preview_key,
                   :project_id,
                   :code_name,
-                  :params,
                   :secure_key,
                   :content_link_url_resolver,
                   :inline_content_item_resolver,
-                  :query_type
+                  :query_type,
+                  :query_string
 
     # Setter for url, returns self for chaining
     # .url represents *manually* configured urls, otherwise final url is
@@ -35,6 +36,7 @@ module Delivery
       config.each do |k, v|
         instance_variable_set("@#{k}", v) unless v.nil?
       end
+      self.query_string = Delivery::QueryParameters::QueryString.new
       return if config.fetch(:qp, nil).nil?
 
       # Query parameters were passed, parse and validate
@@ -70,60 +72,55 @@ module Delivery
     end
 
     def order_by(value, sort = '[asc]')
-      set_param('order', value + sort)
+      query_string.set_param('order', value + sort)
       self
     end
 
     def skip(value)
-      set_param('skip', value)
+      query_string.set_param('skip', value)
       self
     end
 
     def language(value)
-      set_param('language', value)
+      query_string.set_param('language', value)
     end
 
     def limit(value)
-      set_param('limit', value)
+      query_string.set_param('limit', value)
       self
     end
 
     def elements(value)
-      set_param('elements', value)
+      query_string.set_param('elements', value)
       self
     end
 
     def depth(value)
-      set_param('depth', value)
+      query_string.set_param('depth', value)
       self
     end
 
     private
 
     def provide_url
-      @url = Delivery::UrlProvider.provide_url self if @url.nil?
-      Delivery::UrlProvider.validate_url @url
+      @url = Delivery::Builders::UrlBuilder.provide_url self if @url.nil?
+      Delivery::Builders::UrlBuilder.validate_url @url
     end
 
     def validate_params(query_parameters)
-      self.params = if query_parameters.is_a? Array
-                      query_parameters
-                    else
-                      [query_parameters]
-                    end
+      params = if query_parameters.is_a? Array
+                 query_parameters
+               else
+                 [query_parameters]
+               end
       params.each do |p|
+        query_string.set_param p
         unless p.is_a? Delivery::QueryParameters::Filter
           raise ArgumentError, ERROR_PARAMS
         end
       end
     end
 
-    def set_param(key, value)
-      self.params = [] if params.nil?
-      remove_existing_param key
-      params << Delivery::QueryParameters::ParameterBase.new(key, '', value)
-    end
-
     # Returns true if this query should use preview mode. Raises an error if
     # preview is enabled, but the key is nil
     def should_preview
@@ -168,10 +165,5 @@ module Delivery
         end
       end
     end
-
-    # Remove existing parameter from @params if key exists
-    def remove_existing_param(key)
-      params.delete_if { |i| i.key.eql? key } unless params.nil?
-    end
   end
 end

data/lib/delivery/query_parameters/query_string.rb

@@ -0,0 +1,49 @@
+require 'delivery/query_parameters/parameter_base'
+
+module Delivery
+  module QueryParameters
+    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
+      def set_param(param, values = '', operator = '')
+        parameter_base =
+          if param.is_a? String
+            Delivery::QueryParameters::ParameterBase.new(
+              param,
+              operator,
+              values
+            )
+          else
+            param
+          end
+        # Ensure we have a ParameterBase object
+        return unless parameter_base.respond_to? 'provide_query_string_parameter'
+
+        remove_param parameter_base.key
+        @params << parameter_base
+      end
+
+      def remove_param(key)
+        @params.delete_if { |i| i.key.eql? key }
+      end
+
+      def param(key)
+        @params.select { |p| p.key.eql? key }
+      end
+
+      def empty?
+        @params.empty?
+      end
+
+      def to_s
+        '?' + @params.map(&:provide_query_string_parameter).join('&')
+      end
+    end
+  end
+end

data/lib/delivery/version.rb

@@ -1,3 +1,3 @@
 module Delivery
-  VERSION = '0.11.4'.freeze
+  VERSION = '0.12.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: delivery-sdk-ruby
 version: !ruby/object:Gem::Version
-  version: 0.11.4
+  version: 0.12.0
 platform: ruby
 authors:
 - Eric Dugre
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-02-19 00:00:00.000000000 Z
+date: 2019-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -104,14 +104,16 @@ files:
 - bin/console
 - bin/setup
 - lib/delivery-sdk-ruby.rb
+- lib/delivery/builders/image_transformation_builder.rb
+- lib/delivery/builders/url_builder.rb
 - lib/delivery/client/delivery_client.rb
 - lib/delivery/client/delivery_query.rb
-- lib/delivery/client/url_provider.rb
 - lib/delivery/models/content_item.rb
 - lib/delivery/models/content_type.rb
 - lib/delivery/models/pagination.rb
 - lib/delivery/query_parameters/filters.rb
 - lib/delivery/query_parameters/parameter_base.rb
+- lib/delivery/query_parameters/query_string.rb
 - lib/delivery/resolvers/content_link_resolver.rb
 - lib/delivery/resolvers/inline_content_item_resolver.rb
 - lib/delivery/responses/delivery_item_listing_response.rb

data/lib/delivery/client/url_provider.rb

@@ -1,64 +0,0 @@
-module Delivery
-  # Generates the URL required for Delivery REST API
-  class UrlProvider
-    URL_TEMPLATE_BASE = 'https://deliver.kenticocloud.com/%s'.freeze
-    URL_TEMPLATE_PREVIEW = 'https://preview-deliver.kenticocloud.com/%s'.freeze
-    URL_TEMPLATE_ITEM = '/items/%s'.freeze
-    URL_TEMPLATE_ITEMS = '/items'.freeze
-    URL_TEMPLATE_TYPE = '/types/%s'.freeze
-    URL_TEMPLATE_TYPES = '/types'.freeze
-    URL_TEMPLATE_ELEMENTS = '/types/%s/elements/%s'.freeze
-    URL_TEMPLATE_TAXONOMY = '/taxonomies/%s'.freeze
-    URL_TEMPLATE_TAXONOMIES = '/taxonomies'.freeze
-
-    URL_MAX_LENGTH = 65_519
-    MSG_LONG_QUERY = 'The request url is too long. Split your query into multiple calls.'.freeze
-
-    class << self
-      def provide_url(query)
-        url = provide_base_url(query)
-        url += provide_path_part(query)
-
-        if query.params.nil?
-          url
-        else
-          # Map each parameter to the result of a method and separate with &
-          url + '?' + query.params.map(&:provide_query_string_parameter).join('&')
-        end
-      end
-
-      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
-      def provide_path_part(query)
-        case query.query_type
-        when Delivery::QUERY_TYPE_ITEMS
-          if query.code_name.nil?
-            URL_TEMPLATE_ITEMS
-          else
-            format(URL_TEMPLATE_ITEM, query.code_name)
-          end
-        when Delivery::QUERY_TYPE_TYPES
-          if query.code_name.nil?
-            URL_TEMPLATE_TYPES
-          else
-            format(URL_TEMPLATE_TYPE, query.code_name)
-          end
-        end
-      end
-
-      # Returns the protocol and domain with project ID
-      def provide_base_url(query)
-        if query.use_preview
-          format(URL_TEMPLATE_PREVIEW, query.project_id)
-        else
-          format(URL_TEMPLATE_BASE, query.project_id)
-        end
-      end
-    end
-  end
-end