# `Waffle.Actions.Url`
[🔗](https://github.com/elixir-waffle/waffle/blob/v2.0.0/lib/waffle/actions/url.ex#L1)

Url generation.

Saving your files is only the first half of any decent storage
solution.  Straightforward access to your uploaded files is equally
as important as storing them in the first place.

Often times you will want to regain access to the stored files.  As
such, Waffle facilitates the generation of urls.

    # Given some user record
    user = %{id: 1}

    Avatar.store({%Plug.Upload{}, user}) #=> {:ok, "selfie.png"}

    # To generate a regular, unsigned url (defaults to the first version):
    Avatar.url({"selfie.png", user})
    #=> "https://bucket.s3.amazonaws.com/uploads/1/original.png"

    # To specify the version of the upload:
    Avatar.url({"selfie.png", user}, :thumb)
    #=> "https://bucket.s3.amazonaws.com/uploads/1/thumb.png"

    # To generate a signed url:
    Avatar.url({"selfie.png", user}, :thumb, signed: true)
    #=> "https://bucket.s3.amazonaws.com/uploads/1/thumb.png?AWSAccessKeyId=AKAAIPDF14AAX7XQ&Signature=5PzIbSgD1V2vPLj%2B4WLRSFQ5M%3D&Expires=1434395458"

    # To generate urls for all versions:
    Avatar.urls({"selfie.png", user})
    #=> %{original: "https://.../original.png", thumb: "https://.../thumb.png"}

**Default url**

In cases where a placeholder image is desired when an uploaded file
is not present, Waffle allows the definition of a default image to
be returned gracefully when requested with a `nil` file.

    def default_url(version) do
      MyApp.Endpoint.url <> "/images/placeholders/profile_image.png"
    end

    Avatar.url(nil) #=> "http://example.com/images/placeholders/profile_image.png"
    Avatar.url({nil, scope}) #=> "http://example.com/images/placeholders/profile_image.png"

**Virtual Host**

To support AWS regions other than US Standard, it may be required to
generate urls in the
[`virtual_host`](http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html)
style.  This will generate urls in the style:
`https://#{bucket}.s3.amazonaws.com` instead of
`https://s3.amazonaws.com/#{bucket}`.

To use this style of url generation, your bucket name must be DNS
compliant.

This can be enabled with:

    config :waffle,
      virtual_host: true

> When using virtual hosted–style buckets with SSL, the SSL wild card certificate only matches buckets that do not contain periods. To work around this, use HTTP or write your own certificate verification logic.

**Asset Host**

You may optionally specify an asset host rather than using the
default `bucket.s3.amazonaws.com` format.

In your application configuration, you'll need to provide an `asset_host` value:

    config :waffle,
      asset_host: "https://d3gav2egqolk5.cloudfront.net", # For a value known during compilation
      asset_host: {:system, "ASSET_HOST"} # For a value not known until runtime

# `url`

---

*Consult [api-reference.md](api-reference.md) for complete listing*