Module: CarrierWave::Mount

Included in:

ActiveRecord

Defined in:

lib/carrierwave/mount.rb

Overview

If a Class is extended with this module, it gains the mount_uploader method, which is used for mapping attributes to uploaders and allowing easy assignment.

You can use mount_uploader with pretty much any class, however it is intended to be used with some kind of persistent storage, like an ORM. If you want to persist the uploaded files in a particular Class, it needs to implement a ‘read_uploader` and a `write_uploader` method.

Defined Under Namespace

Modules: Extension Classes: Mounter

Instance Method Summary

• #mount_uploader(column, uploader = nil, options = {}, &block) ⇒ Object

  Mounts the given uploader on the given column.

• #uploader_option(column, option) ⇒ Object

  Return a particular option for a particular uploader.

• #uploader_options ⇒ Object
• #uploaders ⇒ Object

  Returns.

Instance Method Details

#mount_uploader(column, uploader = nil, options = {}, &block) ⇒ Object

Mounts the given uploader on the given column. This means that assigning and reading from the column will upload and retrieve files. Supposing that a User class has an uploader mounted on image, you can assign and retrieve files like this:

@user.image # => <Uploader>
@user.image.store!(some_file_object)

@user.image.url # => '/some_url.png'

It is also possible (but not recommended) to ommit the uploader, which will create an anonymous uploader class.

Passing a block makes it possible to customize the uploader. This can be convenient for brevity, but if there is any significatnt logic in the uploader, you should do the right thing and have it in its own file.

Added instance methods

Supposing a class has used mount_uploader to mount an uploader on a column named image, in that case the following methods will be added to the class:

image

Returns an instance of the uploader only if anything has been uploaded

image=

Caches the given file

image_url

Returns the url to the uploaded file

image_cache

Returns a string that identifies the cache location of the file

image_cache=

Retrieves the file from the cache based on the given cache name

remote_image_url

Returns previously cached remote url

remote_image_url=

Retrieve the file from the remote url

remove_image

An attribute reader that can be used with a checkbox to mark a file for removal

remove_image=

An attribute writer that can be used with a checkbox to mark a file for removal

remove_image?

Whether the file should be removed when store_image! is called.

store_image!

Stores a file that has been assigned with image=

remove_image!

Removes the uploaded file from the filesystem.

image_integrity_error

Returns an error object if the last file to be assigned caused an integrity error

image_processing_error

Returns an error object if the last file to be assigned caused a processing error

write_image_identifier

Uses the write_uploader method to set the identifier.

image_identifier

Reads out the identifier of the file

Parameters

column (Symbol)

the attribute to mount this uploader on

uploader (CarrierWave::Uploader)

the uploader class to mount

options (Hash=> Object)

a set of options

&block (Proc)

customize anonymous uploaders

Options

:mount_on => Symbol

if the name of the column to be serialized to differs you can override it using this option

:ignore_integrity_errors => Boolean

if set to true, integrity errors will result in caching failing silently

:ignore_processing_errors => Boolean

if set to true, processing errors will result in caching failing silently

Examples

Mounting uploaders on different columns.

class Song
  mount_uploader :lyrics, LyricsUploader
  mount_uploader :alternative_lyrics, LyricsUploader
  mount_uploader :file, SongUploader
end

This will add an anonymous uploader with only the default settings:

class Data
  mount_uploader :csv
end

this will add an anonymous uploader overriding the store_dir:

class Product
  mount_uploader :blueprint do
    def store_dir
      'blueprints'
    end
  end
end

# File 'lib/carrierwave/mount.rb', line 140

def mount_uploader(column, uploader=nil, options={}, &block)
  if block_given?
    uploader = Class.new(uploader || CarrierWave::Uploader::Base)
    uploader.class_eval(&block)
    uploader.recursively_apply_block_to_versions(&block)
  else
    uploader ||= Class.new(CarrierWave::Uploader::Base)
  end

  uploaders[column.to_sym] = uploader
  uploader_options[column.to_sym] = options

  include CarrierWave::Mount::Extension

  # Make sure to write over accessors directly defined on the class.
  # Simply super to the included module below.
  class_eval <<-RUBY, __FILE__, __LINE__+1
    def #{column}; super; end
    def #{column}=(new_file); super; end
  RUBY

  # Mixing this in as a Module instead of class_evaling directly, so we
  # can maintain the ability to super to any of these methods from within
  # the class.
  mod = Module.new
  include mod
  mod.class_eval <<-RUBY, __FILE__, __LINE__+1

    def #{column}
      _mounter(:#{column}).uploader
    end

    def #{column}=(new_file)
      _mounter(:#{column}).cache(new_file)
    end

    def #{column}?
      !_mounter(:#{column}).blank?
    end

    def #{column}_url(*args)
      _mounter(:#{column}).url(*args)
    end

    def #{column}_cache
      _mounter(:#{column}).cache_name
    end

    def #{column}_cache=(cache_name)
      _mounter(:#{column}).cache_name = cache_name
    end

    def remote_#{column}_url
      _mounter(:#{column}).remote_url
    end

    def remote_#{column}_url=(url)
      _mounter(:#{column}).remote_url = url
    end

    def remove_#{column}
      _mounter(:#{column}).remove
    end

    def remove_#{column}!
      _mounter(:#{column}).remove!
    end

    def remove_#{column}=(value)
      _mounter(:#{column}).remove = value
    end

    def remove_#{column}?
      _mounter(:#{column}).remove?
    end

    def store_#{column}!
      _mounter(:#{column}).store!
    end

    def #{column}_integrity_error
      _mounter(:#{column}).integrity_error
    end

    def #{column}_processing_error
      _mounter(:#{column}).processing_error
    end

    def write_#{column}_identifier
      _mounter(:#{column}).write_identifier
    end

    def #{column}_identifier
      _mounter(:#{column}).identifier
    end

    def store_previous_model_for_#{column}
      serialization_column = _mounter(:#{column}).serialization_column

      if #{column}.remove_previously_stored_files_after_update && send(:"\#{serialization_column}_changed?")
        @previous_model_for_#{column} ||= self.find_previous_model_for_#{column}
      end
    end

    def find_previous_model_for_#{column}
      self.class.find(to_key.first)
    end

    def remove_previously_stored_#{column}
      if @previous_model_for_#{column} && @previous_model_for_#{column}.#{column}.path != #{column}.path
        @previous_model_for_#{column}.#{column}.remove!
        @previous_model_for_#{column} = nil
      end
    end

  RUBY
end

#uploader_option(column, option) ⇒ Object

Return a particular option for a particular uploader

Parameters

column (Symbol)

The column the uploader is mounted at

option (Symbol)

The option, e.g. validate_integrity

Returns

Object

The option value

# File 'lib/carrierwave/mount.rb', line 46

def uploader_option(column, option)
  if uploader_options[column].has_key?(option)
    uploader_options[column][option]
  else
    uploaders[column].send(option)
  end
end

#uploader_options ⇒ Object

# File 'lib/carrierwave/mount.rb', line 28

def uploader_options
  @uploader_options ||= {}
  @uploader_options = superclass.uploader_options.merge(@uploader_options) if superclass.respond_to?(:uploader_options)
  @uploader_options
end

#uploaders ⇒ Object

Returns

Hash=> CarrierWave

what uploaders are mounted on which columns

# File 'lib/carrierwave/mount.rb', line 22

def uploaders
  @uploaders ||= {}
  @uploaders = superclass.uploaders.merge(@uploaders) if superclass.respond_to?(:uploaders)
  @uploaders
end