waffle

v0.0.3

waffle v0.0.3 Waffle

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: "~> 0.0.1",

    # If using Amazon S3:
    ex_aws: "~> 2.0",
    ex_aws_s3: "~> 2.0",
    hackney: "~> 1.6",
    poison: "~> 3.1",
    sweet_xml: "~> 0.6"
  ]
end

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

Configuration

Waffle expects certain properties to be configured at the application level:

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

Along with any configuration necessary for ExAws.

Storage Providers

Waffle ships with integrations for Waffle.Storage.Local and Waffle.Storage.S3. Alternative storage providers may be supported by the community:

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)

Getting Started: Defining your Upload

Waffle requires a definition module which contains the relevant configuration to store and retrieve your files.

This definition module contains relevant functions to determine:

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

To start off, generate an attachment definition:

mix waffle.g avatar

This should give you a basic file in:

web/uploaders/avatar.ex

Check this file for descriptions of configurable options.

Further reading