README.md in refile-0.2.4 vs README.md in refile-0.2.5
- old
+ new
@@ -1,7 +1,7 @@
# Refile
-
+[](http://badge.fury.io/rb/refile)
[](https://travis-ci.org/elabs/refile)
Refile is a modern file upload library for Ruby applications. It is simple, yet
powerful. Refile is an attempt by CarrierWave's original author to fix the
design mistakes and overengineering in CarrierWave.
@@ -137,10 +137,20 @@
``` ruby
Refile.cache = Refile::Backend::S3.new(max_size: 10.megabytes, ...)
```
+The Refile gem ships with [S3](lib/refile/backends/s3.rb) and
+[FileSystem](lib/refile/backends/file_system.rb) backends. Additional backends
+are provided by other gems.
+
+- [Fog](https://github.com/elabs/refile-fog) provides support for a ton of
+ different cloud storage providers, including Google Storage and Rackspace
+ CloudFiles.
+- [Postgresql](https://github.com/krists/refile-postgres)
+- [In Memory](https://github.com/jnicklas/refile-memory)
+
### Uploadable
The `upload` method on backends can be called with a variety of objects. It
requires that the object passed to it behaves similarly to Ruby IO objects, in
particular it must implement the methods `size`, `read(length = nil, buffer =
@@ -210,11 +220,11 @@
Refile includes a Rack application (an endpoint, not a middleware). This application
streams files from backends and can even accept file uploads and upload them to
backends.
-**Important:** Unlike other file upload solutions, Refile always streams your files thorugh your
+**Important:** Unlike other file upload solutions, Refile always streams your files through your
application. It cannot generate URLs to your files. This means that you should
**always** put a CDN or other HTTP cache in front of your application. Serving
files through your app takes a lot of resources and you want it to happen rarely.
Setting this up is actually quite simple, you can use the same CDN you would use
@@ -224,11 +234,11 @@
``` ruby
Refile.host = "//your-dist-url.cloudfront.net"
```
-Using a [procol-relative URL](http://www.paulirish.com/2010/the-protocol-relative-url/) for `Refile.host` is recommended.
+Using a [protocol-relative URL](http://www.paulirish.com/2010/the-protocol-relative-url/) for `Refile.host` is recommended.
### Mounting
If you are using Rails and have required [refile/rails.rb](lib/refile/rails.rb),
then the Rack application is mounted for you at `/attachments`. You should be able
@@ -310,19 +320,32 @@
The `attachment_url` helper can then be used for generating URLs for the uploaded
files:
``` erb
-<%= image_tag attachment_url(@user, :profile_image) %>
+<%= link_to "Image", attachment_url(@user, :profile_image) %>
```
Any additional arguments to it are included in the URL as processor arguments:
``` erb
-<%= image_tag attachment_url(@user, :profile_image, :fill, 300, 300) %>
+<%= link_to "Image", attachment_url(@user, :profile_image, :fill, 300, 300) %>
```
+There's also a helper for generating image tags:
+
+``` erb
+<%= attachment_image_tag(@user, :profile_image, :fill, 300, 300) %>
+```
+
+With this helper you can specify an image which is used as a fallback in case
+no file has been uploaded:
+
+``` erb
+<%= attachment_image_tag(@user, :profile_image, :fill, 300, 300, fallback: "defaul.png") %>
+```
+
## 5. JavaScript library
Refile's JavaScript library is small but powerful.
Uploading files is slow, so anything we can do to speed up the process is going
@@ -451,9 +474,38 @@
### Browser compatibility
Refile's JavaScript library requires HTML5 features which are unavailable on
IE9 and earlier versions. All other major browsers are supported. Note though
that it has not yet been extensively tested.
+
+## Removing attached files
+
+File input fields unfortunately do not have the option of removing an already
+uploaded file. This is problematic when editing a model which has a file attached
+and the user wants to remove this file. To work around this, Refile automatically
+adds an attribute to your model when you use the `attachment` method, which is
+designed to be used with a checkbox in a form.
+
+``` erb
+<%= form_for @user do |form| %>
+ <%= form.label :profile_image %>
+ <%= form.attachment_field :profile_image %>
+
+ <%= form.check_box :remove_profile_image %>
+ <%= form.label :remove_profile_image %>
+<% end %>
+```
+
+Don't forget to permit this attribute in your controller:
+
+``` ruby
+def user_params
+ params.require(:user).permit(:profile_image, :profile_image_cache_id, :remove_profile_image)
+end
+```
+
+Now when you check this checkbox and submit the form, the previously attached
+file will be removed.
## Cache expiry
Files will accumulate in your cache, and you'll probably want to remove them
after some time.