## Methods

### Public Class

### Public Instance

- add_derivative
- add_derivatives
- change
- create_derivatives
- data
- delete_derivatives
- derivatives
- derivatives=
- destroy
- get
- get_derivatives
- load_data
- map_derivative
- merge_derivatives
- process_derivatives
- promote
- promote_derivatives
- remove_derivative
- remove_derivatives
- set_derivatives
- upload_derivative
- upload_derivatives
- url

## Attributes

derivatives | [R] |

## Public Class methods

Adds the ability to accept derivatives.

# File lib/shrine/plugins/derivatives.rb 108 def initialize(derivatives: {}, **options) 109 super(**options) 110 111 @derivatives = derivatives 112 @derivatives_mutex = Mutex.new if shrine_class.derivatives_options[:mutex] 113 end

## Public Instance methods

Uploads a given file and adds it to the derivatives hash.

attacher.derivatives #=> # { # thumb: #<Shrine::UploadedFile>, # } attacher.add_derivative(:cropped, cropped) attacher.derivatives #=> # { # thumb: #<Shrine::UploadedFile>, # cropped: #<Shrine::UploadedFile>, # }

# File lib/shrine/plugins/derivatives.rb 235 def add_derivative(name, file, **options) 236 add_derivatives({ name => file }, **options) 237 derivatives[name] 238 end

Uploads given hash of files and adds uploaded files to the derivatives hash.

attacher.derivatives #=> # { # thumb: #<Shrine::UploadedFile>, # } attacher.add_derivatives({ cropped: cropped }) attacher.derivatives #=> # { # thumb: #<Shrine::UploadedFile>, # cropped: #<Shrine::UploadedFile>, # }

# File lib/shrine/plugins/derivatives.rb 217 def add_derivatives(files, **options) 218 new_derivatives = upload_derivatives(files, **options) 219 merge_derivatives(new_derivatives) 220 new_derivatives 221 end

Clears derivatives when attachment changes.

attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> } attacher.change(file) attacher.derivatives #=> {}

# File lib/shrine/plugins/derivatives.rb 462 def change(*) 463 result = super 464 set_derivatives({}) 465 result 466 end

Calls processor and adds returned derivatives.

Attacher.derivatives_processor :my_processor do |original| # ... end attacher.create_derivatives(:my_processor)

# File lib/shrine/plugins/derivatives.rb 199 def create_derivatives(*args, storage: nil, **options) 200 files = process_derivatives(*args, **options) 201 add_derivatives(files, storage: storage) 202 end

Adds derivative data into the hash.

attacher.attach(io) attacher.add_derivatives({ thumb: thumb }) attacher.data #=> # { # "id" => "...", # "storage" => "store", # "metadata" => { ... }, # "derivatives" => { # "thumb" => { # "id" => "...", # "storage" => "store", # "metadata" => { ... }, # } # } # }

# File lib/shrine/plugins/derivatives.rb 416 def data 417 result = super 418 419 if derivatives.any? 420 result ||= {} 421 result["derivatives"] = map_derivative(derivatives, transform_keys: :to_s) do |_, derivative| 422 derivative.data 423 end 424 end 425 426 result 427 end

Deletes given hash of uploaded files.

attacher.delete_derivatives({ thumb: uploaded_file }) uploaded_file.exists? #=> false

# File lib/shrine/plugins/derivatives.rb 384 def delete_derivatives(derivatives = self.derivatives) 385 map_derivative(derivatives) { |_, derivative| derivative.delete } 386 end

Sets a hash of derivatives.

attacher.derivatives = { thumb: Shrine.uploaded_file(...) } attacher.derivatives #=> { thumb: #<Shrine::UploadedFile ...> }

# File lib/shrine/plugins/derivatives.rb 472 def derivatives=(derivatives) 473 unless derivatives.is_a?(Hash) 474 fail ArgumentError, "expected derivatives to be a Hash, got #{derivatives.inspect}" 475 end 476 477 @derivatives = derivatives 478 end

In addition to deleting the main file it also deletes any derivatives.

attacher.add_derivatives({ thumb: thumb }) attacher.derivatives[:thumb].exists? #=> true attacher.destroy attacher.derivatives[:thumb].exists? #=> false

# File lib/shrine/plugins/derivatives.rb 187 def destroy 188 super 189 delete_derivatives 190 end

Convenience method for accessing derivatives.

photo.image_derivatives[:thumb] #=> #<Shrine::UploadedFile> # can be shortened to photo.image(:thumb) #=> #<Shrine::UploadedFile>

# File lib/shrine/plugins/derivatives.rb 120 def get(*path) 121 return super if path.empty? 122 123 get_derivatives(*path) 124 end

Convenience method for accessing derivatives.

photo.image_derivatives.dig(:thumbnails, :large) # can be shortened to photo.image_derivatives(:thumbnails, :large)

# File lib/shrine/plugins/derivatives.rb 131 def get_derivatives(*path) 132 return derivatives if path.empty? 133 134 path = derivative_path(path) 135 136 derivatives.dig(*path) 137 end

Loads derivatives from data generated by `Attacher#data`

.

attacher.load_data({ "id" => "...", "storage" => "store", "metadata" => { ... }, "derivatives" => { "thumb" => { "id" => "...", "storage" => "store", "metadata" => { ... }, } } }) attacher.file #=> #<Shrine::UploadedFile> attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> }

# File lib/shrine/plugins/derivatives.rb 445 def load_data(data) 446 data ||= {} 447 data = data.dup 448 449 derivatives_data = data.delete("derivatives") || data.delete(:derivatives) || {} 450 @derivatives = shrine_class.derivatives(derivatives_data) 451 452 data = nil if data.empty? 453 454 super(data) 455 end

Iterates through nested derivatives and maps results.

attacher.map_derivative(derivatives) { |path, file| ... }

# File lib/shrine/plugins/derivatives.rb 483 def map_derivative(derivatives, **options, &block) 484 shrine_class.map_derivative(derivatives, **options, &block) 485 end

Deep merges given uploaded derivatives with current derivatives.

attacher.derivatives #=> { one: #<Shrine::UploadedFile> } attacher.merge_derivatives({ two: uploaded_file }) attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> }

# File lib/shrine/plugins/derivatives.rb 303 def merge_derivatives(new_derivatives) 304 derivatives_synchronize do 305 merged_derivatives = deep_merge_derivatives(derivatives, new_derivatives) 306 set_derivatives(merged_derivatives) 307 end 308 end

Downloads the attached file and calls the specified processor.

Attacher.derivatives_processor :thumbnails do |original| processor = ImageProcessing::MiniMagick.source(original) { small: processor.resize_to_limit!(300, 300), medium: processor.resize_to_limit!(500, 500), large: processor.resize_to_limit!(800, 800), } end attacher.process_derivatives(:thumbnails) #=> { small: #<File:...>, medium: #<File:...>, large: #<File:...> }

# File lib/shrine/plugins/derivatives.rb 278 def process_derivatives(processor_name = :default, source = nil, **options) 279 # handle receiving only source file without a processor 280 unless processor_name.respond_to?(:to_sym) 281 source = processor_name 282 processor_name = :default 283 end 284 285 source ||= file! 286 287 processor_settings = self.class.derivatives_processor_settings(processor_name) || {} 288 289 if processor_settings[:download] 290 shrine_class.with_file(source) do |file| 291 _process_derivatives(processor_name, file, **options) 292 end 293 else 294 _process_derivatives(processor_name, source, **options) 295 end 296 end

In addition to promoting the main file, also promotes any cached derivatives. This is useful when these derivatives are being created as part of a direct upload.

attacher.assign(io) attacher.add_derivative(:thumb, file, storage: :cache) attacher.promote attacher.stored?(attacher.derivatives[:thumb]) #=> true

# File lib/shrine/plugins/derivatives.rb 162 def promote(**options) 163 super 164 promote_derivatives 165 create_derivatives if create_derivatives_on_promote? 166 end

Uploads any cached derivatives to permanent storage.

# File lib/shrine/plugins/derivatives.rb 169 def promote_derivatives(**options) 170 stored_derivatives = map_derivative(derivatives) do |path, derivative| 171 if cached?(derivative) 172 upload_derivative(path, derivative, **options) 173 else 174 derivative 175 end 176 end 177 178 set_derivatives(stored_derivatives) unless derivatives == stored_derivatives 179 end

Removes derivative with specified name from the derivatives hash.

attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> } attacher.remove_derivative(:one) #=> #<Shrine::UploadedFile> (removed derivative) attacher.derivatives #=> { two: #<Shrine::UploadedFile> }

Nested derivatives are also supported:

attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> } } attacher.remove_derivative([:nested, :one]) #=> #<Shrine::UploadedFile> (removed derivative) attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile> } }

The :delete option can be passed for deleting removed derivative:

attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile> } derivative = attacher.remove_derivatives(:two, delete: true) derivative.exists? #=> false

# File lib/shrine/plugins/derivatives.rb 376 def remove_derivative(path, **options) 377 remove_derivatives(path, **options).first 378 end

Removes derivatives with specified name from the derivatives hash.

attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile>, three: #<Shrine::UploadedFile> } attacher.remove_derivatives(:two, :three) #=> [#<Shrine::UploadedFile>, #<Shrine::UploadedFile>] (removed derivatives) attacher.derivatives #=> { one: #<Shrine::UploadedFile> }

Nested derivatives are also supported:

attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile>, three: #<Shrine::UploadedFile> } } attacher.remove_derivatives([:nested, :two], [:nested, :three]) #=> [#<Shrine::UploadedFile>, #<Shrine::UploadedFile>] (removed derivatives) attacher.derivatives #=> { nested: { one: #<Shrine::UploadedFile> } }

The :delete option can be passed for deleting removed derivatives:

attacher.derivatives #=> { one: #<Shrine::UploadedFile>, two: #<Shrine::UploadedFile>, three: #<Shrine::UploadedFile> } two, three = attacher.remove_derivatives(:two, :three, delete: true) two.exists? #=> false three.exists? #=> false

# File lib/shrine/plugins/derivatives.rb 341 def remove_derivatives(*paths, delete: false) 342 removed_derivatives = paths.map do |path| 343 path = Array(path) 344 345 if path.one? 346 derivatives.delete(path.first) 347 else 348 derivatives.dig(*path[0..-2]).delete(path[-1]) 349 end 350 end 351 352 set_derivatives derivatives 353 354 delete_derivatives(removed_derivatives) if delete 355 356 removed_derivatives 357 end

Sets the given hash of uploaded files as derivatives.

attacher.set_derivatives({ thumb: uploaded_file }) attacher.derivatives #=> { thumb: #<Shrine::UploadedFile> }

# File lib/shrine/plugins/derivatives.rb 392 def set_derivatives(derivatives) 393 self.derivatives = derivatives 394 set file # trigger model write 395 derivatives 396 end

Uploads the given file and deletes it afterwards.

hash = attacher.upload_derivative(:thumb, thumb) hash[:thumb] #=> #<Shrine::UploadedFile>

# File lib/shrine/plugins/derivatives.rb 254 def upload_derivative(path, file, storage: nil, **options) 255 path = derivative_path(path) 256 storage ||= derivative_storage(path) 257 258 file.open if file.is_a?(Tempfile) # refresh file descriptor 259 file.binmode if file.respond_to?(:binmode) # ensure binary mode 260 261 upload(file, storage, derivative: path, delete: true, action: :derivatives, **options) 262 end

Uploads given hash of files.

hash = attacher.upload_derivatives({ thumb: thumb }) hash[:thumb] #=> #<Shrine::UploadedFile>

# File lib/shrine/plugins/derivatives.rb 244 def upload_derivatives(files, **options) 245 map_derivative(files) do |path, file| 246 upload_derivative(path, file, **options) 247 end 248 end

Allows generating a URL to the derivative by passing the derivative name.

attacher.add_derivatives({ thumb: thumb }) attacher.url(:thumb) #=> "https://example.org/thumb.jpg"

# File lib/shrine/plugins/derivatives.rb 144 def url(*path, **options) 145 return super if path.empty? 146 147 path = derivative_path(path) 148 149 url = derivatives.dig(*path)&.url(**options) 150 url ||= default_url(**options, derivative: path) 151 url 152 end