delivery-sdk-ruby 0.16.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: '0058d0fb12f1404bebdc08e2fcb411d4b4e2cc24a5314218f998d3f437797227'
4
- data.tar.gz: 2950d33463280e2eb7e2ffa653dd3c92fd28e0b465ad74405bd85730d3d86d82
3
+ metadata.gz: 6cc5777ca1aad7843166ac84a6af661c21882b20a00d21f93710bf1a06cae304
4
+ data.tar.gz: 140f1c745d5d38fd59448ff856e2203c2ba5c3c3ad37fc91cfc6410e5d666dba
5
5
  SHA512:
6
- metadata.gz: 821a6f42b2044340c81dbb9bb1e6b53a8a318374151cbf844fe7b845d66ddb9e671675a95b5663d4f223daeed1a7b1cb745d284a77a21600054939db75142c18
7
- data.tar.gz: f1c876ef295aa5b3637de511dbd8f40f1d62df18e89b613969e200f8d8696d6a435a6c947a3b19e04093a072aa005d3ead544b50275c895bbe64fbff98bd629d
6
+ metadata.gz: c9e45bca4d8dd901a849428ae90a4e3d28e38c06e859f48ffe481dda7fb0960f4dc79569d47368f3e0840052f02339f69aa1bd903db40e5d0a11bc09ff676318
7
+ data.tar.gz: 9e7e6ee1db6304034f39ed67935ea068d48dbcd1878c9d76a3fe17df5c30d3659f84f8e2ae817112377c850f5b868dec045693dc4da7976fa71773706c69a227
@@ -3,6 +3,11 @@ require 'delivery/query_parameters/query_string'
3
3
  module KenticoCloud
4
4
  module Delivery
5
5
  module Builders
6
+ # Provides methods for manipulating the URL of an asset to adjust the image's
7
+ # size, cropping behavior, background color, output format, and quality.
8
+ #
9
+ # See https://developer.kenticocloud.com/v1/reference#image-transformation and
10
+ # https://github.com/Kentico/delivery-sdk-ruby#image-transformation.
6
11
  class ImageTransformationBuilder
7
12
  FIT_MODE_CLIP = 'clip'.freeze
8
13
  FIT_MODE_SCALE = 'scale'.freeze
@@ -26,55 +31,119 @@ module KenticoCloud
26
31
  'See https://developer.kenticocloud.com/v1/reference#focal-point-crop'\
27
32
  'for more information.'.freeze
28
33
  ONE_TO_100 = 'Quality parameter must be between 1 and 100.'.freeze
29
- BOOLEAN_PARAM = 'The lossless parameter must be "true," "false," '\
30
- '1, or 0.'.freeze
34
+ BOOLEAN_PARAM = 'The parameter must be a boolean, 0, or 1.'.freeze
31
35
 
36
+ # Constructor. Generally, you obtain an +AssetURL+ object by calling
37
+ # KenticoCloud::Delivery::Builders::ImageTransformationBuilder.transform
38
+ # instead of using this constructor.
32
39
  def initialize(url)
33
40
  @url = url
34
41
  @query_string = KenticoCloud::Delivery::QueryParameters::QueryString.new
35
42
  end
36
43
 
44
+ # Applies all transformation options to the asset URL.
45
+ #
46
+ # * *Returns*:
47
+ # - +string+ The full URL to the asset with all query string parameters set
37
48
  def url
38
49
  @url + @query_string.to_s
39
50
  end
40
51
 
52
+ # Sets the width of the image
53
+ #
54
+ # * *Args*:
55
+ # - *width*
56
+ # - +integer+ Width in pixels, between 1 and 8192.
57
+ # - +float+ Width in percentage, between 0 and 1.
58
+ #
59
+ # * *Returns*:
60
+ # - +self+
41
61
  def with_width(width)
42
62
  @query_string.set_param 'w', width
43
63
  self
44
64
  end
45
65
 
66
+ # Sets the height of the image
67
+ #
68
+ # * *Args*:
69
+ # - *height*
70
+ # - +integer+ Height in pixels, between 1 and 8192.
71
+ # - +float+ Height in percentage, between 0 and 1.
72
+ #
73
+ # * *Returns* :
74
+ # - +self+
46
75
  def with_height(height)
47
76
  @query_string.set_param 'h', height
48
77
  self
49
78
  end
50
79
 
80
+ # Sets the device pixel ratio. Either width or height
81
+ # (or both) must be set.
82
+ #
83
+ # * *Args*:
84
+ # - *dpr* (+float+) Pixel ratio between 0 and 5.
85
+ #
86
+ # * *Returns*:
87
+ # - +self+
51
88
  def with_pixel_ratio(dpr)
52
89
  @query_string.set_param 'dpr', dpr
53
90
  self
54
91
  end
55
92
 
93
+ # Defines how the image is constrained while resizing. Either width
94
+ # or height (or both) must be set.
95
+ #
96
+ # * *Args*:
97
+ # - *fit* (+string+) Use constants from KenticoCloud::Delivery::Builders::ImageTransformationBuilder
98
+ #
99
+ # * *Returns*:
100
+ # - +self+
56
101
  def with_fit_mode(fit)
57
102
  @query_string.set_param 'fit', fit
58
103
  self
59
104
  end
60
105
 
106
+ # Selects a region of the image to perform transformations on.
61
107
  # Setting this will remove focal point cropping from the image,
62
108
  # as the two options are incompatible.
63
- # @param x
64
- # @param y
65
- # @param width
66
- # @param height
109
+ #
110
+ # * *Args*:
111
+ # - *x*
112
+ # - +integer+ The left border of the rect in pixels
113
+ # - +float+ The left border of the rect as a percentage between 0 and 1
114
+ # - *y*
115
+ # - +integer+ The top border of the rect in pixels
116
+ # - +float+ The top border of the rect as a percentage between 0 and 1
117
+ # - *width*
118
+ # - +integer+ The width of the rect in pixels
119
+ # - +float+ The width of the rect as a percentage between 0 and 1
120
+ # - *height*
121
+ # - +integer+ The height of the rect in pixels
122
+ # - +float+ The height of the rect as a percentage between 0 and 1
123
+ #
124
+ # * *Returns*:
125
+ # - +self+
67
126
  def with_rect(x, y, width, height)
68
127
  @query_string.remove_param 'fp-x'
69
128
  @query_string.remove_param 'fp-y'
70
129
  @query_string.remove_param 'fp-z'
71
- @query_string.remove_param 'crop', 'focalpoint'
130
+ @query_string.remove_param 'crop'
72
131
  @query_string.set_param 'rect', "#{x},#{y},#{width},#{height}"
73
132
  self
74
133
  end
75
134
 
135
+ # Sets the point of interest when cropping the image.
76
136
  # Setting this will remove the source rectangle region,
77
- # as the two options are incompatible.
137
+ # as the two options are incompatible. It also automatically sets the
138
+ # crop to "focalpoint" and fit to "crop"
139
+ #
140
+ # * *Args*:
141
+ # - *x* (+float+) Percentage of the image's width between 0 and 1
142
+ # - *y* (+float+) Percentage of the image's height between 0 and 1
143
+ # - *z* (+integer+) Amount of zoom to apply. A value of 1 is the default zoom, and each step represents 100% additional zoom.
144
+ #
145
+ # * *Returns*:
146
+ # - +self+
78
147
  def with_focal_point(x, y, z)
79
148
  raise ArgumentError, INVALID_PARAMS unless valid_dims?(x, y, z)
80
149
 
@@ -82,28 +151,50 @@ module KenticoCloud
82
151
  @query_string.set_param 'fp-x', x
83
152
  @query_string.set_param 'fp-y', y
84
153
  @query_string.set_param 'fp-z', z
154
+ @query_string.set_param 'fit', ImageTransformationBuilder::FIT_MODE_CROP
85
155
  @query_string.set_param 'crop', 'focalpoint'
86
156
  self
87
157
  end
88
158
 
89
- def valid_dims?(x, y, z)
90
- (x.to_f >= 0.0 && x.to_f <= 1.0) &&
91
- (y.to_f >= 0.0 && y.to_f <= 1.0) &&
92
- (z.to_i >= 1)
93
- end
94
-
95
- # Sets the background color.
96
- # @param [String] color a valid 3, 4, 6, or 8 digit hexadecimal color, without the # symbol
159
+ # Sets the background color of any transparent areas of the image.
160
+ #
161
+ # * *Args*:
162
+ # - *color* (+string+) A valid 3, 4, 6, or 8 digit hexadecimal color, without the # symbol
163
+ #
164
+ # * *Returns*:
165
+ # - +self+
97
166
  def with_background_color(color)
98
167
  @query_string.set_param 'bg', color
99
168
  self
100
169
  end
101
170
 
171
+ # Sets the output format of the request for the image.
172
+ #
173
+ # * *Args*:
174
+ # - *format* (+string+) Use constants from KenticoCloud::Delivery::Builders::ImageTransformationBuilder
175
+ #
176
+ # * *Returns*:
177
+ # - +self+
102
178
  def with_output_format(format)
103
179
  @query_string.set_param 'fm', format
104
180
  self
105
181
  end
106
182
 
183
+ # Configure the amount of compression for lossy file formats. Lower quality
184
+ # images will have a smaller file size. Only affects *jpg*, *pjpg*, and
185
+ # *webp* files.
186
+ #
187
+ # When no quality is specified for an image transformation, the default
188
+ # value of 85 is used.
189
+ #
190
+ # * *Args*:
191
+ # - *quality* (+integer+) The quality of the image between 1 and 100
192
+ #
193
+ # * *Returns*:
194
+ # - +self+
195
+ #
196
+ # * *Raises*:
197
+ # - +ArgumentError+ if +quality+ is not between 1 and 100 inclusive
107
198
  def with_quality(quality)
108
199
  raise ArgumentError, ONE_TO_100 unless quality.to_i >= 1 && quality.to_i <= 100
109
200
 
@@ -111,7 +202,20 @@ module KenticoCloud
111
202
  self
112
203
  end
113
204
 
114
- # Sets lossless to true or false. If true, automatically sets the format to WebP
205
+ # Sets the lossless parameter. If +true+, automatically sets the format
206
+ # to WebP.
207
+ #
208
+ # * *Args*:
209
+ # - *lossless*
210
+ # - +integer+ Either 1 or 0
211
+ # - +bool+ Either +true+ or +false+
212
+ # - +string+ Either 'true' or 'false'
213
+ #
214
+ # * *Returns*:
215
+ # - +self+
216
+ #
217
+ # * *Raises*:
218
+ # - +ArgumentError+ if +lossless+ cannot be parsed as a boolean
115
219
  def with_lossless(lossless)
116
220
  lossless = lossless.to_s.downcase
117
221
  raise ArgumentError, BOOLEAN_PARAM unless bool? lossless
@@ -121,15 +225,25 @@ module KenticoCloud
121
225
  self
122
226
  end
123
227
 
124
- def bool?(value)
125
- (value == 'true') ||
126
- (value == 'false') ||
127
- (value == '0') ||
128
- (value == '1')
129
- end
130
-
228
+ # Enables or disables automatic format selection. If enabled, it will
229
+ # override the format parameter and deliver WebP instead. If the browser
230
+ # does not support WebP, the value of the format parameter will be used.
231
+ #
232
+ # * *Args*:
233
+ # - *auto*
234
+ # - +integer+ Either 1 or 0
235
+ # - +bool+ Either +true+ or +false+
236
+ # - +string+ Either 'true' or 'false'
237
+ #
238
+ # * *Returns*:
239
+ # - +self+
240
+ #
241
+ # * *Raises*:
242
+ # - +ArgumentError+ if +auto+ cannot be parsed as a boolean
131
243
  def with_auto_format_selection(auto)
132
244
  auto = auto.to_s.downcase
245
+ raise ArgumentError, BOOLEAN_PARAM unless bool? auto
246
+
133
247
  if %w[true 1].include? auto
134
248
  @query_string.set_param 'auto', 'format'
135
249
  else
@@ -137,6 +251,18 @@ module KenticoCloud
137
251
  end
138
252
  self
139
253
  end
254
+
255
+ private
256
+
257
+ def valid_dims?(x, y, z)
258
+ (x.to_f >= 0.0 && x.to_f <= 1.0) &&
259
+ (y.to_f >= 0.0 && y.to_f <= 1.0) &&
260
+ (z.to_i >= 1)
261
+ end
262
+
263
+ def bool?(value)
264
+ %w[true false 0 1].include? value
265
+ end
140
266
  end
141
267
  end
142
268
  end
@@ -1,7 +1,7 @@
1
1
  module KenticoCloud
2
2
  module Delivery
3
3
  module Builders
4
- # Generates the URL required for Delivery REST API
4
+ # Internal class which generates the URL required for Delivery REST API
5
5
  class UrlBuilder
6
6
  URL_TEMPLATE_BASE = 'https://deliver.kenticocloud.com/%s'.freeze
7
7
  URL_TEMPLATE_PREVIEW = 'https://preview-deliver.kenticocloud.com/%s'.freeze
@@ -17,6 +17,14 @@ module KenticoCloud
17
17
  MSG_LONG_QUERY = 'The request url is too long. Split your query into multiple calls.'.freeze
18
18
 
19
19
  class << self
20
+ # Returns the proper domain for the request along with the
21
+ # query string parameters configured by the +DeliveryQuery+.
22
+ #
23
+ # * *Args*:
24
+ # - *query* ( KenticoCloud::Delivery::DeliveryQuery )
25
+ #
26
+ # * *Returns*:
27
+ # - +string+ The full URL for a Delivery request
20
28
  def provide_url(query)
21
29
  url = provide_base_url(query)
22
30
  url += provide_path_part(query)
@@ -28,39 +36,71 @@ module KenticoCloud
28
36
  end
29
37
  end
30
38
 
39
+ # Checks whether the provided URL is too long and raises an error if so.
40
+ #
41
+ # * *Args*:
42
+ # - *url* (+string+) A full Delivery URL
43
+ #
44
+ # * *Raises*:
45
+ # - +UriFormatException+ if the URL is 65,519 characters or more
31
46
  def validate_url(url)
32
47
  raise UriFormatException, MSG_LONG_QUERY if url.length > URL_MAX_LENGTH
33
48
  end
34
49
 
35
50
  private
36
51
 
37
- # Returns relative path part of URL depending on query type
52
+ # Returns relative path part of URL depending on query type.
53
+ #
54
+ # * *Args*:
55
+ # - *query* ( KenticoCloud::Delivery::DeliveryQuery )
56
+ #
57
+ # * *Returns*:
58
+ # - +string+ The URL path part (without protocol or domain)
38
59
  def provide_path_part(query)
39
60
  case query.query_type
40
61
  when KenticoCloud::Delivery::QUERY_TYPE_ITEMS
41
- if query.code_name.nil?
42
- URL_TEMPLATE_ITEMS
43
- else
44
- format(URL_TEMPLATE_ITEM, query.code_name)
45
- end
62
+ provide_item query
46
63
  when KenticoCloud::Delivery::QUERY_TYPE_TYPES
47
- if query.code_name.nil?
48
- URL_TEMPLATE_TYPES
49
- else
50
- format(URL_TEMPLATE_TYPE, query.code_name)
51
- end
64
+ provide_type query
52
65
  when KenticoCloud::Delivery::QUERY_TYPE_TAXONOMIES
53
- if query.code_name.nil?
54
- URL_TEMPLATE_TAXONOMIES
55
- else
56
- format(URL_TEMPLATE_TAXONOMY, query.code_name)
57
- end
66
+ provide_taxonomy query
58
67
  when KenticoCloud::Delivery::QUERY_TYPE_ELEMENT
59
68
  format(URL_TEMPLATE_ELEMENTS, query.content_type, query.code_name)
60
69
  end
61
70
  end
62
71
 
63
- # Returns the protocol and domain with project ID
72
+ def provide_item(query)
73
+ if query.code_name.nil?
74
+ URL_TEMPLATE_ITEMS
75
+ else
76
+ format(URL_TEMPLATE_ITEM, query.code_name)
77
+ end
78
+ end
79
+
80
+ def provide_taxonomy(query)
81
+ if query.code_name.nil?
82
+ URL_TEMPLATE_TAXONOMIES
83
+ else
84
+ format(URL_TEMPLATE_TAXONOMY, query.code_name)
85
+ end
86
+ end
87
+
88
+ def provide_type(query)
89
+ if query.code_name.nil?
90
+ URL_TEMPLATE_TYPES
91
+ else
92
+ format(URL_TEMPLATE_TYPE, query.code_name)
93
+ end
94
+ end
95
+
96
+ # Returns the protocol and domain with project ID. Domain changes
97
+ # according to the query's +use_preview+ attribute.
98
+ #
99
+ # * *Args*:
100
+ # - *query* ( KenticoCloud::Delivery::DeliveryQuery )
101
+ #
102
+ # * *Returns*:
103
+ # - +string+ The URL with the project ID
64
104
  def provide_base_url(query)
65
105
  if query.use_preview
66
106
  format(URL_TEMPLATE_PREVIEW, query.project_id)
@@ -14,6 +14,15 @@ module KenticoCloud
14
14
  class DeliveryClient
15
15
  attr_accessor :use_preview
16
16
 
17
+ # Constructor. Accepts a hash with the options for client.
18
+ #
19
+ # * *Args*:
20
+ # - *config* (+Hash+) May contain the following keys:
21
+ # - project_id (+string+) _required_
22
+ # - preview_key (+string+)
23
+ # - secure_key (+string+)
24
+ # - content_link_url_resolver ( KenticoCloud::Delivery::Resolvers::ContentLinkResolver )
25
+ # - inline_content_item_resolver ( KenticoCloud::Delivery::Resolvers::InlineContentItemResolver )
17
26
  def initialize(config)
18
27
  @project_id = config.fetch(:project_id)
19
28
  @preview_key = config.fetch(:preview_key, nil)
@@ -23,12 +32,23 @@ module KenticoCloud
23
32
  self.use_preview = !@preview_key.nil?
24
33
  end
25
34
 
35
+ # Return all content types of the project
36
+ #
37
+ # * *Returns*:
38
+ # - KenticoCloud::Delivery::DeliveryQuery
26
39
  def types
27
40
  DeliveryQuery.new project_id: @project_id,
28
41
  secure_key: @secure_key,
29
42
  query_type: QUERY_TYPE_TYPES
30
43
  end
31
44
 
45
+ # Return a single content type of the project
46
+ #
47
+ # * *Args*:
48
+ # - *code_name* (+string+) Code name of the desired content type
49
+ #
50
+ # * *Returns*:
51
+ # - KenticoCloud::Delivery::DeliveryQuery
32
52
  def type(code_name)
33
53
  DeliveryQuery.new project_id: @project_id,
34
54
  secure_key: @secure_key,
@@ -36,6 +56,13 @@ module KenticoCloud
36
56
  query_type: QUERY_TYPE_TYPES
37
57
  end
38
58
 
59
+ # Return all content items of the project
60
+ #
61
+ # * *Args*:
62
+ # - *query_parameters* (+Array+) _optional_ One or more KenticoCloud::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
63
+ #
64
+ # * *Returns*:
65
+ # - KenticoCloud::Delivery::DeliveryQuery
39
66
  def items(query_parameters = [])
40
67
  q = DeliveryQuery.new project_id: @project_id,
41
68
  secure_key: @secure_key,
@@ -48,6 +75,14 @@ module KenticoCloud
48
75
  q
49
76
  end
50
77
 
78
+ # Return a single content item of the project
79
+ #
80
+ # * *Args*:
81
+ # - *code_name* (+string+) The code name of the desired content item
82
+ # - *query_parameters* (+Array+) _optional_ One or more KenticoCloud::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
83
+ #
84
+ # * *Returns*:
85
+ # - KenticoCloud::Delivery::DeliveryQuery
51
86
  def item(code_name, query_parameters = [])
52
87
  q = DeliveryQuery.new project_id: @project_id,
53
88
  secure_key: @secure_key,
@@ -61,6 +96,13 @@ module KenticoCloud
61
96
  q
62
97
  end
63
98
 
99
+ # Return all taxonomy groups of the project
100
+ #
101
+ # * *Args*:
102
+ # - *query_parameters* (+Array+) _optional_ One or more KenticoCloud::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
103
+ #
104
+ # * *Returns*:
105
+ # - KenticoCloud::Delivery::DeliveryQuery
64
106
  def taxonomies(query_parameters = [])
65
107
  DeliveryQuery.new project_id: @project_id,
66
108
  secure_key: @secure_key,
@@ -68,6 +110,13 @@ module KenticoCloud
68
110
  query_type: QUERY_TYPE_TAXONOMIES
69
111
  end
70
112
 
113
+ # Return a single taxonomy group of the project
114
+ #
115
+ # * *Args*:
116
+ # - *code_name* (+string+) The code name of the desired taxonomy group
117
+ #
118
+ # * *Returns*:
119
+ # - KenticoCloud::Delivery::DeliveryQuery
71
120
  def taxonomy(code_name)
72
121
  DeliveryQuery.new project_id: @project_id,
73
122
  secure_key: @secure_key,
@@ -75,6 +124,14 @@ module KenticoCloud
75
124
  query_type: QUERY_TYPE_TAXONOMIES
76
125
  end
77
126
 
127
+ # Return a single element of a content type
128
+ #
129
+ # * *Args*:
130
+ # - *content_type* (+string+) The code name of the content type containing the element
131
+ # - *element* (+string+) The code name of the desired element
132
+ #
133
+ # * *Returns*:
134
+ # - KenticoCloud::Delivery::DeliveryQuery
78
135
  def element(content_type, element)
79
136
  DeliveryQuery.new project_id: @project_id,
80
137
  secure_key: @secure_key,