godmin 0.10.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 53be376cd7a129561b4522def2402cccb39d3058
-  data.tar.gz: 0d6f5077a4d56bbdb7bc4dcdd53fd2175f7383ad
+  metadata.gz: f825ae621a3f84cb0d609b8c701f17f6e7febe80
+  data.tar.gz: 37128e9e80e832c80f1fff70a840495ed703d3bb
 SHA512:
-  metadata.gz: dd9ef0ee561183456d29bdcfb9790f5c7779ac1fd38cd6655a860daff9b7094c2fe7c139956f0a973c42fb876ea6f6d38d4b8bc3f407e01057b27094c04d001b
-  data.tar.gz: 904eb969e8b6a2b9086bf630b5efd3ab0113fa6a95aa3472121e10dfb25f6ce6ff4ac758f3b9875888c3aafd1b2c0cfeb4c4ab08c17303c94585d2580b69d91d
+  metadata.gz: dba1ad1a2b6512520a88ae0731e73b8d0c482d101cc54bd982a76bda45248aecd7492cc9ceb626cc2f9a77c1efa34878f354b94ea881ec4ce3b81b20551ac79d
+  data.tar.gz: b61ac263261cd384466f9ae7f6e31de566655b21de48ba6d25f3c5c1d02c2f87bf4d5726fc3195fc2a75ba990796b165d3fcae1a87f774f3df902e648249c068

data/.gitignore

@@ -21,5 +21,6 @@ config/initializers/secret_token.rb
 .DS_Store
 *.swp
 /test/dummy/log/*
+/test/dummy/db/*.sqlite3
 Gemfile.lock
 tags

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+### 0.11.0 - 2015-04-13
+Other
+- Split resources into controllers and service objects (https://github.com/varvet/godmin/pull/79)
+- Renames the following modules:
+  - Godmin::Application -> Godmin::ApplicationController
+  - Godmin::Resource -> Godmin::Resources::ResourceController
+  - Godmin::Sessions -> Godmin::SessionsController
+
 ### 0.10.3 - 2015-02-18
 Bug fixes
 - Adds the possibility to pass options to the `date_field` and `datetime_field` form helpers

data/README.md

@@ -11,17 +11,17 @@ Godmin is an admin framework for Rails 4+.
 	- [Engine installation](#engine-installation)
 	- [Installation artefacts](#installation-artefacts)
 - [Getting started](#getting-started)
-- [Controllers](#controllers)
+- [Resources](#resources)
 	- [Scopes](#scopes)
 	- [Filters](#filters)
 	- [Batch actions](#batch-actions)
-	- [Resource fetching](#resource-fetching)
+	- [Resource fetching, building and saving](#resource-fetching-building-and-saving)
 	- [Redirecting](#redirecting)
 	- [Pagination](#pagination)
 - [Views](#views)
   - [Forms](#forms)
 - [Authentication](#authentication)
-	- [Simple authentication](#simple-authentication)
+	- [Built in authentication](#built-in-authentication)
 	- [Shared authentication](#shared-authentication)
 - [Authorization](#authorization)
 - [Localization](#localization)
@@ -45,7 +45,7 @@ Add the gem to the application's `Gemfile`:
 gem "godmin"
 ```
 
-Bundle then run the install generator:
+Bundle, then run the install generator:
 ```sh
 $ bundle install
 $ bin/rails generate godmin:install
@@ -76,7 +76,7 @@ Add the gem to the engine's gemspec, `admin/admin.gemspec`:
 s.add_dependency "godmin", "~> x.x.x"
 ```
 
-Bundle then run the install generator within the scope of the engine, i.e. note the leading `admin/`:
+Bundle, then run the install generator within the scope of the engine, i.e. note the leading `admin/`:
 ```sh
 $ bundle install
 $ admin/bin/rails generate godmin:install
@@ -105,12 +105,12 @@ Rails.application.routes.draw do
 end
 ```
 
-Resource routes placed within the `godmin` block are automatically added to the default navigation, and set up to work with batch actions. More on this in later sections.
+Resource routes placed within the `godmin` block are automatically added to the default navigation.
 
 The application controller is modified as such:
 ```ruby
 class ApplicationController < ActionController::Base
-  include Godmin::Application
+  include Godmin::ApplicationController
 end
 ```
 
@@ -135,7 +135,7 @@ $ admin/bin/rails generate godmin:resource article title published
 
 This does a number of things.
 
-First, it inserts a route in the `config/routes.rb` file:
+It inserts a route in the `config/routes.rb` file:
 
 ```ruby
 godmin do
@@ -143,43 +143,46 @@ godmin do
 end
 ```
 
-Second, it creates a controller:
+It creates a controller:
 
 ```ruby
 class ArticlesController < ApplicationController
-  include Godmin::Resource
+  include Godmin::Resources::ResourceController
+end
+```
 
-  def attrs_for_index
-    [:title, :published]
-  end
+It creates a service object:
 
-  def attrs_for_form
-    [:title, :published]
-  end
+```ruby
+class ArticleService
+  include Godmin::Resources::ResourceService
+
+  attrs_for_index :title, :published
+  attrs_for_form :title, :published
 end
 ```
 
 Using `attrs_for_index` we can control what fields are displayed in the table listing, and using `attrs_for_form` we can control what fields are available in the new and edit forms. We can, for instance, add the `body` field to `attrs_for_form` to make it appear in forms:
 
 ```ruby
-def attrs_for_form
-  [:title, :body, :published]
-end
+attrs_for_form :title, :body, :published
 ```
 
 By now we have a basic admin interface for managing articles.
 
-## Controllers
+## Resources
+
+As we saw in the example above, resources are divided into controllers and service objects. Actions, redirects, params permitting etc go in the controller while resource fetching, building, sorting, filtering etc go in the service object. This makes the service objects small and easy to test.
 
-We have already seen two controller methods at play: `attrs_for_index` and `attrs_for_form`. We will now look at some additional controller concepts.
+We have already seen two methods at play: `attrs_for_index` and `attrs_for_form`. We will now look at some additional resource concepts.
 
 ### Scopes
 
 Scopes are a way of sectioning resources, useful for quick navigation, and can be created as follows:
 
 ```ruby
-class ArticlesController < ApplicationController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
   scope :unpublished, default: true
   scope :published
@@ -199,8 +202,8 @@ end
 Filters offer great flexibility when it comes to searching for resources, and can be created as follows:
 
 ```ruby
-class ArticlesController < ApplicationController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
   filter :title
 
@@ -229,15 +232,15 @@ filter :category, as: :select, collection: -> { Category.all }, option_text: "ti
 Batch actions can be created as follows:
 
 ```ruby
-class ArticlesController < ApplicationController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
   batch_action :publish
   batch_action :unpublish
   batch_action :destroy, confirm: true
 
   def batch_action_publish(resources)
-    resources.each { |r| r.update_attributes(published: true) }
+    resources.each(&:publish!)
   end
 end
 ```
@@ -249,32 +252,39 @@ batch_action :publish, only: [:unpublished]
 batch_action :unpublish, only: [:published]
 ```
 
-If you wish to implement your own redirect after a batch action, return false afterwards:
+If you wish to implement your own redirect after a batch action, it needs to be implemented in the controller:
 
 ```ruby
-def batch_action_publish(resources)
-  resources.each { |r| r.update_attributes(published: true) }
-  redirect_to articles_path(scope: :published) and return false
+class ArticlesController < ApplicationController
+  include Godmin::Resources::ResourceController
+
+  private
+
+  def redirect_after_batch_action_publish
+    redirect_to articles_path(scope: :published)
+  end
 end
 ```
 
-### Resource fetching
+### Resource fetching, building and saving
 
-Resources are made available to the views through instance variables. The index view can access the resources using `@resources` while show, new and edit can access the single resource using `@resource`.
+Resources are made available to the views through instance variables. The index view can access the resources using `@resources` while show, new and edit can access the single resource using `@resource`. In addition, the resource class is available as `@resource_class` and the service object is available as `@resource_service`.
 
-In order to modify resource fetching and construction, these methods can be overridden per resource controller:
+In order to modify resource fetching and construction, these methods can be overridden per resource service:
 
 - `resource_class`
 - `resources_relation`
 - `resources`
-- `build_resource`
 - `find_resource`
+- `build_resource`
+- `create_resource`
+- `update_resource`
 
-To change the class name of the resource from the default based on the controller name:
+To change the class name of the resource from the default based on the service class name:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
   def resource_class
     FooArticle
@@ -285,11 +295,12 @@ end
 To scope resources, e.g. based on the signed in user:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
+  # The signed in admin user is available to all service objects via the options hash
   def resources_relation
-    admin_user.articles
+    options[:admin_user].articles
   end
 end
 ```
@@ -297,8 +308,8 @@ end
 To add to the resources query, e.g. to change the default order:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
   def resources
     super.order(author: :desc)
@@ -306,28 +317,71 @@ class ArticlesController
 end
 ```
 
+To change the way a resource is fetched for `show`, `edit`, `update` and `destroy` actions:
+
+```ruby
+class ArticleService
+  include Godmin::Resources::ResourceService
+
+  def find_resource(id)
+    resources_relation.find_by(slug: id)
+  end
+end
+```
+
 To change the way a resource is constructed for `new` and `create` actions:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
-  def build_resource(params)
-    article = resources_relation.new(params)
+  def build_resource(_params)
+    article = super
     article.setup_more_things
     article
   end
 end
 ```
 
-To change the way a resource is fetched for `show`, `edit`, `update` and `destroy` actions:
+To change the way a resource is saved in the `create` action:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticleService
+  include Godmin::Resources::ResourceService
 
-  def find_resource(slug)
-    resources_relation.find_by(slug: slug)
+  # This method should return true or false
+  def create_resource(resource)
+    resource.save_in_some_interesting_way
+  end
+end
+```
+
+To change the way a resource is saved in the `update` action:
+
+```ruby
+class ArticleService
+  include Godmin::Resources::ResourceService
+
+  # This method should return true or false
+  def update_resource(resource, params)
+    resource.assign_attributes(params)
+    resource.save_in_some_interesting_way
+  end
+end
+```
+
+#### Strong parameters
+
+When using `attrs_for_form`, parameters are automatically permitted. If building a custom form, see the [forms](#forms) section, parameters can be permitted by overriding the `resource_params` method in the controller:
+
+```ruby
+class ArticlesController < ApplicationController
+  include Godmin::Resources::ResourceController
+
+  private
+
+  def resource_params
+    params.require(:article).permit(:title, :body)
   end
 end
 ```
@@ -339,8 +393,10 @@ By default the user is redirected to the resource show page after create and upd
 For instance, to have the article controller redirect to the index page after both create and update:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticlesController < ApplicationController
+  include Godmin::Resources::ResourceController
+
+  private
 
   def redirect_after_save
     articles_path
@@ -351,8 +407,10 @@ end
 Or, to have the article controller redirect to the index page after create and the edit page after update:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticlesController < ApplicationController
+  include Godmin::Resources::ResourceController
+
+  private
 
   def redirect_after_create
     articles_path
@@ -368,9 +426,9 @@ If you wish to change the behaviour for every resource controller, consider crea
 
 ```ruby
 class ResourceController < ApplicationController
-  include Godmin::Resource
+  include Godmin::Resources::ResourceController
 
-  protected
+  private
 
   def redirect_after_save
     resource_class.model_name.route_key.to_sym
@@ -380,13 +438,13 @@ end
 
 ### Pagination
 
-If you wish to change the number of resources per page, you can override the `per_page` class method in the controller:
+If you wish to change the number of resources per page, you can override the `per_page` method in the service object:
 
 ```ruby
-class ArticlesController
-  include Godmin::Resource
+class ArticlesService
+  include Godmin::Resources::Service
 
-  def self.per_page
+  def per_page
     50
   end
 end
@@ -463,7 +521,7 @@ Along with a sessions controller:
 
 ```ruby
 class SessionsController < ApplicationController
-  include Godmin::Authentication::Sessions
+  include Godmin::Authentication::SessionsController
 end
 ```
 
@@ -471,7 +529,7 @@ Finally, the application controller is modified:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  include Godmin::Application
+  include Godmin::ApplicationController
   include Godmin::Authentication
 
   def admin_user_class
@@ -491,7 +549,7 @@ There is no need to run a generator in this instance. Simply add the authenticat
 ```ruby
 module Admin
   class ApplicationController < ActionController::Base
-    include Godmin::Application
+    include Godmin::ApplicationController
     include Godmin::Authentication
   end
 end
@@ -502,7 +560,7 @@ Provided you have `User` model set up with Devise in the main application, overr
 ```ruby
 module Admin
   class ApplicationController < ActionController::Base
-    include Godmin::Application
+    include Godmin::ApplicationController
     include Godmin::Authentication
 
     def authenticate_admin_user
@@ -530,7 +588,7 @@ Add the authorization module to the application controller:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  include Godmin::Application
+  include Godmin::ApplicationController
   include Godmin::Authentication
   include Godmin::Authorization
 
@@ -583,27 +641,33 @@ When a user is not authorized to access a resource, a `NotAuthorizedError` is ra
 If you want to change this behaviour you can rescue the error yourself in the appropriate `ApplicationController`:
 
 ```ruby
-module Admin
-  class ApplicationController < ActionController::Base
-    include Godmin::Application
-    include Godmin::Authentication
-    include Godmin::Authorization
+class ApplicationController < ActionController::Base
+  include Godmin::ApplicationController
+  include Godmin::Authentication
+  include Godmin::Authorization
 
-    # Renders 404 page and returns status code 404.
-    rescue_from NotAuthorizedError do
-      render file: "#{Rails.root}/public/404.html", status: 404, layout: false
-    end
+  # Renders 404 page and returns status code 404.
+  rescue_from NotAuthorizedError do
+    render file: "#{Rails.root}/public/404.html", status: 404, layout: false
   end
 end
 ```
 
-## Localization
+If you wish to specify what policy to use manually, override the following method in your model. It does not have to be an ActiveRecord object, but any object will do.
 
-Godmin supports localization out of the box. Strings can be translated both globally and per resource, similar to how views work.
+```ruby
+class Article
+  def policy_class(_record)
+    FooArticlePolicy
+  end
+end
+```
+
+## Localization
 
-For a list of translatable strings, [look here](https://github.com/varvet/godmin/blob/master/config/locales/en.yml).
+Godmin supports localization out of the box. For a list of translatable strings, [look here](https://github.com/varvet/godmin/blob/master/config/locales/en.yml).
 
-For instance, to translate the `godmin.batch_actions.buttons.select_all` string globally:
+Strings can be translated both globally and per resource, similar to how views work. For instance, to translate the `godmin.batch_actions.buttons.select_all` string globally:
 
 ```yml
 godmin:
@@ -711,6 +775,7 @@ Some additional features are available as plugins:
 
 - [Godmin Uploads](https://github.com/varvet/godmin-uploads)
 - [Godmin Tags](https://github.com/varvet/godmin-tags)
+- [Godmin Redactor](https://github.com/varvet/godmin-redactor)
 
 ## Contributors