{"id":19211616,"url":"https://github.com/marcusg/force_format","last_synced_at":"2025-05-12T20:08:36.307Z","repository":{"id":10798839,"uuid":"13070461","full_name":"marcusg/force_format","owner":"marcusg","description":"Define the formats your Rails application controllers should respond to. ","archived":false,"fork":false,"pushed_at":"2013-10-10T14:14:35.000Z","size":336,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-20T17:39:07.767Z","etag":null,"topics":[],"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/marcusg.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2013-09-24T16:33:43.000Z","updated_at":"2019-02-08T01:22:39.000Z","dependencies_parsed_at":"2022-09-02T14:32:08.417Z","dependency_job_id":null,"html_url":"https://github.com/marcusg/force_format","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusg%2Fforce_format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusg%2Fforce_format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusg%2Fforce_format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusg%2Fforce_format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcusg","download_url":"https://codeload.github.com/marcusg/force_format/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253805843,"owners_count":21967052,"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":[],"created_at":"2024-11-09T13:43:07.398Z","updated_at":"2025-05-12T20:08:36.255Z","avatar_url":"https://github.com/marcusg.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# force_format\n\n[![Gem Version](https://badge.fury.io/rb/force_format.png)](http://badge.fury.io/rb/force_format)\n[![Build Status](https://travis-ci.org/marcusg/force_format.png?branch=master)](https://travis-ci.org/marcusg/force_format)\n[![Code Climate](https://codeclimate.com/github/marcusg/force_format.png)](https://codeclimate.com/github/marcusg/force_format)\n[![Dependency Status](https://gemnasium.com/marcusg/force_format.png)](https://gemnasium.com/marcusg/force_format)\n\nDefine  the formats your Rails application should respond to within your controllers.\n\n## Background\n\nNormally a Rails3 application tries to respond to all kinds of formats (e.g. html, xml, json, ...)\ndefined via ```respond_to``` inside the controller. Given the following setup for a controller responding\nto html and javascript requests.\n\n    class PagesController \u003c ApplicationController\n\n      def index\n        respond_to do |format|\n          format.html\n          format.js\n        end\n      end\n    end\n\nAll other requests will return a white page with status code 406 (Not Acceptable). For some this seems to be a correct behaviour but it may be important for some webapps to render out a error page giving a good description of the error - like 404 pages. In other words: If the action can't handle the requested format, render out an error page with an supported format like html.\n\nThis is where ```force_format``` joins the game. The gem adds some accessible methods for your controllers based on before_filters. With that you can define the allowed formats for each controller action. If the requested mime-type does not\nmatch one of the specified formats, ```force_format``` will raise a custom exception wich you can handle on you own (e.g. print out some useful sentences for your users).\n\nBesides this, if you theoretical don't need the ```respond_to``` because you use templates which are rendered by default, you can omit the ```respond_to``` block when using ```force_format```.\n\n## Requirements\n\n```rails \u003e= 3.2```\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'force_format'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install force_format\n\n## Usage\n\n#### Basics\n\nInclude the ```force_format_filter``` method in your controllers.\nThe important param is the ```:for =\u003e [:my, :formats]```.\nWith that given array of fomat types you can define the formats the\naction should respond to (and hopefully find a template).\nIn addition it accepts ```:only =\u003e ...```, ```:except =\u003e ...```, ```:if =\u003e ...```\nand ```:unless =\u003e ...``` parameters like the Rails filters.\n\n\n\n    class PagesController \u003c ApplicationController\n      force_format_filter :for =\u003e [:html, :js], :only =\u003e :index\n\n      def index\n      end\n    end\n\n\n#### Supported format types\nFor the moment the following (MIME-)types are available.\n\n    ForceFormat::Controller::FORCE_FORMAT_TYPES\n    =\u003e [:html, :js, :json, :pdf, :csv, :zip, :xml]\n\n\n#### Skip the filter\n\nIf you want to skip the filter in inherited controllers, use the ```skip_force_format_filter``` method.\nIt accepts the same parameters the ```force_format_filter``` methods except ```:for =\u003e ...```.\n\n#### And more options...\n\nMaybe you want to define the formats more granular, for example different per action.\nTo accomplish this, pass an hash with action names and required formats. Add a *:default* key with formats\nfor actions that are not specified directly.\n\n\n    class PagesController \u003c ApplicationController\n      force_format_filter :for =\u003e {:index =\u003e :js, :default =\u003e [:json, :html]}\n\n      def index\n        # should respond with js\n      end\n\n      def new\n        # should respond with json or html\n      end\n\n    end\n\n\n#### Handling exceptions\n\nBy default ```force_format``` raises an ```ForceFormat::Errors::UnknownFormat```\nif a requested format matches none of the attributes specified via ```:for =\u003e ...```.\nIt should be easy to rescue from this exception, for example in your ```application_controller.rb```:\n\n\n    class ApplicationController \u003c ActionController::Base\n\n      rescue_from ForceFormat::Errors::UnknownFormat, :with =\u003e :render_error\n\n      def render_error\n        # handle it\n      end\n    end\n\n#### Use custom exception\n\nYou can pass an custom exception lambda to the ```force_format_filter``` method for a better error handling.\n\n    class PagesController \u003c ApplicationController\n      force_format_filter :for =\u003e :html, :exception =\u003e lambda { |msg| raise(MyApp::AwesomeException.new(msg)) }\n    end\n\n\n#### Widcard accept header\n\nIf an user agent sets the accept header wildcard like ```*/*``` ```force_format_filter``` would fallback\nand set the ```request.format``` to *:html*. This is important for access via ```curl``` and I think for the\ngoogle bot too. If you don't want this behaviour of wildcard rewriting you can set the ```:skip_wildcard``` option.\n\n    class PagesController \u003c ApplicationController\n      force_format_filter :for =\u003e :html, :skip_wildcard =\u003e true\n    end\n\nNOTE: Call the method ```force_format_filter``` only once per controller!\nIf you call it multiple times, the last one would be used.\n\n\n## TODO\n1. More tests\n2. More robust params checking\n\n\n## Contributing\n\n1. Fork it\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 new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusg%2Fforce_format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcusg%2Fforce_format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusg%2Fforce_format/lists"}