Module: Shrine::Plugins::KitheDerivativeDefinitions::AttacherClassMethods

Defined in:
lib/shrine/plugins/kithe_derivative_definitions.rb

Instance Method Summary collapse

Instance Method Details

#define_derivative(key, content_type: nil, default_create: true, &block) ⇒ Object

Establish a derivative definition that will be used to create a derivative when #create_derivatives is called, for instance automatically after promotion.

The most basic definition consists of a derivative key, and a ruby block that takes the original file, transforms it, and returns a ruby File or other (shrine-compatible) IO-like object. It will usually be done inside your custom AssetUploader class definition.

class AssetUploader < Kithe::AssetUploader
  Attacher.define_derivative :thumbnail do |original_file|
    someTempFileOrOtherIo
  end
end

The original_file passed in will be a ruby File object that is already open for reading. If you need a local file path for your transformation, just use ‘original_file.path`.

The return value can be any IO-like object. If it is a ruby File or Tempfile, that temporary file will be deleted for you after the derivative has been created. If you have to make any intermediate files, you are responsible for cleaning them up. Ruby stdlib Tempfile and Dir.mktmpdir may be useful.

If in order to do your transformation you need additional information about the original, just add a ‘attacher:` keyword argument to your block, and a `Shrine::Attacher` subclass will be passed in. You can then get the model object from `attacher.record`, or the original file as a `Shrine::UploadedFile` object with `attacher.file`.

Attacher.define_derivative :thumbnail do |original_file, attacher:|
   attacher.record.title, attacher.file.width, attacher.file.content_type # etc
end

Derivatives are normally uploaded to the Shrine storage labeled :kithe_derivatives, but a definition can specify an alternate Shrine storage id. (specified shrine storage key is applied on derivative creation; if you change it with existing derivatives, they should remain, and be accessible, where they were created; there is no built-in solution at present for moving them).

Attacher.define_derivative :thumbnail, storage_key: :my_thumb_storage do |original| # ...

You can also set ‘default_create: false` if you want a particular definition not to be included in a no-arg `asset.create_derivatives` that is normally triggered on asset creation.

And you can set content_type to either a specific type like ‘image/jpeg` (or array of such) or a general type like `image`, if you want to define a derivative generation routine for only certain types. If multiple blocks for the same key are defined, with different content_type restrictions, the most specific one will be used. That is, for a JPG, `image/jpeg` beats `image` beats no restriction.



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/shrine/plugins/kithe_derivative_definitions.rb', line 91

def define_derivative(key, content_type: nil, default_create: true, &block)
  # Make sure we dup the array to handle sub-classes on class_attribute
  self.kithe_derivative_definitions = self.kithe_derivative_definitions.dup.push(
    Kithe::Asset::DerivativeDefinition.new(
      key: key,
      content_type: content_type,
      default_create: default_create,
      proc: block
    )
  ).freeze
end

#defined_derivative_keys ⇒ Object

Returns all derivative keys registered with a definition, as array of strings



104
105
106
 
# File 'lib/shrine/plugins/kithe_derivative_definitions.rb', line 104

def defined_derivative_keys
  self.kithe_derivative_definitions.collect(&:key).uniq.collect(&:to_s)
end

#remove_derivative_definition!(*keys) ⇒ Object

If you have a subclass that has inherited derivative definitions, you can remove them – only by key, will remove any definitions with that key regardless of content_type restrictions.

This could be considered rather bad OO design, you might want to consider a different class hieararchy where you don’t have to do this. But it’s here.



114
115
116
117
118
119
 
# File 'lib/shrine/plugins/kithe_derivative_definitions.rb', line 114

def remove_derivative_definition!(*keys)
  keys = keys.collect(&:to_sym)
  self.kithe_derivative_definitions = self.kithe_derivative_definitions.reject do |defn|
    keys.include?(defn.key.to_sym)
  end.freeze
end