Effective Resources

This gem looks at the current routes.rb, authorization ability.rb, current_user and controller context to metaprogram an effective CRUD website.

It automates linking to resource edit, show, delete pages, as well as member and collection actions.

It totally replaces your controller, and instead provides a simple DSL to route actions based on your form params[:commit].

The goal of this gem is to reduce the amount of code that needs to be written when developing a ruby on rails website.

It’s ruby on rails, on effective rails.

Getting Started

ruby gem 'effective_resources'

Run the bundle command to install it:

console bundle install

Install the configuration file:

console rails generate effective_resources:install

The generator will install an initializer which describes all configuration options.

Check the config/initializer/effective_resources.rb and make sure it’s calling your authentication library correctly.

config.authorization_method = Proc.new { |controller, action, resource| authorize!(action, resource) } # CanCanCan

Workflow

A rails developer will always need to maintain and write:

The routes.rb as it’s the single most important file in an entire app.
The ability.rb or other authorization.
A normal ApplicationRecord model file for each model, /app/models/post.rb.
Its corresponding form, /app/views/posts/_form.html.haml and _post.html.haml
Any javascript and css

However, all other areas of code should be automated.

This gem replaces the following work a rails developer would normally do:

Controllers.
Any file named index/edit/show/new.html. We use rails application templates and powerful defaults views so these files need never be written.
Writing permitted params. This gem implements a model dsl to define and blacklist params.
Manually checking which actions are available to the current_user on each resource all the time.
Writing submit buttons

Quick Start

This gem was built to quickly build CRUD interfaces. Automate all the actions, and submit buttons.

It uses the params[:commit] message to call the appropriate action, or save on the given resource.

It reads the routes.rb to serve collection and member actions, and considers current_user and ability.rb

Tries to do the right thing in all situations.

Add to your app/models/post.rb:

```ruby class Post < ApplicationRecord belongs_to :author, class_name: ‘User’

# The only thing this block is used for - right now - is permitted_params effective_resource do category :string title :string body :text

approved      :boolean, permitted: false   # You could write permitted: [:admin] to only permit this in the admin namespace

timestamps   end

# The approve! action will be called by Effective::CrudController when submitted on a create/update or member action def approve! raise ‘already approved’ if approved?s update!(approved: true) end end ```

Add to your routes.rb:

ruby resources :posts

Add to your contoller:

```ruby class PostsController < ApplicationController include Effective::CrudController

submit :approve, ‘Approve’ end ```

and in your view:

ruby = form_with(model: post) do = f.input :text = effective_submit(f) # Will make a Save and an Approve. Rails 5 forms. = simple_form_submit(f) # Ditto.

and in your authorization:

ruby can :approve, Post # can(:approve, Post) { |post| !post.approved? }

Controller

Implements the 7 RESTful actions: index, new, create, show, edit, update, destroy.

Loads an appropriate @posts or @post type instance variable.
Sets a @page_title (effective_pages).
Calls authorize as per the configured EffectiveResources.authorization_method (flow through to CanCan or Pundit)
Does the create/update save
Sets a flash[:success] and redirects on success, or sets a flash.now[:danger] and renders on error.
Does the right thing with member and collection actions
Intelligently redirects based on commit message

You can override individual methods on the CrudController.

Here is a more advanced example:

```ruby class PostsController < ApplicationController include Effective::CrudController # Sets the @page_title in a before_filter page_title ‘My Posts’, only: [:index]

# Callbacks: before_render, before_save, after_save, after_error, after_commit before_render(only: :new) do resource.client = current_user.clients.first end

submit :accept, ‘Accept’, if: -> { !resource.approved? }, # Imho this check should be kept in ability.rb, but you could do it here. redirect: -> { accepted_posts_path }, success: ‘The @resource has been approved’ # Any @resource will be replaced with @resource.to_s

# All queries and objects will be built with this scope resource_scope -> { current_user.posts }

# Similar to above, with block syntax resource_scope do Post.active.where(user: current_user) end

protected

# The post_params are discovered from the model effective_resource do … end block. # But you could also define them like this if you wanted. # Other recognized method names are posts_params and permitted_params def post_params params.require(:post).permit(:id, :author_id, :category, :title, :body) end

# Pass /things/new?duplicate_id=3 def duplicate_resource(resource) resource_klass.new(resource.attributes.slice(‘job_site’, ‘address’)) end end ```

Helpers

effective_submit & simple_form_submit

rails = form_with(model: post) do |f| = effective_submit(f) = simple_form_submit(f)

These helpers output the = f.submit 'Save' based on the controllers submits, the current_user and ability.rb.

They try to add good data-confirm options for delete buttons and sort by btn-primary, btn-secondary and btn-danger.

Application Templates

When you installed the gem, it should make some views/application/index.html.haml, new.html.haml, etc.

If you’re not using haml, you should be, go install haml. Or convert to slim, you sly devils.

These files, possibly customized to your app, should replace almost all resource specific views.

Just create a _form.html.haml and _post.html.haml for each resource.

Just put another app/views/posts/index.html.haml in the posts directory to override the default template.

Concerns

Sure why not. These don’t really fit into my code base anywhere else.

acts_as_paginable

Quickly adds a paginate scope to your model that can then be used in your views and also integrates well with effective_bootstrap. The pagination method is Limit and Offset.

```ruby # Given any model you just need to call it like class Thing < ApplicationRecord acts_as_paginable end

Now you can use it like:

Thing.all.paginate(page: 1, per_page: 5) ``` ### acts_as_tokened

Quickly adds rails 5 has_secure_token to your model, along with some Post.find() enhancements to work with tokens instead of IDs.

This prevents enumeration of this resource.

Make sure to create a string token field on your model, then just declare acts_as_tokened. There are no options.

acts_as_archived

Create an ‘archived’ boolean filed in your model, then declare acts_as_archived.

Implements the dumb archived pattern.

An archived object should not be displayed on index screens, or any related resource’s #new pages

effective_select (from the effective_bootstrap gem) is aware of this concern, and calls .unarchived and .archived appropriately when passed an ActiveRecord relation.

Use the cascade argument to cascade archived changes to any has_manys

ruby class Thing < ApplicationRecord has_many :comments acts_as_archivable cascade: :comments end

Each controller needs its own archive and unarchive action. To simplify this, use the following route concern.

In your routes.rb:

```ruby Rails.application.routes.draw do acts_as_archived

resource :things, concern: :acts_as_archived resource :comments, concern: :acts_as_archived end ```

and include Effective::CrudController in your resource controller.

acts_as_wizard

Build up an object through a wizard.

Works with the wicked gem to create wizard quickly.

Create a model and define acts_as_wizard:

```ruby class Thing < ApplicationRecord acts_as_wizard( start: ‘Start’, select: ‘Select’, finish: ‘Finish’ )

effective_resource do title :string wizard_steps :text, permitted: false end

validates :title, presence: true

def to_s title.presence || ‘New Thing’ end

# If you define a bang method matching the name of a step # it will be called when that step is submitted. # Otherwise save! is called. def select! ApplicationMailer.selected(self).deliver_later save! end

# An array of steps that the controller will use # Default value is just all of them. But you can customize here # def required_steps # steps = WIZARD_STEPS.keys # selectable? ? steps : steps - [:select] # end

# Control whether the user has permission to visit this step # # This is the default, can go forward or back: # # def can_visit_step?(step) # can_revisit_completed_steps(step) # end # # Easy change if you only want to go forward: # # def can_visit_step?(step) # cannot_revisit_completed_steps(step) # end # # or custom algorithm: # # def can_visit_step?(step) # return false unless has_completed_previous_step?(step) # return false if has_completed_step?(:finish) && step != :finish # end end ```

In your routes:

ruby resources :things, only: [:index, :show, :new, :destroy] do resources :build, controller: :things, only: [:show, :update] end

Make a controller:

ruby class ThingsController < ApplicationController include Effective::WizardController end

And then create one view per step.

Here’s views/things/start.html.haml:

```haml = render_wizard_sidebar(resource) do %h1= @page_title

= effective_form_with(model: resource, url: wizard_path(step), method: :put) do |f| = f.text_field :title = f.submit ‘Save and Continue’ ```

You can also call render_wizard_sidebar(resource) without the block syntax.

If you add f.hidden_field(:skip_to_step, value: 'stepc') you can control the next step.

Select2 Ajax Controller

This gem provides an admin endpoint for select2 AJAX to fetch users.

To use this endpoint please add

can :admin, :effective_resources

And then create a select field like this:

= f.select :user_id, current_user.class.all, ajax_url: effective_resources.users_admin_select2_ajax_index_path

To format the results, add a method to your User class. It can return html.

def to_select2 "<span>#{user.first_name} #{user.last_name}</span> <small>#{user.email}</small>" end

Authentication

Effective Resources is designed to work with Devise. It also adds support for an alternate email for authentication. You just need to add an alternate_email column to your User model table.

After that column is added, any user would be able to log in with either their email or their alternate_email.

You can also create another mailer for devise in order to send password reset emails to the both the primary email and also the alternate_email, like this:

```ruby class DeviseMailer < Devise::Mailer # Overriding Devise’s #headers_for to support alternate_email when present def headers_for(action, opts) headers = super(action, opts)

if [:reset_password_instructions].include?(action)
  headers.merge!(
    to: [resource.email, resource.try(:alternate_email)].compact.uniq
  )
end

headers   end end ```

and set this new mailer to be used by devise in config/initializers/devise.rb:

ruby Devise.setup do |config| # ... config.mailer = 'DeviseMailer' # ... end

Testing

Run tests by:

ruby rails test

License

MIT License. Copyright Code and Effect Inc.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Bonus points for test coverage
Create new Pull Request