You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rails SDK for [ImageKit](https://imagekit.io/) that implements the new APIs and interface for performing different file operations.
9
-
10
-
ImageKit is a complete image optimization and transformation solution that comes with and
11
-
[image CDN](https://imagekit.io/features/imagekit-infrastructure) and media storage. It can be integrated with your
12
-
existing infrastructure - storage like AWS s3, web servers, your CDN, and custom domain names, allowing you to deliver
13
-
optimize images in minutes with minimal code changes.
11
+
ImageKit gem for Ruby on Rails that allows you to use real-time [image resizing](https://docs.imagekit.io/features/image-transformations), [optimization](https://docs.imagekit.io/features/image-optimization), and [file uploading](https://docs.imagekit.io/api-reference/upload-file-api/).
14
12
15
13
Table of contents -
16
14
*[Installation](#Installation)
@@ -24,19 +22,12 @@ Table of contents -
24
22
*[Links](#Links)
25
23
26
24
27
-
## Installation
28
-
29
-
If you want to create new rails application, then use this command
30
-
31
-
```bash
32
-
# New application with default Sqlite3 database
33
-
rails new <your_application_name>
25
+
# Quick start guide
26
+
Get started with [official quick start guide](https://docs.imagekit.io/getting-started/quickstart-guides/ruby-on-rails) for integrating ImageKit in Ruby on Rails.
34
27
35
-
# New application with specific database
36
-
rails new <your_application_name> -d <database_name>
37
-
```
28
+
## Installation
38
29
39
-
Add this dependency to your application's Gemfile:
30
+
Add `imagekitio` dependency to your application's Gemfile:
40
31
41
32
```ruby
42
33
gem 'imagekitio'
@@ -46,7 +37,8 @@ And then execute:
46
37
```
47
38
$ bundle install
48
39
```
49
-
Or install it yourself as:
40
+
41
+
Or install it yourself:
50
42
```
51
43
$ gem install imagekitio
52
44
```
@@ -64,19 +56,20 @@ config.imagekit={
64
56
```
65
57
66
58
You can create a carrierwave uploader in order to attach pictures to your database objects as their attributes. To upload images without designating them as database attributes, skip to [this section](https://github.com/imagekit-developer/imagekit-ruby#file-upload).
59
+
67
60
```bash
68
61
rails g uploader <Uploading_attribute_name>
69
-
# For example if you want to create uploader for Avatar attribute then use
62
+
# For example, if you want to create an uploader for Avatar attribute, then use
70
63
rails g uploader Avatar
71
64
# Generated uploader's path will be app/uploaders/avatar_uploader.rb
72
65
```
73
66
74
-
After that you need to edit your generated uploader and do the following changes:
67
+
After that, you need to edit your generated uploader and make the following changes:
75
68
```ruby
76
69
# Set store as imagekit_store
77
70
storage :imagekit_store
78
71
79
-
# If you want to add uploading options then create this method inside uploader file as an example
72
+
# If you want to add uploading options, then create this method inside the uploader file as an example
80
73
81
74
defoptions
82
75
options={
@@ -87,14 +80,14 @@ def options
87
80
}
88
81
end
89
82
90
-
# If you want to set upload dir then you can use following method or you can also use options method.
91
-
# This method shuld return string
83
+
# If you want to set upload dir, then you can use the following method, or you can also use the options method.
84
+
# This method should return a string
92
85
defstore_dir
93
86
"your_directory/"
94
87
end
95
88
```
96
89
97
-
Then you need to modify your model. for example- if your model name is employee then do these changes
90
+
Then you need to modify your model. for example- if your model name is employee, then do these changes.
98
91
99
92
```ruby
100
93
classEmployee < ApplicationRecord
@@ -107,7 +100,7 @@ Get image url:
107
100
```ruby
108
101
# If @employee is an object of your model that has data.
109
102
110
-
# To get original image url use
103
+
# To get the original image url, use
111
104
@employee.avatar.url
112
105
113
106
# And to get transformed url use
@@ -117,8 +110,9 @@ Get image url:
117
110
118
111
## Usage
119
112
120
-
You can use this Ruby SDK for 3 different kinds of methods - URL generation, file upload, and file management.
121
-
The usage of the SDK has been explained below
113
+
You can use this Ruby SDK for three different kinds of methods - URL generation, file upload, and file management.
This method allows you to add transformation parameters to and existing, complete URL that is already mapped to ImageKit
149
-
using ```src``` parameter. This method should be used if you have the complete image URL mapped to ImageKit stored in your
142
+
This method allows you to add transformation parameters to an existing, complete URL that is already mapped to ImageKit
143
+
using `src` parameter. This method should be used if you have the complete image URL mapped to ImageKit stored in your
150
144
database.
151
145
152
146
@@ -172,9 +166,9 @@ The `.url()` method accepts the following parameters
172
166
| path | Conditional. This is the path at which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. |
173
167
| src | Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. |
174
168
| transformation | Optional. An array of objects specifying the transformation to be applied in the URL. The transformation name and the value should be specified as a key-value pair in the object. Different steps of a [chained transformation](https://docs.imagekit.io/features/image-transformations/chained-transformations) can be specified as different objects of the array. The complete list of supported transformations in the SDK and some examples of using them are given later. If you use a transformation name that is not specified in the SDK, it gets applied as it is in the URL. |
175
-
| transformation_position | Optional. The default value is `path` that places the transformation string as a path parameter in the URL. It can also be specified as `query` which adds the transformation string as the query parameter `tr` in the URL. If you use `src` parameter to create the URL, then the transformation string is always added as a query parameter. |
169
+
| transformation_position | Optional. The default value is `path` that places the transformation string as a path parameter in the URL. It can also be specified as `query`, which adds the transformation string as the query parameter `tr` in the URL. If you use `src` parameter to create the URL, then the transformation string is always added as a query parameter. |
176
170
| query_parameters | Optional. These are the other query parameters that you want to add to the final URL. These can be any query parameters and not necessarily related to ImageKit. Especially useful if you want to add some versioning parameter to your URLs. |
177
-
| signed | Optional. Boolean. Default is `false`. If set to `true`, the SDK generates a signed image URL adding the image signature to the image URL. This can only be used if you are creating the URL with the `url_endpoint` and `path` parameters, and not with the `src` parameter. |
171
+
| signed | Optional. Boolean. Default is `false`. If set to `true`, the SDK generates a signed image URL adding the image signature to the image URL. This can only be used if you are creating the URL with the `url_endpoint` and `path` parameters and not with the `src` parameter. |
178
172
| expire_seconds | Optional. Integer. Meant to be used along with the `signed` parameter to specify the time in seconds from now when the URL should expire. If specified, the URL contains the expiry timestamp in the URL, and the image signature is modified accordingly. |
The complete list of transformations supported and their usage in ImageKit can be found [here](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations).
251
-
The SDK gives a name to each transformation parameter, making the code simpler, making the code simpler and readable.
245
+
The SDK gives a name to each transformation parameter, making the code simpler, making the code simpler, and readable.
252
246
If a transformation is supported in ImageKit, but a name for it cannot be found in the table below, then use the
253
-
transformation code from ImageKit docs as the name when using in the `url` function.
247
+
transformation code from ImageKit docs as the name when using the `url` function.
254
248
255
249
| Supported Transformation Name | Translates to parameter |
@@ -312,7 +306,7 @@ transformation code from ImageKit docs as the name when using in the `url` funct
312
306
| original | orig |
313
307
314
308
## File Upload
315
-
This method can be used to directly upload images to your ImageKit Media Library, without giving it the designation of an attribute of any database object.
309
+
This method can be used to directly upload images to your ImageKit Media Library without giving it the designation of an attribute of any database object.
316
310
317
311
The SDK provides a simple interface using the `.upload()` method to upload files to the ImageKit Media library. It
318
312
accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload).
@@ -339,7 +333,7 @@ be `None`.
339
333
## File Management
340
334
341
335
The SDK provides a simple interface for all the [media APIs mentioned here](https://docs.imagekit.io/api-reference/media-api)
342
-
to manage your files. This also returns `error` and `result`, error will be `None` if API succeeds.
336
+
to manage your files. This also returns `error` and `result`. The `error` will be `None` if API succeeds.
Delete a file as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/delete-files-bulk). The method accepts a list of file IDs of files that has to be
387
+
Delete a file as per the [API documentation here](https://docs.imagekit.io/api-reference/media-api/delete-files-bulk). The method accepts a list of file IDs of files that has to be
394
388
deleted.
395
389
396
390
```ruby
@@ -419,9 +413,7 @@ We have included the following commonly used utility functions in this package.
419
413
420
414
**Authentication parameter generation**
421
415
422
-
In case you are looking to implement client-side file upload, you are going to need a token, expiry timestamp
423
-
, and a valid signature for that upload. The SDK provides a simple method that you can use in your code to generate these
424
-
authentication parameters for you.
416
+
In case you are looking to implement client-side file upload, you are going to need a `token`, `expiry` timestamp, and a valid `signature` for that upload. The SDK provides a simple method that you can use in your code to generate these authentication parameters for you.
425
417
426
418
_Note: The Private API Key should never be exposed in any client-side code. You must always generate these authentication parameters on the server-side_
427
419
@@ -437,26 +429,24 @@ Returns
437
429
}
438
430
```
439
431
440
-
Both the `token` and `expire` parameters are optional. If not specified, the SDK uses the uuid to generate a random
441
-
token and also generates a valid expiry timestamp internally. The value of the token and expire used to generate the
442
-
signature are always returned in the response, no matter if they are provided as an input to this method or not.
432
+
Both the `token` and `expire` parameters are optional. If not specified, the SDK uses the uuid to generate a random token and also generates a valid expiry timestamp internally. The value of the `token` and `expire` used to generate the signature is always returned in the response, no matter if they are provided as an input to this method or not.
443
433
444
434
**Distance calculation between two pHash values**
445
435
446
436
Perceptual hashing allows you to construct a hash value that uniquely identifies an input image based on the contents
447
437
of an image. [imagekit.io metadata API](https://docs.imagekit.io/api-reference/metadata-api) returns the pHash
448
-
value of an image in the response. You can use this value to find a duplicate, near the duplicate(similar) image by calculating
438
+
value of an image in the response. You can use this value to find a duplicate near the duplicate(similar) image by calculating
449
439
the distance between the two images.
450
440
451
441
452
-
This SDK exposes phash_distance function to calculate the distance between two pHash value. It accepts two pHash hexadecimal
442
+
This SDK exposes the `phash_distance` function to calculate the distance between two pHash value. It accepts two pHash hexadecimal
453
443
strings and returns a numeric value indicative of the level of difference between the two images.
454
444
455
445
```ruby
456
446
defcalculate_distance():
457
447
# fetch metadata of two uploaded image files
458
448
...
459
-
# extract pHash strings from both: say 'first_hash' and 'second_hash'
449
+
# extract pHash strings from both: say 'first_hash' and 'second_hash.'
460
450
...
461
451
# calculate the distance between them:
462
452
@@ -482,8 +472,8 @@ There are two sample apps:
482
472
*[Rails application using Carrierwave](#Instructions-for-rails-application)
This is under [samples/rails_app](https://github.com/imagekit-developer/imagekit-ruby/blob/master/samples/rails_app) directory. Follow the instructions below to set up rails application.
475
+
### Instructions for a rails application
476
+
This is under [samples/rails_app](https://github.com/imagekit-developer/imagekit-ruby/blob/master/samples/rails_app) directory. Follow the instructions below to set up a rails application.
487
477
488
478
**1. Clone git repository**
489
479
```bash
@@ -505,7 +495,7 @@ config.imagekit={
505
495
```ruby
506
496
bundle install
507
497
```
508
-
This sample project are using Sqlite3 database. If you are getting `sqlite3` gem installation error then install sqlite3 first then again run `bundle install`.
498
+
This sample project is using the Sqlite3 database. If you are getting `sqlite3` gem installation error,then install sqlite3 first,then again run `bundle install`.
509
499
510
500
**5. Migrate the database**
511
501
```ruby
@@ -533,5 +523,4 @@ For any feedback or to report any issues or general implementation support, plea
0 commit comments