{"id":13519358,"url":"https://github.com/filestack/filestack-rails","last_synced_at":"2025-11-11T18:39:13.905Z","repository":{"id":4756609,"uuid":"5906709","full_name":"filestack/filestack-rails","owner":"filestack","description":"Official Ruby on Rails plugin for Filestack File Picker that makes it easy to add powerful file uploading and transformation capabilities to any web or mobile application.","archived":false,"fork":false,"pushed_at":"2024-12-10T22:54:49.000Z","size":678,"stargazers_count":222,"open_issues_count":12,"forks_count":101,"subscribers_count":22,"default_branch":"develop","last_synced_at":"2025-10-29T17:10:17.525Z","etag":null,"topics":["hacktoberfest","ruby","ruby-gem","ruby-on-rails","transforming-files","upload","upload-file","upload-images"],"latest_commit_sha":null,"homepage":"https://www.filestack.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filestack.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-09-21T20:03:33.000Z","updated_at":"2025-07-15T05:37:18.000Z","dependencies_parsed_at":"2024-04-10T20:41:53.681Z","dependency_job_id":"20e0a779-3723-4631-8a1b-1c04bb8c7693","html_url":"https://github.com/filestack/filestack-rails","commit_stats":{"total_commits":347,"total_committers":60,"mean_commits":5.783333333333333,"dds":0.6628242074927955,"last_synced_commit":"2e54a71894c076e2073a5e7501c87ffea99983f0"},"previous_names":["filepicker/filepicker-rails"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/filestack/filestack-rails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filestack","download_url":"https://codeload.github.com/filestack/filestack-rails/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filestack%2Ffilestack-rails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283543910,"owners_count":26853366,"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","status":"online","status_checked_at":"2025-11-09T02:00:05.828Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["hacktoberfest","ruby","ruby-gem","ruby-on-rails","transforming-files","upload","upload-file","upload-images"],"created_at":"2024-08-01T05:01:57.831Z","updated_at":"2025-11-11T18:39:13.889Z","avatar_url":"https://github.com/filestack.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Gems"],"sub_categories":["Articles"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"logo.svg\" align=\"center\" width=\"100\"/\u003e\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eFilestack::Rails SDK\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/filestack/filestack-rails\"\u003e\n    \u003cimg src=\"https://img.shields.io/travis/filestack/filestack-rails/master.svg?longCache=true\u0026style=flat-square\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/filestack/filestack-rails?branch=master\"\u003e\n    \u003cimg src=\"https://img.shields.io/coveralls/github/filestack/filestack-rails/master.svg?longCache=true\u0026style=flat-square\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\nRails SDK for Filestack API and content management system.\n\u003c/p\u003e\n\n**Important: This is the readme for 4.0.0+.**\n\nNote that the [Filestack::Ruby](https://github.com/filestack/filestack-ruby/) dependency has been updated to no longer interfere with namespace. However, if you were using that dependency in your Rails application, you will need to change any `Client` and `Filelink` class declarations to `FilestackClient` and `FilestackFilelink`, as per documented [here](https://github.com/filestack/filestack-ruby/blob/master/README.md).\n\n## Overview\n\n* A multi-part uploader powered on the backend by the [Filestack CIN](https://www.filestack.com/products/content-ingestion-network).\n* An interface to the [Filestack Processing Engine](https://www.filestack.com/docs/image-transformations) for transforming assets via URLs.\n* The Filestack Picker - an upload widget for the web that integrates over a dozen cloud providers and provides pre-upload image editing.\n\n## Installation\n\nAdd this line to your application's `Gemfile`:\n\n```ruby\ngem 'filestack-rails'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install filestack-rails\n\nAdd the Filestack File Picker and initialization script to your layout:\n\n```erb\n\u003c%= filestack_js_include_tag %\u003e\n\u003c%= filestack_js_init_tag %\u003e\n```\n**Please note:** The scripts need to be added before your application's custom scripts, e.g. before any scripts in your assets folder, if you need access the Filestack client in your own Javascript.\n\nSet your API key and client name in `config/application.rb`:\n\n```ruby\nconfig.filestack_rails.api_key = 'Your Filestack API Key'\nconfig.filestack_rails.client_name = 'custom_client_name'\n```\nThe client name defaults to `\"filestack_client\"` and is injected into your client-side Javascript. This is because v3 of the File Picker lives in the Javascript of your web application.\n\n### Filestack Picker Version\n\nFor Filestack Rails SDK v.4.0.0+, the picker `version` is setup by default to `v3`. It means that Javascript version is 1.x.x. If you want to use older Javascript version (0.11.5), you have to configure `version` to `v2` in `config/application.rb`:\n```ruby\n# filestack-js (0.11.5)\nconfig.filestack_rails.version = 'v2'\n\n# filestack-js (1.x.x)\nconfig.filestack_rails.version = 'v3'\n```\n\nFor Filestack Rails SDK v.5.0.0+, you have to provide picker version precisely. By default the picker version is setup to `3.x.x`. If you want to use older filestack-js version (0.11.5), you have to configure `version` to `0.11.5` in `config/application.rb`:\n```ruby\n# filestack-js (0.11.5)\nconfig.filestack_rails.version = '0.11.5'\n\n# filestack-js (1.x.x)\nconfig.filestack_rails.version = '1.x.x'\n\n# filestack-js (3.x.x)\nconfig.filestack_rails.version = '3.x.x'\n```\n\nPlease take a look on available versions in [filestack-js](https://github.com/filestack/filestack-js) repository.\n\n### CNAME\n\nIf you have set up a custom CNAME, you can add it to your configuration file. The Picker will modify all assets to formatted with your domain origin instead of Filestack's.\n\nSet your CNAME in `config/application.rb`:\n\n```ruby\nconfig.filestack_rails.cname = 'custom_cname'\n```\n\n### Security\n\nIf your account has security enabled, then you must initialize the File Picker with a signature and policy.\n\nSet up your application secret and security options in `config/application.rb`:\n\n```ruby\nconfig.filestack_rails.app_secret = 'YOUR_APP_SECRET'\nconfig.filestack_rails.security = {'call' =\u003e %w[pick store read convert] }\n```\nIf you set security to an empty object like so:\n```ruby\nconfig.filestack_rails.security = {}\n```\nIt will provide a policy and signature with only an expiry setting (this defaults to one hour).\n\nYou can access the generated policy and signature anytime by calling their attributes on the created security object:\n\n```ruby\nputs config.filestack_rails.security.policy\nputs config.filestack_rails.security.signature\n```\nYou can also generate a new security object at any time, although this will only affect the filestack_image tag, and not the File Picker client.\n\n## Usage\n\n### Filestack Upload Button\nThis is a generic button that can be added anywhere in your application and opens an instance of the File Picker. Once a user has chosen a file(s) and submitted, a callback will be executed, passing in the results. You can also pass in any options for the File Picker using the `pickerOptions` symbol:\n\n```erb\n\u003c%= filestack_picker_element 'button test', 'callbackForButton', id: 'someuniqueid', input_id: 'someuniqueinputid', pickerOptions: { 'fromSources': 'facebook', 'maxFiles': 50 } %\u003e\n```\nFile Picker options are exactly the same as in the Javscript SDK and can be found in the aforementioned documentation.\n\nThe callback can be either the name of a function you've defined in your main Javascript or it can be any code that is immediately executable, e.g. `console.log` or `(function(data){console.log(data)})`. The callback should take in a response array as its only argument, which has the following structure:\n\n```javascript\n{\n    \"filesUploaded\": [\n        {\n            \"filename\":\"Birds\",\n            \"handle\":\"unique_filestack_handle\",\n            \"mimetype\":\"image/jpeg\",\n            \"originalPath\":\"/bird/flickr/3/2849/9533051578_377332e54c_z.jpg/Birds\",\n            \"size\":121727,\n            \"source\":\"imagesearch\",\n            \"url\":\"https://cdn.filestackcontent.com/unique_filestack_handle\",\n            \"key\":\"fnZb1ElSMmKCLPNaErRU_bird.jpg\",\n            \"container\":\"filestack-website-uploads\"\n        },\n        {\n            \"filename\": ...\n        }\n    ],\n    \"filesFailed\": []\n}\n```\n\nEach file that is uploaded will be represented as a single object within the filesUploaded array. Accessing the first file uploaded in the callback would be achieved like so:\n```javascript\nurl = data.filesUploaded[0].url\n```\n\nFor version `v3`, you can add following callbacks: `onOpen`, `onClose`, `onFileUploadFinished`, `onFileSelected`, `onUploadStarted`, to `pickerOptions`.\n\n```erb\n\u003c%= filestack_picker_element 'button test', 'callbackForButton', id: 'someuniqueid', input_id: 'someuniqueinputid', pickerOptions: { onClose: 'callbackOnClose', onOpen: 'callbackOnOpen', onFileUploadFinished: 'callbackOnFileUploadFinished' } %\u003e\n```\n\nwhere following callbacks `callbackOnClose`, `callbackOnOpen`, `callbackOnFileUploadFinished` are javascript function's name and refer to your own created function. For instance:\n\n```js\nfunction onFileUploadFinishedCallback(data) {console.log(data);}\n```\n\n### Filestack Form Helper\nThe form helper wraps the generic Pick element and adds the value of the returned file to an invisible text element, in order to attach to the form. It accepts the same options as the Pick element and renders the same button.\n\n```erb\n\u003c%= form_for @user do |f| %\u003e\n  \u003cdiv\u003e\n    \u003c%= f.filestack_field :filepicker_url, 'Upload Your Avatar!',  pickerOptions: {'fromSources': 'facebook'}, id: 'unique-id', input_id: 'unique-input-id' %\u003e\n  \u003c/div\u003e\n\n  \u003c%= f.submit %\u003e\n\u003c% end %\u003e\n```\n### Displaying an image with Filestack Transformations:\nFilestack::Rails now has access to the full list of image transforms through our custom Transformation Engine. This functionality is provided by the Filestack Ruby SDK and acts as a small wrapper around it. The `filestack_image` tag accepts the same options as the genric Rails `image_tag`, with the addition of a transform option, which accepts a `filestack_transform` chain:\n\n```erb\n\u003c%= filestack_image @user.filepicker_url, transform: filestack_transform.resize(width:100, height:100).flip.enhance %\u003e\n```\n\nYou can also add attributes to `image_tag`, for instance:\n```erb\n\u003c%= filestack_image @user.filepicker_url, size: \"160x100\", alt: \"Picture\" %\u003e\n```\n\n### Fetching a converted Filestack image URL with Filestack Transformations:\nThe `filestack_image_url` method accepts the original Filestack image URL and an optional `filestack_transform` chain:\n\n```erb\n\u003c%= image_tag @user.filepicker_url, data: { transformed_image_url: filestack_image_url(@user.filepicker_url, filestack_transform.resize(width: 100, height: 100).flip.enhance) } %\u003e\n```\n\n## Migrating from 2.x to 3.x\nFilestack::Rails 3.x is a significant and breaking change. Users wishing to upgrade will need to change their current implementation in order to use the plugin correctly.\n\n### Javascript-based File Picker\nThe v3 File Picker is a Javascript application that lives on the client-side of your application. This means you have greater control and access to when it is called, access to the rest of the web SDK, as well as being able to pass callbacks executed once uploads have completed. You must keep in mind the File Picker client lives in global scope and adjust your namespaces accordingly, although you can also change the name of the client, as detailed in the above sections.\n\n### Form Helper\nThe form helper's call remains essentially the same, except that it now takes as its argument the value of the button element displayed on the page.\n```erb\n\u003c%= f.filestack_field :filestack_url, 'Pick Your Avatar' \u003e\n```\n### Save Button\nAs user saving/downloading is not currently supported in the v3 File Picker, that functionality has been removed from Filestack::Rails for the time being.\n\n### Transformations\nThe `filestack_image` tag wraps the generic Rails `image_tag` and generates a new URL with use of the Ruby SDK. This provides the entire scope of the possible transformations through Filestack's transformation engine, minus those which do not return an image (like debug, av_convert, and so forth). Defining transformations is as simple as chaining them together using the `filestack_transform` method:\n```erb\n\u003c%= @user.filestack_url, transform: filestack_transform.resize(width:100, height:100).enhance %\u003e\n```\nFor a list of valid transformations, please see [here](https://www.filestack.com/docs/api/processing/).\n\n### Ruby SDK\nFilestack::Rails injects the Filestack Ruby SDK into your application for use anywhere. You can use it to access the rest of the Filestack API and find its documentation [here](https://github.com/filestack/filestack-ruby).\n\n## Demo\n\nTo see the Filestack::Rails plugin in action, clone this repository and run the demo app by following these instructions (will only work in Rails 5.x):\n\n### Set API key\n\nGo to ```spec/dummy/config/application.rb``` and change the API key to your own.\n\n### Install Dependencies\n\nNavigate to the ```spec/dummy``` folder and run:\n```\n$ bundle install\n```\n\n### Migrate User Database\n\nThe form field requires a User model, which has been predefined, and so you need to migrate the database:\n```\nrails db:migrate\n```\n\n### Run Server\n\nWhile in the ```spec/dummy``` directory, run the server\n```\nrails s\n```\nand navigate to http://localhost:3000.\n\n## Versioning\n\nFilestack::Rails follows the [Semantic Versioning](http://semver.org/).\n\n## Issues\n\nIf you have problems, please create a [Github Issue](https://github.com/filestack/filestack-rails/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilestack%2Ffilestack-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilestack%2Ffilestack-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilestack%2Ffilestack-rails/lists"}