URLs

Standard URLs

The format of the standard urls can be configured using url_format:

Dragonfly.app.configure do
  url_format "/:job/:name"  # this is the default
end

What parameters can go in the url format string?

Anything.

:job is always present, and if not specified in the url_format, is appended as a query parameter.

Parameters are taken from the Job object’s url_attributes object (which is like an OpenStruct).

With url_format "/:a/:b-:c.:d":

job = Dragonfly.app.fetch('my_uid')
job.url_attributes.a = 'one'
job.url_attributes.b = 'two'
job.url_attributes.c = 'three'
job.url_attributes.d = 'four'
job.url    # "/one/two-three.four?job=W1s...."

If the parameter is not present, the segment simply doesn’t appear (also the preceding delimiter character, e.g. “/”, “-“ or “.”, is removed)

job.url_attributes.b = nil
job.url    # "/one-three.four?job=W1s...."

job.url_attributes.d = nil
job.url    # "/one-three?job=W1s...."

Passing in attributes

url_attributes can be overridden by passing in attributes in the call to url.

With url_format "/:a":

job = Dragonfly.app.fetch('my_uid')
job.url_attributes['a'] = 'one'
job.url(a: 'uno')    # "/uno?job=W1s...."

How does this relate to models?

When using models you don’t deal with url_attributes directly. Instead, this is populated from the model’s magic attributes (see Models for more details).

Let’s imagine we have a model

class Person < ActiveRecord::Base
  dragonfly_accessor :photo
end

person = Person.create!(photo: Pathname.new('face.jpg'))

and a url_format "/stuff/:job/:width/:name"

Then with only a photo_uid column:

person.photo.url   # "/stuff/W1siZiIsImEiXV0"

With columns photo_uid, photo_name

person.photo.url   # "/stuff/W1siZiIsImEiXV0/face.jpg"

With columns photo_uid, photo_name, photo_width

person.photo.url   # "/stuff/W1siZiIsImEiXV0/280/face.jpg"

Parameters can be overridden in in the same way as before

person.photo.url(width: 10, name: 'bean.jpg')   # "/stuff/W1siZiIsImEiXV0/10/bean.jpg"

Special parameters

:job

This encodes all the information about the job and will always be present. If not specified in the url_format string it will be added as a query parameter.

:name, :basename and :ext

:basename and :ext are taken from :name, so you can split them in the url.

For example, with url_format "/:basename-:width.:ext"

image = Dragonfly.app.fetch('my_uid')
image.url(width: 22, name: 'frog.png')   # "/frog-22.png?job=W1s..."

Processors changing URL parameters

Processors can optionally update url_attributes. For example, the imagemagick encode processor updates the file extension (if using :ext or :name)

For example, with url_format "/:name" and Person model with columns image_uid and image_name

person.photo.url                  # "/face.jpg?job=W1s..."
person.photo.encode('pdf').url    # "/face.pdf?job=W7h..."

See Processors for more details.

Host

By default all URLs are relative. You can set a host for the urls in configure

Dragonfly.app.configure{ url_host 'http://some.host' }

image.url    # "http://some.host/W1s..."

…or by passing as an argument…

image.url(host: 'http://localhost:8080')    # "http://localhost:8080/W1s..."

Path Prefix

A url_format like "/media/:job" will generate URLs like /media/W1s... and in turn match any incoming ones that look like /media/....

If, for whatever reason, you need the generated URLs to have a further prefix (such as when the app is mounted under a subdirectory), you can use url_path_prefix

Dragonfly.app.configure{ url_path_prefix "/stuff" }

image.url    # "/stuff/media/W1s..."

…or…

image.url(path_prefix: "/blungeon")    # "/blungeon/media/W1s..."

Remote URLs

If the datastore supports it, you can get the URL for serving directly from the data store using

Dragonfly.app.remote_url_for(uid)
    # e.g. http://my-bucket.s3.amazonaws.com/2011/04/01/03/03/05/243/file.jpg

or from a model attachment

my_model.attachment.remote_url
    # e.g. http://my-bucket.s3.amazonaws.com/2011/04/01/03/03/05/243/file.jpg

The File, S3 and Couch data stores support this, as well as any others that implement the correct interface as per the data stores doc.

Rails custom URLs

See Using with Rails