delivery-sdk-ruby 1.0.9 → 2.0.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (29) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +47 -46
  3. data/lib/delivery/builders/image_transformation_builder.rb +239 -237
  4. data/lib/delivery/builders/url_builder.rb +95 -93
  5. data/lib/delivery/client/delivery_client.rb +137 -135
  6. data/lib/delivery/client/delivery_query.rb +222 -220
  7. data/lib/delivery/client/request_manager.rb +83 -81
  8. data/lib/delivery/models/content_item.rb +132 -130
  9. data/lib/delivery/models/content_type.rb +33 -31
  10. data/lib/delivery/models/pagination.rb +16 -14
  11. data/lib/delivery/models/taxonomy_group.rb +33 -31
  12. data/lib/delivery/query_parameters/filters.rb +36 -34
  13. data/lib/delivery/query_parameters/parameter_base.rb +37 -35
  14. data/lib/delivery/query_parameters/query_string.rb +65 -63
  15. data/lib/delivery/resolvers/content_link_resolver.rb +85 -83
  16. data/lib/delivery/resolvers/inline_content_item_resolver.rb +61 -59
  17. data/lib/delivery/resolvers/linked_item_resolver.rb +29 -27
  18. data/lib/delivery/responses/delivery_element_response.rb +25 -23
  19. data/lib/delivery/responses/delivery_item_listing_response.rb +41 -39
  20. data/lib/delivery/responses/delivery_item_response.rb +30 -28
  21. data/lib/delivery/responses/delivery_taxonomy_listing_response.rb +33 -31
  22. data/lib/delivery/responses/delivery_taxonomy_response.rb +22 -20
  23. data/lib/delivery/responses/delivery_type_listing_response.rb +33 -31
  24. data/lib/delivery/responses/delivery_type_response.rb +22 -20
  25. data/lib/delivery/responses/response_base.rb +29 -27
  26. data/lib/delivery/tests/fake_responder.rb +50 -48
  27. data/lib/delivery/version.rb +5 -3
  28. data/lib/kontent-delivery-sdk-ruby.rb +19 -0
  29. metadata +10 -9
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 810bf0eebd44bb2fee47eebfe0920020052b093dd9c35d93d82aa2789e47b3f0
4
- data.tar.gz: 7e7da7f14b27e2818682dac4a0560cc0e38349832a218d328cb7ff0bece752cc
3
+ metadata.gz: b7c12c35f279bbc41dbdc875ec09e599796708653e2d7a3f805e0576dd7ac03c
4
+ data.tar.gz: ebb3e28b29c84d7e8e3b694d1f6fa4c9999621fb426e7e1a0b62a03dad2a80e5
5
5
  SHA512:
6
- metadata.gz: 72074bfb5bf3a63b381aff2ce362bc826f423f3b20ee62b88e8605b9b7993b25a442c6ca7fc734cdab2b7af7dd364ff289b5094a702dd7d1c6a1d34b26727f08
7
- data.tar.gz: 8804147c3766b7fd4934cb4e285a080700c4d865a78d84538661bff769256738ec4231f0759a8dc73d9cf1d0ab5a53631eeb55e8f9cbbd1fc3d7f189b719d80e
6
+ metadata.gz: 6887dbaac36af78ba9e798141e351b0b001628b4ef6a291ff268e1f4a05e864b038353a9b6b926a23c6700ec6788a17d7d075523c1e5ee736021f3b5413e5abc
7
+ data.tar.gz: 0b6b5c0fca8a2a0e93b24ab91dab06b679735e8b5dcc949a0c9463c918582afcf9847e468ed4c8436c707ce1249bf11eb350f85bebe94cb6c670c12708000803
data/README.md CHANGED
@@ -1,16 +1,17 @@
1
- [![Build Status](https://api.travis-ci.com/Kentico/delivery-sdk-ruby.svg?branch=master)](https://travis-ci.com/Kentico/delivery-sdk-ruby)
1
+ [![Build Status](https://api.travis-ci.com/Kentico/kontent-delivery-sdk-ruby.svg?branch=master)](https://travis-ci.com/Kentico/kontent-delivery-sdk-ruby)
2
2
  [![Join the chat at https://kentico-community.slack.com](https://img.shields.io/badge/join-slack-E6186D.svg)](https://kentico-community.slack.com)
3
3
  [![Stack Overflow](https://img.shields.io/badge/Stack%20Overflow-ASK%20NOW-FE7A16.svg?logo=stackoverflow&logoColor=white)](https://stackoverflow.com/tags/kentico-cloud)
4
- [![Version](https://img.shields.io/gem/v/delivery-sdk-ruby.svg?style=flat)](https://rubygems.org/gems/delivery-sdk-ruby)
5
- [![Maintainability](https://api.codeclimate.com/v1/badges/b2e3fae28a2b2601d815/maintainability)](https://codeclimate.com/github/Kentico/delivery-sdk-ruby/maintainability)
4
+ [![Version](https://img.shields.io/gem/v/kontent-delivery-sdk-ruby.svg?style=flat)](https://rubygems.org/gems/kontent-delivery-sdk-ruby)
5
+ [![Maintainability](https://api.codeclimate.com/v1/badges/b2e3fae28a2b2601d815/maintainability)](https://codeclimate.com/github/Kentico/kontent-delivery-sdk-ruby/maintainability)
6
+ [![Test coverage](https://api.codeclimate.com/v1/badges/b2e3fae28a2b2601d815/test_coverage)](https://codeclimate.com/github/Kentico/delivery-sdk-ruby/test_coverage)
6
7
 
7
8
  # Delivery Ruby SDK
8
9
 
9
- ![Banner](https://github.com/Kentico/delivery-sdk-ruby/blob/master/banner.png)
10
+ ![Banner](https://github.com/Kentico/kontent-delivery-sdk-ruby/blob/master/banner.png)
10
11
 
11
12
  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.
12
13
 
13
- See [How to setup a development environment on Windows](https://github.com/Kentico/delivery-sdk-ruby/wiki/How-to-setup-development-environment-on-Windows) for local development.
14
+ See [How to setup a development environment on Windows](https://github.com/Kentico/kontent-delivery-sdk-ruby/wiki/How-to-setup-development-environment-on-Windows) for local development.
14
15
 
15
16
 
16
17
  ## Demo Rails application
@@ -22,42 +23,42 @@ class ApplicationController < ActionController::Base
22
23
  PROJECT_ID = '<your-project-id>'.freeze
23
24
  ```
24
25
 
25
- 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:
26
+ If you don't have the sample project installed in Kentico Cloud, you can generate a new project [here](https://app.kontent.ai/sample-project-generator). Save the file, then open a terminal in the `/dancing_goat` directory and run the following commands:
26
27
 
27
28
  ```
28
29
  bundle install
29
30
  rails server
30
31
  ```
31
32
 
32
- The site should be accessible at localhost:3000. You can also follow a step-by-step guide to creating a basic Rails application on the [Kentico Cloud Blog](https://kenticocloud.com/blog/creating-a-kentico-cloud-ruby-on-rails-application).
33
+ The site should be accessible at localhost:3000. You can also follow a step-by-step guide to creating a basic Rails application on the [Kentico Cloud Blog](https://kontent.ai/blog/creating-a-kentico-cloud-ruby-on-rails-application).
33
34
 
34
35
  ## Installation
35
36
 
36
37
  To use the SDK in your own project, add the gem to your Gemfile:
37
38
 
38
39
  ```ruby
39
- gem 'delivery-sdk-ruby'
40
+ gem 'kontent-delivery-sdk-ruby'
40
41
  ```
41
42
 
42
- Then run `bundle install`. You can also download the gem from [RubyGems.org](https://rubygems.org/gems/delivery-sdk-ruby). To use the SDK in an `.rb` file, you need to require it:
43
+ Then run `bundle install`. You can also download the gem from [RubyGems.org](https://rubygems.org/gems/kontent-delivery-sdk-ruby). To use the SDK in an `.rb` file, you need to require it:
43
44
 
44
45
  ```ruby
45
- require 'delivery-sdk-ruby'
46
+ require 'kontent-delivery-sdk-ruby'
46
47
  ```
47
48
 
48
49
  ## Creating a client
49
50
 
50
- You will use `KenticoCloud::Delivery::DeliveryClient` to obtain content from Kentico Cloud. Create an instance of the client and pass your project ID:
51
+ You will use `Kentico::Kontent::Delivery::DeliveryClient` to obtain content from Kentico Cloud. Create an instance of the client and pass your project ID:
51
52
 
52
53
  ```ruby
53
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>'
54
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>'
54
55
  ```
55
56
 
56
57
  :gem: **Pro tip:** You can alias namespaces to make them shorter, e.g.
57
58
 
58
59
  ```ruby
59
- KC = KenticoCloud::Delivery
60
- delivery_client = KC::DeliveryClient.new project_id: '<your-project-id>'
60
+ KK = Kentico::Kontent::Delivery
61
+ delivery_client = KK::DeliveryClient.new project_id: '<your-project-id>'
61
62
  ```
62
63
 
63
64
  ### Previewing unpublished content
@@ -65,8 +66,8 @@ delivery_client = KC::DeliveryClient.new project_id: '<your-project-id>'
65
66
  To enable [preview](https://developer.kenticocloud.com/docs/previewing-content-in-a-separate-environment "preview"), pass the Preview API Key to the constructor:
66
67
 
67
68
  ```ruby
68
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
69
- preview_key: '<your-preview-key>'
69
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>',
70
+ preview_key: '<your-preview-key>'
70
71
  ```
71
72
 
72
73
  This enables preview, but you can toggle preview at any time by setting the `use_preview` attribute of DeliveryClient which is propogated to all queries created by the client, _or_ per-query by setting it's `use_preview` attribute:
@@ -88,7 +89,7 @@ end
88
89
  If you've [secured access](https://developer.kenticocloud.com/docs/securing-public-access "Securing public access") to your project, you need to provide the DeliveryClient with the primary or secondary key:
89
90
 
90
91
  ```ruby
91
- KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
92
+ Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>',
92
93
  secure_key: '<your-secure-key>'
93
94
  ```
94
95
 
@@ -107,7 +108,7 @@ The default policy retries requests 5 times, totaling 6 overall attempts to retr
107
108
  To disable the retry policy, you can use the `with_retry_policy` argument:
108
109
 
109
110
  ```ruby
110
- KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
111
+ Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>',
111
112
  secure_key: '<your-secure-key>',
112
113
  with_retry_policy: false
113
114
  ```
@@ -115,7 +116,7 @@ KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
115
116
  ## Listing items
116
117
 
117
118
 
118
- Use `.item` or `.items` to create a `KenticoCloud::Delivery::DeliveryQuery`, then call `.execute` to perform the request.
119
+ Use `.item` or `.items` to create a `Kentico::Kontent::Delivery::DeliveryQuery`, then call `.execute` to perform the request.
119
120
 
120
121
  ```ruby
121
122
  delivery_client.items.execute do |response|
@@ -163,7 +164,7 @@ delivery_client.items [
163
164
 
164
165
  ### Parameters
165
166
 
166
- The `.item` and `.items` methods return a `KenticoCloud::Delivery::DeliveryQuery` object which you can further configure before executing. The methods you can call are:
167
+ The `.item` and `.items` methods return a `Kentico::Kontent::Delivery::DeliveryQuery` object which you can further configure before executing. The methods you can call are:
167
168
 
168
169
  |Method|Example|REST equivalent
169
170
  |--|--|--|
@@ -204,7 +205,7 @@ When you have a URL (i.e. `next_page` for paging, for testing purposes, or if yo
204
205
 
205
206
  ```ruby
206
207
  delivery_client.items
207
- .url('https://deliver.kenticocloud.com/<your-project-id>/items?system.type=grinder')
208
+ .url('https://deliver.kontent.ai/<your-project-id>/items?system.type=grinder')
208
209
  .execute do |response|
209
210
  # Do something
210
211
  end
@@ -212,7 +213,7 @@ delivery_client.items
212
213
 
213
214
  ### Responses
214
215
 
215
- All responses from the `.execute` method will be/extend the `KenticoCloud::Delivery::Responses::ResponseBase` class which contains an `http_code` attribute and a friendly message that can be displayed by calling `.to_s`. You can check the code to determine if the request was successful:
216
+ All responses from the `.execute` method will be/extend the `Kentico::Kontent::Delivery::Responses::ResponseBase` class which contains an `http_code` attribute and a friendly message that can be displayed by calling `.to_s`. You can check the code to determine if the request was successful:
216
217
 
217
218
  ```ruby
218
219
  delivery_client.items.execute do |response|
@@ -298,7 +299,7 @@ end
298
299
 
299
300
  ### Responses
300
301
 
301
- As with content item queries, all content type queries will return a `KenticoCloud::Delivery::Responses::ResponseBase` of the class `DeliveryTypeResponse` or `DeliveryTypeListingResponse` for single and multiple type queries, respectively.
302
+ As with content item queries, all content type queries will return a `Kentico::Kontent::Delivery::Responses::ResponseBase` of the class `DeliveryTypeResponse` or `DeliveryTypeListingResponse` for single and multiple type queries, respectively.
302
303
 
303
304
  For multiple type queries, you can access the array of `ContentType` objects at `.types`, and at `.type` for singe type queries. You can access information about the type(s) dynamically:
304
305
 
@@ -327,7 +328,7 @@ delivery_client.taxonomy('personas').execute do |response|
327
328
  end
328
329
  ```
329
330
 
330
- Each response will return either a single `KenticoCloud::Delivery::TaxonomyGroup` or an array of groups. The taxonomy group(s) are accessible at `.taxonomy` and `.taxonomies` for single and multiple queries, respectively.
331
+ Each response will return either a single `Kentico::Kontent::Delivery::TaxonomyGroup` or an array of groups. The taxonomy group(s) are accessible at `.taxonomy` and `.taxonomies` for single and multiple queries, respectively.
331
332
 
332
333
  The `TaxonomyGroup` object contains two attributes `.system` and `.terms` which are dynamic OStruct objects containing the same elements as a standard JSON reponse. For example, given a successful query you could access information about the first term of a group using:
333
334
 
@@ -362,16 +363,16 @@ delivery_client.element('brewer', 'product_status').execute do |response|
362
363
  end
363
364
  ```
364
365
 
365
- This returns a `KenticoCloud::Delivery::Responses::DeliveryElementResponse` where the `element` attribute is a dynamic OStruct representation of the JSON response. This means that you can access any property of the element by simply typing the name as in the above example.
366
+ This returns a `Kentico::Kontent::Delivery::Responses::DeliveryElementResponse` where the `element` attribute is a dynamic OStruct representation of the JSON response. This means that you can access any property of the element by simply typing the name as in the above example.
366
367
 
367
368
  The element will always contain __codename__, __type__, and __name__, but multiple choice elements will also contain __options__ and taxonomy elements will contain __taxonomy_group__. The Ruby SDK fully supports obtaining [custom elements](https://developer.kenticocloud.com/v1/reference#custom-elements-api) using this approach and any other methods.
368
369
 
369
370
  ## Resolving links
370
371
 
371
- If a rich text element contains links to other content items, you will need to generate the URLs to those items. You can do this by registering a `KenticoCloud::Delivery::Resolvers::ContentLinkResolver` when you instantiate the DeliveryClient. When you create a ContentLinkResolver, you must pass a method that will return the URL, and you may pass another method that will be called if the content contains a link, but the content item is not present in the response:
372
+ If a rich text element contains links to other content items, you will need to generate the URLs to those items. You can do this by registering a `Kentico::Kontent::Delivery::Resolvers::ContentLinkResolver` when you instantiate the DeliveryClient. When you create a ContentLinkResolver, you must pass a method that will return the URL, and you may pass another method that will be called if the content contains a link, but the content item is not present in the response:
372
373
 
373
374
  ```ruby
374
- link_resolver = KenticoCloud::Delivery::Resolvers::ContentLinkResolver.new(lambda do |link|
375
+ link_resolver = Kentico::Kontent::Delivery::Resolvers::ContentLinkResolver.new(lambda do |link|
375
376
  # Link valid
376
377
  return "/coffees/#{link.url_slug}" if link.type.eql? 'coffee'
377
378
  return "/brewers/#{link.url_slug}" if link.type.eql? 'brewer'
@@ -379,14 +380,14 @@ link_resolver = KenticoCloud::Delivery::Resolvers::ContentLinkResolver.new(lambd
379
380
  # Link broken
380
381
  return "/notfound?id=#{id}"
381
382
  end)
382
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
383
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>',
383
384
  content_link_url_resolver: link_resolver
384
385
  ```
385
386
 
386
- You can also build the logic for your resolver in a separate class and register an instance of that class in the DeliveryClient. The class must extend `KenticoCloud::Delivery::Resolvers::ContentLinkResolver` and contain a `resolve_link(link)` method, as well as the `resolve_404(id)` method for broken links. For example, you can create `MyLinkResolver.rb`:
387
+ You can also build the logic for your resolver in a separate class and register an instance of that class in the DeliveryClient. The class must extend `Kentico::Kontent::Delivery::Resolvers::ContentLinkResolver` and contain a `resolve_link(link)` method, as well as the `resolve_404(id)` method for broken links. For example, you can create `MyLinkResolver.rb`:
387
388
 
388
389
  ```ruby
389
- class MyLinkResolver < KenticoCloud::Delivery::Resolvers::ContentLinkResolver
390
+ class MyLinkResolver < Kentico::Kontent::Delivery::Resolvers::ContentLinkResolver
390
391
  def resolve_link(link)
391
392
  return "/coffees/#{link.url_slug}" if link.type.eql? 'coffee'
392
393
  return "/brewers/#{link.url_slug}" if link.type.eql? 'brewer'
@@ -401,14 +402,14 @@ end
401
402
  Then create an object of this class when instantiating the DeliveryClient:
402
403
 
403
404
  ```ruby
404
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
405
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>',
405
406
  content_link_url_resolver: MyLinkResolver.new
406
407
  ```
407
408
 
408
409
  You can pass a `ContentLinkResolver` to the DeliveryQuery instead of the client if you only want to resolve links for that query, or they should be resolved differently:
409
410
 
410
411
  ```ruby
411
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>'
412
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>'
412
413
  # Client doesn't use ContentLinkResolver, but query below will
413
414
  delivery_client.items
414
415
  .with_link_resolver MyLinkResolver.new
@@ -424,11 +425,11 @@ The `ContentLink` object that is passed to your resolver contains the following
424
425
  To resolve links in rich text elements, you must retrieve the text using `get_string`:
425
426
 
426
427
  ```ruby
427
- item_resolver = KenticoCloud::Delivery::Resolvers::ContentLinkResolver.new(lambda do |link|
428
+ item_resolver = Kentico::Kontent::Delivery::Resolvers::ContentLinkResolver.new(lambda do |link|
428
429
  return "/coffees/#{link.url_slug}" if link.type.eql? 'coffee'
429
430
  return "/brewers/#{link.url_slug}" if link.type.eql? 'brewer'
430
431
  end)
431
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
432
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>',
432
433
  content_link_url_resolver: item_resolver
433
434
  delivery_client.item('coffee_processing_techniques').execute do |response|
434
435
  text = response.item.get_string 'body_copy'
@@ -440,18 +441,18 @@ end
440
441
  Existing content items can be inserted into a rich text element, or you can create new content items as components. You need to resolve these in your application just as with content links. You can register a resolver when you instantiate the client by passing it with the hash key `inline_content_item_resolver`:
441
442
 
442
443
  ```ruby
443
- item_resolver = KenticoCloud::Delivery::Resolvers::InlineContentItemResolver.new(lambda do |item|
444
+ item_resolver = Kentico::Kontent::Delivery::Resolvers::InlineContentItemResolver.new(lambda do |item|
444
445
  return "<h1>#{item.elements.zip_code.value}</h1>" if item.system.type.eql? 'cafe'
445
446
  return "<div>$#{item.elements.price.value}</div>" if item.system.type.eql? 'brewer'
446
447
  end)
447
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>',
448
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>',
448
449
  inline_content_item_resolver: item_resolver
449
450
  ```
450
451
 
451
- The object passed to the resolving method is a complete ContentItem. Similar to content link resolvers, you can create your own class which extends `KenticoCloud::Delivery::Resolvers::InlineContentItemResolver` and implements the `resolve_item` method:
452
+ The object passed to the resolving method is a complete ContentItem. Similar to content link resolvers, you can create your own class which extends `Kentico::Kontent::Delivery::Resolvers::InlineContentItemResolver` and implements the `resolve_item` method:
452
453
 
453
454
  ```ruby
454
- class MyItemResolver < KenticoCloud::Delivery::Resolvers::InlineContentItemResolver
455
+ class MyItemResolver < Kentico::Kontent::Delivery::Resolvers::InlineContentItemResolver
455
456
  def resolve_item(item)
456
457
  return "<h1>#{item.elements.zip_code.value}</h1>" if item.system.type.eql? 'cafe'
457
458
  return "<div>$#{item.elements.price.value}</div>" if item.system.type.eql? 'brewer'
@@ -462,7 +463,7 @@ end
462
463
  You can also set the inline content resolver per-query:
463
464
 
464
465
  ```ruby
465
- delivery_client = KenticoCloud::Delivery::DeliveryClient.new project_id: '<your-project-id>'
466
+ delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '<your-project-id>'
466
467
  # Client doesn't use InlineContentItemResolver, but query below will
467
468
  delivery_client.items
468
469
  .with_inline_content_item_resolver MyItemResolver.new
@@ -470,11 +471,11 @@ delivery_client.items
470
471
 
471
472
  ## Image transformation
472
473
 
473
- 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 `KenticoCloud::Delivery::Builders::ImageTransformationBuilder`, then call the transformation methods. When you're done, call the `.url` method to get the new URL:
474
+ 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 `Kentico::Kontent::Delivery::Builders::ImageTransformationBuilder`, then call the transformation methods. When you're done, call the `.url` method to get the new URL:
474
475
 
475
476
  ```ruby
476
477
  url = response.item.get_assets('teaser_image').first.url
477
- url = KenticoCloud::Delivery::Builders::ImageTransformationBuilder.transform(url)
478
+ url = Kentico::Kontent::Delivery::Builders::ImageTransformationBuilder.transform(url)
478
479
  # methods...
479
480
  .url
480
481
  ```
@@ -486,18 +487,18 @@ The available methods are:
486
487
  |`.with_width`| positive integer, or float between 0 and 1| ?w=200
487
488
  |`.with_height`| positive integer, or float between 0 and 1| ?h=200
488
489
  |`.with_pixel_ratio`| float greater than 0 but less than 5| ?dpr=1.5
489
- |`.with_fit_mode`| constants available at `KenticoCloud::Delivery::Builders::ImageTransformationBuilder` <ul><li>FITMODE_CROP</li><li>FITMODE_CLIP</li><li>FITMODE_SCALE</li></ul>| ?fit=crop
490
+ |`.with_fit_mode`| constants available at `Kentico::Kontent::Delivery::Builders::ImageTransformationBuilder` <ul><li>FITMODE_CROP</li><li>FITMODE_CLIP</li><li>FITMODE_SCALE</li></ul>| ?fit=crop
490
491
  |`.with_rect`| 4 integer values representing pixels or floats representing percentages|rect=100,100,0.7,0.7
491
492
  |`.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
492
493
  |`.with_background_color`| string containing 3, 4, 6, or 8 characters | ?bg=7A0099EE
493
- |`.with_output_format`| constants available at `KenticoCloud::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
494
+ |`.with_output_format`| constants available at `Kentico::Kontent::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
494
495
  |`.with_quality`| integer between 1 to 100 | ?quality=50
495
496
  |`.with_lossless`| 'true', 'false', 0, or 1| ?lossless=1
496
497
  |`.with_auto_format_selection`| 'true', 'false', 0, or 1 | ?auto=format
497
498
 
498
499
  ## Feedback & Contributing
499
500
 
500
- 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.
501
+ Check out the [contributing](https://github.com/Kentico/kontent-delivery-sdk-ruby/blob/master/CONTRIBUTING.md) page to see the best places to file issues, start discussions, and begin contributing.
501
502
 
502
503
  ## License
503
504
 
@@ -505,6 +506,6 @@ The gem is available as open source under the terms of the [MIT License](https:/
505
506
 
506
507
  ## Code of Conduct
507
508
 
508
- Everyone interacting in the Delivery project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Kentico/delivery-sdk-net/blob/master/CODE_OF_CONDUCT.md).
509
+ Everyone interacting in the Delivery project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Kentico/kontent-delivery-sdk-net/blob/master/CODE_OF_CONDUCT.md).
509
510
 
510
- ![Analytics](https://kentico-ga-beacon.azurewebsites.net/api/UA-69014260-4/Kentico/delivery-sdk-ruby?pixel)
511
+ ![Analytics](https://kentico-ga-beacon.azurewebsites.net/api/UA-69014260-4/Kentico/kontent-delivery-sdk-ruby?pixel)
@@ -1,267 +1,269 @@
1
1
  require 'delivery/query_parameters/query_string'
2
2
 
3
- module KenticoCloud
4
- module Delivery
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.
11
- class ImageTransformationBuilder
12
- FIT_MODE_CLIP = 'clip'.freeze
13
- FIT_MODE_SCALE = 'scale'.freeze
14
- FIT_MODE_CROP = 'crop'.freeze
15
- FORMAT_GIF = 'gif'.freeze
16
- FORMAT_PNG = 'png'.freeze
17
- FORMAT_PNG8 = 'png8'.freeze
18
- FORMAT_JPG = 'jpg'.freeze
19
- FORMAT_PJPG = 'pjpg'.freeze
20
- FORMAT_WEBP = 'webp'.freeze
3
+ module Kentico
4
+ module Kontent
5
+ module Delivery
6
+ module Builders
7
+ # Provides methods for manipulating the URL of an asset to adjust the image's
8
+ # size, cropping behavior, background color, output format, and quality.
9
+ #
10
+ # See https://developer.kenticocloud.com/v1/reference#image-transformation and
11
+ # https://github.com/Kentico/kontent-delivery-sdk-ruby#image-transformation.
12
+ class ImageTransformationBuilder
13
+ FIT_MODE_CLIP = 'clip'.freeze
14
+ FIT_MODE_SCALE = 'scale'.freeze
15
+ FIT_MODE_CROP = 'crop'.freeze
16
+ FORMAT_GIF = 'gif'.freeze
17
+ FORMAT_PNG = 'png'.freeze
18
+ FORMAT_PNG8 = 'png8'.freeze
19
+ FORMAT_JPG = 'jpg'.freeze
20
+ FORMAT_PJPG = 'pjpg'.freeze
21
+ FORMAT_WEBP = 'webp'.freeze
21
22
 
22
- class << self
23
- def transform(url)
24
- AssetURL.new url
23
+ class << self
24
+ def transform(url)
25
+ AssetURL.new url
26
+ end
25
27
  end
26
28
  end
27
- end
28
29
 
29
- class AssetURL
30
- INVALID_PARAMS = 'One or more of the parameters is invalid. '\
31
- 'See https://developer.kenticocloud.com/v1/reference#focal-point-crop'\
32
- 'for more information.'.freeze
33
- ONE_TO_100 = 'Quality parameter must be between 1 and 100.'.freeze
34
- BOOLEAN_PARAM = 'The parameter must be a boolean, 0, or 1.'.freeze
30
+ class AssetURL
31
+ INVALID_PARAMS = 'One or more of the parameters is invalid. '\
32
+ 'See https://developer.kenticocloud.com/v1/reference#focal-point-crop'\
33
+ 'for more information.'.freeze
34
+ ONE_TO_100 = 'Quality parameter must be between 1 and 100.'.freeze
35
+ BOOLEAN_PARAM = 'The parameter must be a boolean, 0, or 1.'.freeze
35
36
 
36
- # Constructor. Generally, you obtain an +AssetURL+ object by calling
37
- # KenticoCloud::Delivery::Builders::ImageTransformationBuilder.transform
38
- # instead of using this constructor.
39
- def initialize(url)
40
- @url = url
41
- @query_string = KenticoCloud::Delivery::QueryParameters::QueryString.new
42
- end
37
+ # Constructor. Generally, you obtain an +AssetURL+ object by calling
38
+ # Kentico::Kontent::Delivery::Builders::ImageTransformationBuilder.transform
39
+ # instead of using this constructor.
40
+ def initialize(url)
41
+ @url = url
42
+ @query_string = Kentico::Kontent::Delivery::QueryParameters::QueryString.new
43
+ end
43
44
 
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
48
- def url
49
- @url + @query_string.to_s
50
- end
45
+ # Applies all transformation options to the asset URL.
46
+ #
47
+ # * *Returns*:
48
+ # - +string+ The full URL to the asset with all query string parameters set
49
+ def url
50
+ @url + @query_string.to_s
51
+ end
51
52
 
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+
61
- def with_width(width)
62
- @query_string.set_param 'w', width
63
- self
64
- end
53
+ # Sets the width of the image
54
+ #
55
+ # * *Args*:
56
+ # - *width*
57
+ # - +integer+ Width in pixels, between 1 and 8192.
58
+ # - +float+ Width in percentage, between 0 and 1.
59
+ #
60
+ # * *Returns*:
61
+ # - +self+
62
+ def with_width(width)
63
+ @query_string.set_param 'w', width
64
+ self
65
+ end
65
66
 
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+
75
- def with_height(height)
76
- @query_string.set_param 'h', height
77
- self
78
- end
67
+ # Sets the height of the image
68
+ #
69
+ # * *Args*:
70
+ # - *height*
71
+ # - +integer+ Height in pixels, between 1 and 8192.
72
+ # - +float+ Height in percentage, between 0 and 1.
73
+ #
74
+ # * *Returns* :
75
+ # - +self+
76
+ def with_height(height)
77
+ @query_string.set_param 'h', height
78
+ self
79
+ end
79
80
 
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+
88
- def with_pixel_ratio(dpr)
89
- @query_string.set_param 'dpr', dpr
90
- self
91
- end
81
+ # Sets the device pixel ratio. Either width or height
82
+ # (or both) must be set.
83
+ #
84
+ # * *Args*:
85
+ # - *dpr* (+float+) Pixel ratio between 0 and 5.
86
+ #
87
+ # * *Returns*:
88
+ # - +self+
89
+ def with_pixel_ratio(dpr)
90
+ @query_string.set_param 'dpr', dpr
91
+ self
92
+ end
92
93
 
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+
101
- def with_fit_mode(fit)
102
- @query_string.set_param 'fit', fit
103
- self
104
- end
94
+ # Defines how the image is constrained while resizing. Either width
95
+ # or height (or both) must be set.
96
+ #
97
+ # * *Args*:
98
+ # - *fit* (+string+) Use constants from Kentico::Kontent::Delivery::Builders::ImageTransformationBuilder
99
+ #
100
+ # * *Returns*:
101
+ # - +self+
102
+ def with_fit_mode(fit)
103
+ @query_string.set_param 'fit', fit
104
+ self
105
+ end
105
106
 
106
- # Selects a region of the image to perform transformations on.
107
- # Setting this will remove focal point cropping from the image,
108
- # as the two options are incompatible.
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+
126
- def with_rect(x, y, width, height)
127
- @query_string.remove_param 'fp-x'
128
- @query_string.remove_param 'fp-y'
129
- @query_string.remove_param 'fp-z'
130
- @query_string.remove_param 'crop'
131
- @query_string.set_param 'rect', "#{x},#{y},#{width},#{height}"
132
- self
133
- end
107
+ # Selects a region of the image to perform transformations on.
108
+ # Setting this will remove focal point cropping from the image,
109
+ # as the two options are incompatible.
110
+ #
111
+ # * *Args*:
112
+ # - *x*
113
+ # - +integer+ The left border of the rect in pixels
114
+ # - +float+ The left border of the rect as a percentage between 0 and 1
115
+ # - *y*
116
+ # - +integer+ The top border of the rect in pixels
117
+ # - +float+ The top border of the rect as a percentage between 0 and 1
118
+ # - *width*
119
+ # - +integer+ The width of the rect in pixels
120
+ # - +float+ The width of the rect as a percentage between 0 and 1
121
+ # - *height*
122
+ # - +integer+ The height of the rect in pixels
123
+ # - +float+ The height of the rect as a percentage between 0 and 1
124
+ #
125
+ # * *Returns*:
126
+ # - +self+
127
+ def with_rect(x, y, width, height)
128
+ @query_string.remove_param 'fp-x'
129
+ @query_string.remove_param 'fp-y'
130
+ @query_string.remove_param 'fp-z'
131
+ @query_string.remove_param 'crop'
132
+ @query_string.set_param 'rect', "#{x},#{y},#{width},#{height}"
133
+ self
134
+ end
134
135
 
135
- # Sets the point of interest when cropping the image.
136
- # Setting this will remove the source rectangle region,
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+
147
- def with_focal_point(x, y, z)
148
- raise ArgumentError, INVALID_PARAMS unless valid_dims?(x, y, z)
136
+ # Sets the point of interest when cropping the image.
137
+ # Setting this will remove the source rectangle region,
138
+ # as the two options are incompatible. It also automatically sets the
139
+ # crop to "focalpoint" and fit to "crop"
140
+ #
141
+ # * *Args*:
142
+ # - *x* (+float+) Percentage of the image's width between 0 and 1
143
+ # - *y* (+float+) Percentage of the image's height between 0 and 1
144
+ # - *z* (+integer+) Amount of zoom to apply. A value of 1 is the default zoom, and each step represents 100% additional zoom.
145
+ #
146
+ # * *Returns*:
147
+ # - +self+
148
+ def with_focal_point(x, y, z)
149
+ raise ArgumentError, INVALID_PARAMS unless valid_dims?(x, y, z)
149
150
 
150
- @query_string.remove_param 'rect'
151
- @query_string.set_param 'fp-x', x
152
- @query_string.set_param 'fp-y', y
153
- @query_string.set_param 'fp-z', z
154
- @query_string.set_param 'fit', ImageTransformationBuilder::FIT_MODE_CROP
155
- @query_string.set_param 'crop', 'focalpoint'
156
- self
157
- end
151
+ @query_string.remove_param 'rect'
152
+ @query_string.set_param 'fp-x', x
153
+ @query_string.set_param 'fp-y', y
154
+ @query_string.set_param 'fp-z', z
155
+ @query_string.set_param 'fit', ImageTransformationBuilder::FIT_MODE_CROP
156
+ @query_string.set_param 'crop', 'focalpoint'
157
+ self
158
+ end
158
159
 
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+
166
- def with_background_color(color)
167
- @query_string.set_param 'bg', color
168
- self
169
- end
160
+ # Sets the background color of any transparent areas of the image.
161
+ #
162
+ # * *Args*:
163
+ # - *color* (+string+) A valid 3, 4, 6, or 8 digit hexadecimal color, without the # symbol
164
+ #
165
+ # * *Returns*:
166
+ # - +self+
167
+ def with_background_color(color)
168
+ @query_string.set_param 'bg', color
169
+ self
170
+ end
170
171
 
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+
178
- def with_output_format(format)
179
- @query_string.set_param 'fm', format
180
- self
181
- end
172
+ # Sets the output format of the request for the image.
173
+ #
174
+ # * *Args*:
175
+ # - *format* (+string+) Use constants from Kentico::Kontent::Delivery::Builders::ImageTransformationBuilder
176
+ #
177
+ # * *Returns*:
178
+ # - +self+
179
+ def with_output_format(format)
180
+ @query_string.set_param 'fm', format
181
+ self
182
+ end
182
183
 
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
198
- def with_quality(quality)
199
- raise ArgumentError, ONE_TO_100 unless quality.to_i >= 1 && quality.to_i <= 100
184
+ # Configure the amount of compression for lossy file formats. Lower quality
185
+ # images will have a smaller file size. Only affects *jpg*, *pjpg*, and
186
+ # *webp* files.
187
+ #
188
+ # When no quality is specified for an image transformation, the default
189
+ # value of 85 is used.
190
+ #
191
+ # * *Args*:
192
+ # - *quality* (+integer+) The quality of the image between 1 and 100
193
+ #
194
+ # * *Returns*:
195
+ # - +self+
196
+ #
197
+ # * *Raises*:
198
+ # - +ArgumentError+ if +quality+ is not between 1 and 100 inclusive
199
+ def with_quality(quality)
200
+ raise ArgumentError, ONE_TO_100 unless quality.to_i >= 1 && quality.to_i <= 100
200
201
 
201
- @query_string.set_param 'q', quality
202
- self
203
- end
202
+ @query_string.set_param 'q', quality
203
+ self
204
+ end
204
205
 
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
219
- def with_lossless(lossless)
220
- lossless = lossless.to_s.downcase
221
- raise ArgumentError, BOOLEAN_PARAM unless bool? lossless
206
+ # Sets the lossless parameter. If +true+, automatically sets the format
207
+ # to WebP.
208
+ #
209
+ # * *Args*:
210
+ # - *lossless*
211
+ # - +integer+ Either 1 or 0
212
+ # - +bool+ Either +true+ or +false+
213
+ # - +string+ Either 'true' or 'false'
214
+ #
215
+ # * *Returns*:
216
+ # - +self+
217
+ #
218
+ # * *Raises*:
219
+ # - +ArgumentError+ if +lossless+ cannot be parsed as a boolean
220
+ def with_lossless(lossless)
221
+ lossless = lossless.to_s.downcase
222
+ raise ArgumentError, BOOLEAN_PARAM unless bool? lossless
222
223
 
223
- @query_string.set_param 'lossless', lossless
224
- @query_string.set_param 'fm', KenticoCloud::Delivery::Builders::ImageTransformationBuilder::FORMAT_WEBP if %w[true 1].include? lossless
225
- self
226
- end
224
+ @query_string.set_param 'lossless', lossless
225
+ @query_string.set_param 'fm', Kentico::Kontent::Delivery::Builders::ImageTransformationBuilder::FORMAT_WEBP if %w[true 1].include? lossless
226
+ self
227
+ end
227
228
 
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
243
- def with_auto_format_selection(auto)
244
- auto = auto.to_s.downcase
245
- raise ArgumentError, BOOLEAN_PARAM unless bool? auto
229
+ # Enables or disables automatic format selection. If enabled, it will
230
+ # override the format parameter and deliver WebP instead. If the browser
231
+ # does not support WebP, the value of the format parameter will be used.
232
+ #
233
+ # * *Args*:
234
+ # - *auto*
235
+ # - +integer+ Either 1 or 0
236
+ # - +bool+ Either +true+ or +false+
237
+ # - +string+ Either 'true' or 'false'
238
+ #
239
+ # * *Returns*:
240
+ # - +self+
241
+ #
242
+ # * *Raises*:
243
+ # - +ArgumentError+ if +auto+ cannot be parsed as a boolean
244
+ def with_auto_format_selection(auto)
245
+ auto = auto.to_s.downcase
246
+ raise ArgumentError, BOOLEAN_PARAM unless bool? auto
246
247
 
247
- if %w[true 1].include? auto
248
- @query_string.set_param 'auto', 'format'
249
- else
250
- @query_string.remove_param 'auto'
248
+ if %w[true 1].include? auto
249
+ @query_string.set_param 'auto', 'format'
250
+ else
251
+ @query_string.remove_param 'auto'
252
+ end
253
+ self
251
254
  end
252
- self
253
- end
254
255
 
255
- private
256
+ private
256
257
 
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
258
+ def valid_dims?(x, y, z)
259
+ (x.to_f >= 0.0 && x.to_f <= 1.0) &&
260
+ (y.to_f >= 0.0 && y.to_f <= 1.0) &&
261
+ (z.to_i >= 1)
262
+ end
262
263
 
263
- def bool?(value)
264
- %w[true false 0 1].include? value
264
+ def bool?(value)
265
+ %w[true false 0 1].include? value
266
+ end
265
267
  end
266
268
  end
267
269
  end