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 a custom Asset class definition.

class Asset < Kithe::Asset
  define_derivative :thumbnail do |original_file|
  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 ‘record:` keyword argument to your block, and the Asset object will be passed in:

define_derivative :thumbnail do |original_file, record:|
   record.width, record.height, record.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).

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.



68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/shrine/plugins/kithe_derivative_definitions.rb', line 68

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



81
82
83
 
# File 'lib/shrine/plugins/kithe_derivative_definitions.rb', line 81

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.



91
92
93
94
95
96
 
# File 'lib/shrine/plugins/kithe_derivative_definitions.rb', line 91

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