Sn::Foil::Rails

Installation

Add this line to your application's Gemfile:

gem 'snfoil-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install snfoil-rails

Usage

SnFoil Rails mostly just ties together a bunch of the other SnFoil Repos together. To get the most out of this project we highly recommend you read the docs for SnFoil Contexts, Controllers, Searchers, and Policies.

What it does add is a few rails friend steps for you:

Basic CRUD controllers
JSONAPI Include Parser
Serialize and Deserialize Helpers
Pagination Helpers
Additional Searcher Functionality

CRUD Controllers

To use setup a crud controller you just need to inherit from the SnFoil::Rails::APIController

class PeopleController < SnFoil::Rails::APIController
    ...
end

This will setup create, show, update, destroy, and index for you.

If you only want one or a few of these methods you can include just that functionality using the appropraite concerns.

class PeopleController < ActionController::API
    # Just include Create and Destroy
    include SnFoil::Rails::API::Create
    include SnFoil::Rails::API::Destroy
    ...
end

Helpers

Name	Arguments	Description
inject_deserialized	options - hash	calls the deserialize method using the current option `:params` and injects it into the options hash as `:params`
inject_id	options - hash	attempts to find the appropriate id of the current request model and injects it into the options hash as `:id`
inject_include	options - hash	takes include from the params object, parses it by common, and injects it as a symbolized array into the options hash as ':include'
inject_request_id	options - hash	puts the current request's request_id into the options hash as `:request_id`
inject_request_params	options - hash	calls the current controller's params, symbolizes the keys, and injects it into the options hash as `:params` and `:request_params`. Since `:params` is expected to be overridden by `#inject_deserialized` a copy of the original params is store in `:request_params`
process_pagination	options - hash	uses the `:request_params` to discern how to paginate

Pagination

While most of the helpers are pretty simple pagination require a little more detail.

#process_pagination uses parameters from :request_params in the options hash.

per_page - The amount of results to return per page. If 0 then it will return the page_maximum. Default 10.
page - The page to return.

Searchers

In addition to the base searcher functionality a SnFoil::Rails::Searcher includes the following

order

The default order direction you want the results to be return in. This can be overridden by including order in the request params. Defaults to ASC.

class PeopleSearcher
  include SnFoil::Searcher

  model Person
  order :ASC
end

order_by

The model attribute you want to order by. This can be overridden by including order_by in the request params. Defaults to :id.

class PeopleSearcher
  include SnFoil::Searcher

  model Person
  order_by :last_name
end

distinct

Whether or not to call ActiveRecord's .distinct on the results of the query. Defaults to true.

class PeopleSearcher
  include SnFoil::Searcher

  model Person
  distinct false
end

includes

A shorthand for adding ActiveRecord's .include to the to the query.

class PeopleSearcher
  include SnFoil::Searcher

  model Person
  includes :address,
           { occupation: :employer }
end

Author Notes

What happened to SSR controllers?

Honestly I never used them myself and never heard of anyone else using them. This framework was born out of frustration with REST APIs and the only reason SSR was implemented in the first place was a CYA move. Rather than keeping something in that I wasn't actively using, I decided to focus on what I was. If you are interested in bring SSR controllers back feel free to reach out and I can walk you through it!

Contributing

Contribution directions go here.

License

The gem is available as open source under the terms of the MIT License.

snfoil-rails

Development

Runtime