{"id":19474618,"url":"https://github.com/tomasc/simple_form_attachments","last_synced_at":"2025-04-25T12:31:54.137Z","repository":{"id":30882880,"uuid":"34440565","full_name":"tomasc/simple_form_attachments","owner":"tomasc","description":"A Rails engine which takes care of creating Attachments using the jQuery File Upload plugin.","archived":false,"fork":false,"pushed_at":"2021-12-17T11:03:30.000Z","size":34972,"stargazers_count":2,"open_issues_count":5,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-17T19:37:36.232Z","etag":null,"topics":["attachments","engine","ruby-on-rails","uploads"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomasc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-23T07:24:00.000Z","updated_at":"2022-08-01T06:57:25.000Z","dependencies_parsed_at":"2022-08-07T16:00:19.160Z","dependency_job_id":null,"html_url":"https://github.com/tomasc/simple_form_attachments","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomasc%2Fsimple_form_attachments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomasc%2Fsimple_form_attachments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomasc%2Fsimple_form_attachments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomasc%2Fsimple_form_attachments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomasc","download_url":"https://codeload.github.com/tomasc/simple_form_attachments/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250817809,"owners_count":21492228,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["attachments","engine","ruby-on-rails","uploads"],"created_at":"2024-11-10T19:25:52.595Z","updated_at":"2025-04-25T12:31:53.088Z","avatar_url":"https://github.com/tomasc.png","language":"Ruby","readme":"# SimpleFormAttachments\n\n[![Build Status](https://travis-ci.org/tomasc/simple_form_attachments.svg)](https://travis-ci.org/tomasc/simple_form_attachments) [![Gem Version](https://badge.fury.io/rb/simple_form_attachments.svg)](http://badge.fury.io/rb/simple_form_attachments) [![Coverage Status](https://img.shields.io/coveralls/tomasc/simple_form_attachments.svg)](https://coveralls.io/r/tomasc/simple_form_attachments)\n\nA Rails engine for creating Attachments using the [jQuery File Upload](https://github.com/blueimp/jQuery-File-Upload) plugin.\n\nDependencies:\n* [Mongoid](http://mongoid.org)\n* [Simple Form](https://github.com/plataformatec/simple_form)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'simple_form_attachments'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install simple_form_attachments\n\nAdd `simple_form_attachments` to `application.js`:\n\n    //= require simple_form_attachments\n\n## Usage\n\n### Attachment model\n\nCreate a model for your attachments that includes the `SimpleFormAttachments::Attachment` concern:\n\n```ruby\nclass AttachmentImage\n  include SimpleFormAttachments::Attachment\nend\n```\n\nThis adds a `:temporary` Boolean field (set to `false` by default) and two scopes: `temporary` and `permanent` to the model.\n\nNote that the concern does not include any specific accessors (ie Dragonfly). You need to define those yourself in your model.\n\n#### Validations\n\nStandard Rails validation errors are displayed in the uploader, should the uploaded file not pass the validations defined on the attachment model.\n\n### Owner model\n\nAdd the `SimpleFormAttachments::HasAttachments` concern to the attachment owner. This includes the mongoid relation macros `has_one_attachment` and `has_many_attachments`:\n\n```ruby\nclass Parent\n  include Mongoid::Document\n  include SimpleFormAttachments::HasAttachments\n\n  has_one_attachment :attachment_pdf, class_name: 'AttachmentPdf'\n  has_many_attachments :attachment_images, class_name: 'AttachmentImage'\nend\n```\n\nRelations between the parent and Attachment are referenced, not embedded. The gem uses `belongs_to` for 1–1 relations and `has_and_belongs_to_many` for 1–n relations. This is to ensure that relations work with embedded parents, since the relations need to be stored on the owner's side.\n\nYou could use for example the `before_save` callback to embed the attachments yourself.\n\n#### Callbacks\n\nSince attachments can be added/removed dynamically in the form, we need to indicate which ones are actually submitted in the end, so that we can – immediately or later (left up to you) – delete the temporary ones.\n\nFor that each relation defines a method named after the relation name, which can be called for example via a callback:\n\n```ruby\nafter_save :mark_attachment_pdf_permanent\nafter_save :mark_attachment_images_permanent\n```\n\nThese methods (atomically) set the attachment's `:temporary` attribute to `false`.\n\nAlternatively the `mark_all_attachments_permanent` method can be used to loop through all attachment relations, triggering individual above-mentioned methods. This means the two `after_save` callbacks above can be replaced with:\n\n```ruby\nafter_save :mark_all_attachments_permanent\n```\n\n#### Validations\n\nIf you want to validate the number of attachments allowed on the owner, you can use for example the following validation. Eventual validation errors will be displayed to the user when submitting the parent form.\n\n```ruby\nvalidates :attachment_pdfs, length: { maximum: 2 }\n```\n\n### Controller\n\nThe default `UploadController` receives the uploaded attachment, sets its `temporary` to `true` and creates corresponding record in the database.\n\nRemember, you need to mark attachments as permanent (ie `temporary` to `false`) yourself. See Callbacks above.\n\n### Routes\n\nMount the engine in your routes:\n\n```ruby\nmount SimpleFormAttachments::Engine =\u003e \"/\"\n```\n\nThis will include a default `/attachments` route.\n\n### Forms\n\nNow you can use the attachment input in your SimpleForm forms:\n\n```ruby\n= form.input :attachment_images, as: :attachment\n```\n\n## Configuration\n\n### Sorting\n\nSorting of attachments is turned on by default for `has_many_attachments` relations. But it's possible to disable sorting on a field:\n\n```slim\n= f.input :attachment_images, as: :attachment, sortable: false\n```\n\n### Views\n\nUploaded attachments are displayed in a `div`. The gem will look for a partial using the normal rails partial lookup (with a fallback to the default partial), this makes it easy to define a partial for each of your attachment models.\n\nHere an example partial for a model called `AttachmentImage`:\n\n```slim\n/ app/views/simple_form_attachments/attachment_images/_attachment_image.html.slim\n/ (Note the nesting in 'simple_form_attachments' directory.)\n\ndiv class=SimpleFormAttachments.dom_class(:attachment, [:col, :thumb])\n  = image_tag attachment.thumb_url\n\ndiv class=SimpleFormAttachments.dom_class(:attachment, [:col, :file_info])\n  span class=SimpleFormAttachments.dom_class(:attachment, :col, :file_info, :name)\n    = link_to attachment.file_name, attachment.file.url\n  span class=SimpleFormAttachments.dom_class(:attachment, :col, :file_info, :mime_type)\n    = attachment.file_mime_type\n  span class=SimpleFormAttachments.dom_class(:attachment, :col, :file_info, :size) data-filesize=attachment.file_size\n    = attachment.file_size\n\n- if attachment.errors.to_a.any?\n  div class=SimpleFormAttachments.dom_class(:attachment, [:col, :errors])\n    = render 'simple_form_attachments/errors', errors: attachment.errors.to_a\n\n- else\n  div class=SimpleFormAttachments.dom_class(:attachment, [:col, :fields])\n    = fields.input :caption\n```\n\n### Dom class and CSS\n\nThe component is isolated in the `simple_form_attachments` namespace. This gem comes with its own helper that generates corresponding class names – for example `SimpleFormAttachments.dom_class(:attachment, :file_info)` would generate `simple_form_attachments__file_info`.\n\nBasic styling can be achieved by including `simple_form_attachments` css in your app:\n\n```css\n/*\n*= require simple_form_attachments\n*/\n```\n\n#### Validation errors\n\nIf you want to show validation errors in your partial, simply include the `simple_form_attachments/errors` partial as shown above.\n\n### Route\n\nYou can customize the engine to use a different controller and route, for example should you want to preprocess the uploaded files or determine the attachment model based on file mime/extension/format, ….\n\nSetup a controller for your attachments:\n\n```ruby\nclass AttachmentsController \u003c SimpleFormAttachments::UploadController\n  # The default controller uses the attachment type passed from the form input\n  # to determine which Attachment class to create.\n  #\n  # This can be easily overridden, for instance if you want to infer\n  # the class from the `mime type` of the file:\n  #\n  def attachment_class\n    mime_type = params[:attachment][:file].content_type\n  end\nend\n```\n\nAdd route as usual:\n\n```ruby\nresources :attachments, only: [:create]\n```\n\nSpecify the route either app wide in an initializer:\n\n```ruby\n# config/initializers/simple_form_attachments.rb\n\nrequire 'simple_form_attachments'\n# Configuration\n\nSimpleFormAttachments::AttachmentInput.configure do |c|\n  c.route = attachments_path\n  # can be also specified as a lambda to be evaluated at runtime: -\u003e { attachments_path }\nend\n```\n\nOr per input:\n\n```slim\n= f.input :attachment_images, as: :attachment, route: attachments_path\n```\n\n## Testing\n\nBesides a `MiniTest` test suite, the gem has a dummy app located at `test/dummy`. Simply `cd` into the directory and run `bin/rails s` to test the uploader.\n\n## Contributing\n\n1. Fork it ( https://github.com/tomasc/simple_form_attachments/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomasc%2Fsimple_form_attachments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomasc%2Fsimple_form_attachments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomasc%2Fsimple_form_attachments/lists"}