waffle v1.1.5

Waffle (waffle v1.1.5)

Waffle is a flexible file upload library for Elixir with straightforward integrations for Amazon S3 and ImageMagick.

Installation

Add the latest stable release to your mix.exs file, along with the required dependencies for ExAws if appropriate:

defp deps do
  [
    {:waffle, "~> 1.1"},

    # If using S3:
    {:ex_aws, "~> 2.1.2"},
    {:ex_aws_s3, "~> 2.0"},
    {:hackney, "~> 1.9"},
    {:sweet_xml, "~> 0.6"}
  ]
end

Then run mix deps.get in your shell to fetch the dependencies.

Usage

After installing Waffle, another two things should be done:

  1. setup a storage provider
  2. define a definition module

Setup a storage provider

Waffle has two built-in storage providers:

Other available storage providers are supported by the community.

An example for setting up Waffle.Storage.Local:

config :waffle,
  storage: Waffle.Storage.Local,
  asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}

An example for setting up Waffle.Storage.S3:

config :waffle,
  storage: Waffle.Storage.S3,
  bucket: "custom_bucket",                # or {:system, "AWS_S3_BUCKET"}
  asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}

config :ex_aws,
  json_codec: Jason
  # any configurations provided by https://github.com/ex-aws/ex_aws

Define a definition module

Waffle requires a definition module which contains the relevant functions to store and retrieve files:

  • Optional transformations of the uploaded file
  • Where to put your files (the storage directory)
  • How to name your files
  • How to secure your files (private? Or publicly accessible?)
  • Default placeholders

This module can be created manually or generated by mix waffle.g automatically.

As an example, we will generate a definition module for handling avatars:

mix waffle.g avatar

This should generate a file at lib/[APP_NAME]_web/uploaders/avatar.ex. Check this file for descriptions of configurable options.

Examples

Usage with Ecto

Waffle comes with a companion package for use with Ecto. If you intend to use Waffle with Ecto, it is highly recommended you also add the waffle_ecto dependency. Benefits include:

  • Changeset integration
  • Versioned urls for cache busting (.../thumb.png?v=63601457477)

Other Storage Providers

Further reading