activeadmin 1.0.0.pre4 → 2.4.0

data/docs/13-authorization-adapter.md

@@ -1,3 +1,7 @@
+---
+redirect_from: /docs/13-authorization-adapter.html
+---
+
 # Authorization Adapter
 
 Active Admin offers the ability to define and use your own authorization
@@ -6,8 +10,8 @@ taken. By default, '#authorized?' returns true.
 
 ## Setting up your own AuthorizationAdapter
 
-Setting up your own `AuthorizationAdapter` is easy! The following example shows
-how to set up and tie your authorization adapter class to Active Admin:
+The following example shows how to set up and tie your authorization
+adapter class to Active Admin:
 
 ```ruby
 # app/models/only_authors_authorization.rb
@@ -37,7 +41,11 @@ application's `config/initializers/active_admin.rb` and add/modify the line:
 config.authorization_adapter = "OnlyAuthorsAuthorization"
 ```
 
-Authorization adapters can be configured per ActiveAdmin namespace as well, for example:
+Now, whenever a controller action is performed, the `OnlyAuthorsAuthorization`'s
+`#authorized?` method will be called.
+
+Authorization adapters can be configured per ActiveAdmin namespace as well, for
+example:
 
 ```ruby
 ActiveAdmin.setup do |config|
@@ -50,9 +58,6 @@ ActiveAdmin.setup do |config|
 end
 ```
 
-Now, whenever a controller action is performed, the `OnlyAuthorsAuthorization`'s
-`#authorized?` method will be called.
-
 ## Getting Access to the Current User
 
 From within your authorization adapter, you can call the `#user` method to
@@ -70,9 +75,9 @@ end
 
 ## Scoping Collections in Authorization Adapters
 
-`ActiveAdmin::AuthorizationAdapter` also provides a hook method (`#scope_collection`)
-for the adapter to scope the resource's collection. For example, you may want to
-centralize the scoping:
+`ActiveAdmin::AuthorizationAdapter` also provides a hook method
+(`#scope_collection`) for the adapter to scope the resource's collection. For
+example, you may want to centralize the scoping:
 
 ```ruby
 class OnlyMyAccount < ActiveAdmin::AuthorizationAdapter
@@ -101,7 +106,9 @@ class OnlyDashboard < ActiveAdmin::AuthorizationAdapter
   def authorized?(action, subject = nil)
     case subject
     when ActiveAdmin::Page
-      action == :read && subject.name == "Dashboard" && subject.namespace.name == :admin
+      action == :read &&
+        subject.name == "Dashboard" &&
+        subject.namespace.name == :admin
     else
       false
     end
@@ -113,24 +120,23 @@ end
 
 By default Active Admin simplifies the controller actions into 4 actions:
 
-  * `:read` - This controls if the user can view the menu item as well as the
-    index and show screens.
-  * `:create` - This controls if the user can view the new screen and submit
-    the form to the create action.
-  * `:update` - This controls if the user can view the edit screen and submit
-    the form to the update action.
-  * `:destroy` - This controls if the user can delete a resource.
+* `:read` - This controls if the user can view the menu item as well as the
+  index and show screens.
+* `:create` - This controls if the user can view the new screen and submit
+  the form to the create action.
+* `:update` - This controls if the user can view the edit screen and submit
+  the form to the update action.
+* `:destroy` - This controls if the user can delete a resource.
 
 Each of these actions is available as a constant. Eg: `:read` is available as
 `ActiveAdmin::Authorization::READ`.
 
-
 ## Checking for Authorization in Controllers and Views
 
 Active Admin provides a helper method to check if the current user is
 authorized to perform an action on a subject.
 
-Simply use the `#authorized?(action, subject) method to check.
+Use the `#authorized?(action, subject)` method to check.
 
 ```ruby
 ActiveAdmin.register Post do
@@ -174,28 +180,28 @@ end
 
 Sub-classing `ActiveAdmin::AuthorizationAdapter` is fairly low level. Many times
 it's nicer to have a simpler DSL for managing authorization. Active Admin
-provides an adapter out of the box for [CanCan](https://github.com/ryanb/cancan)
-and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
+provides an adapter out of the box for [CanCanCan](https://github.com/CanCanCommunity/cancancan).
 
-To use the CanCan adapter, simply update the configuration in the Active Admin
+To use the CanCan adapter, update the configuration in the Active Admin
 initializer:
 
 ```ruby
 config.authorization_adapter = ActiveAdmin::CanCanAdapter
 ```
 
-You can also specify a method to be called on unauthorized access. This is necessary
-in order to prevent a redirect loop that can happen if a user tries to access a page
-they don't have permissions for (see [#2081](https://github.com/activeadmin/activeadmin/issues/2081)).
+You can also specify a method to be called on unauthorized access. This is
+necessary in order to prevent a redirect loop that can happen if a user tries to
+access a page they don't have permissions for (see
+[#2081](https://github.com/activeadmin/activeadmin/issues/2081)).
 
 ```ruby
 config.on_unauthorized_access = :access_denied
 ```
 
-The method `access_denied` would be defined in `application_controller.rb`. Here is one
-example that redirects the user from the page they don't have permission to
-access to a resource they have permission to access (organizations in this case), and
-also displays the error message in the browser:
+The method `access_denied` would be defined in `application_controller.rb`. Here
+is one example that redirects the user from the page they don't have permission
+to access to a resource they have permission to access (organizations in this
+case), and also displays the error message in the browser:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -214,7 +220,7 @@ changed from the initializer:
 config.cancan_ability_class = "MyCustomAbility"
 ```
 
-Now you can simply use CanCan or CanCanCan the way that you would expect and
+Now you can simply use CanCanCan the way that you would expect and
 Active Admin will use it for authorization:
 
 ```ruby
@@ -226,23 +232,54 @@ class Ability
     can :manage, Post
     can :read, User
     can :manage, User, id: user.id
-    can :read, ActiveAdmin::Page, name: "Dashboard", namespace_name: :admin
+    can :read, ActiveAdmin::Page, name: "Dashboard", namespace_name: "admin"
   end
 
 end
 ```
 
-To view more details about the API's, visit project pages of [CanCan](https://github.com/ryanb/cancan) and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
+To view more details about the API's, visit project pages of
+[CanCanCan](https://github.com/CanCanCommunity/cancancan).
 
 ## Using the Pundit Adapter
 
-Active Admin provides an adapter out of the box also for [Pundit](https://github.com/elabs/pundit).
+Active Admin also provides an adapter out of the box for
+[Pundit](https://github.com/varvet/pundit).
 
-To use the Pundit adapter, simply update the configuration in the Active Admin
+To use the Pundit adapter, update the configuration in the Active Admin
 initializer:
 
 ```ruby
 config.authorization_adapter = ActiveAdmin::PunditAdapter
 ```
 
-You can simply use Pundit the way that you would expect and Active Admin will use it for authorization. Check Pundit's documentation to [set up Pundit in your application](https://github.com/elabs/pundit#installation). If you want to use batch actions just ensure that `destroy_all?` method is defined in your policy class. You can use this [template policy](https://github.com/activeadmin/activeadmin/blob/master/spec/support/templates/policies/application_policy.rb) in your application instead of default one generated by Pundit's `rails g pundit:install` command.
+Once that's done, Active Admin will pick up your Pundit policies, and use
+them for authorization. For more information about setting up Pundit, see
+[their documentation](https://github.com/varvet/pundit#installation).
+
+Pundit also has [verify_authorized and/or verify_policy_scoped
+methods](https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used)
+to enforce usage of `authorized` and `policy_scope`. This conflicts with Active
+Admin's authorization architecture, so if you're using those features, you'll
+want to disable them for Active Admin's controllers:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Pundit
+  after_action :verify_authorized, except: :index, unless: :active_admin_controller?
+  after_action :verify_policy_scoped, only: :index, unless: :active_admin_controller?
+
+  def active_admin_controller?
+    is_a?(ActiveAdmin::BaseController)
+  end
+end
+```
+
+If you want to use batch actions, ensure that `destroy_all?` method is defined
+in your policy class. You can use this [template
+policy](https://github.com/activeadmin/activeadmin/blob/master/spec/support/templates/policies/application_policy.rb)
+in your application instead of default one generated by Pundit's
+`rails g pundit:install` command.
+
+In addition, there are [example policies](https://github.com/activeadmin/activeadmin/tree/master/spec/support/templates/policies/active_admin)
+for restricting access to ActiveAdmin's pages and comments.

data/docs/14-gotchas.md

@@ -1,21 +1,29 @@
-#Gotchas
+---
+redirect_from: /docs/14-gotchas.html
+---
+
+# Gotchas
 
 ## Security
 
 ### Spreadsheet applications vulnerable to unescaped CSV data
 
-If your CSV export includes untrusted data provided by your users, it's possible that they could include an executable formula that could call arbitrary commands on your computer. See [#4256](https://github.com/activeadmin/activeadmin/issues/4256) for more details.
+If your CSV export includes untrusted data provided by your users, it's possible
+that they could include an executable formula that could call arbitrary commands
+on your computer. See
+[#4256](https://github.com/activeadmin/activeadmin/issues/4256) for more
+details.
 
 ## Session Commits & Asset Pipeline
 
-When configuring the asset pipeline ensure that the asset prefix 
-(`config.assets.prefix`) is not the same as the namespace of ActiveAdmin 
-(default namespace is `/admin`). If they are the same Sprockets will prevent the 
-session from being committed. Flash messages won't work and you will be unable to 
+When configuring the asset pipeline ensure that the asset prefix
+(`config.assets.prefix`) is not the same as the namespace of ActiveAdmin
+(default namespace is `/admin`). If they are the same Sprockets will prevent the
+session from being committed. Flash messages won't work and you will be unable to
 use the session for storing anything.
 
-For more information see the following post: 
-[http://www.intridea.com/blog/2013/3/20/rails-assets-prefix-may-disable-your-session](http://www.intridea.com/blog/2013/3/20/rails-assets-prefix-may-disable-your-session)
+For more information see [the following
+post](http://www.intridea.com/blog/2013/3/20/rails-assets-prefix-may-disable-your-session).
 
 ## Helpers
 
@@ -24,13 +32,14 @@ find a solution.
 
 ### Helpers are not reloading in development
 
-This is a known and still open [issue](https://github.com/activeadmin/activeadmin/issues/697)
-the only way is to restart your server each time you change a helper.
+This is a known and still open
+[issue](https://github.com/activeadmin/activeadmin/issues/697) the only way is
+to restart your server each time you change a helper.
 
 ### Helper maybe not included by default
 
-If you use `config.action_controller.include_all_helpers = false` in your application config, 
-you need to include it by hand.
+If you use `config.action_controller.include_all_helpers = false` in your
+application config, you need to include it by hand.
 
 #### Solutions
 
@@ -59,23 +68,27 @@ end
 
 ## CSS
 
-In order to avoid the override of your application style with the Active Admin one, you can do one of these things:
-* You can properly move the generated file `active_admin.scss` from `app/assets/stylesheets` to `vendor/assets/stylesheets`.
-* You can remove all `require_tree` commands from your root level css files, where the `active_admin.scss` is in the tree.
+In order to avoid the override of your application style with the Active Admin
+one, you can do one of these things:
+
+* You can properly move the generated file `active_admin.scss` from
+  `app/assets/stylesheets` to `vendor/assets/stylesheets`.
+* You can remove all `require_tree` commands from your root level css files,
+  where the `active_admin.scss` is in the tree.
 
 ## Conflicts
 
 ### With gems that provides a `search` class method on a model
 
-If a gem defines a `search` class method on a model, this can result in conflicts 
+If a gem defines a `search` class method on a model, this can result in conflicts
 with the same method provided by `ransack` (a dependency of ActiveAdmin).
 
-Each of this conflicts need to solved is a different way. Some solutions are 
+Each of this conflicts need to solved is a different way. Some solutions are
 listed below.
 
 #### `tire`, `retire` and `elasticsearch-rails`
 
-This conflict can be solved, by using explicitly the `search` method of `tire`, 
+This conflict can be solved, by using explicitly the `search` method of `tire`,
 `retire` or `elasticsearch-rails`:
 
 ##### For `tire` and `retire`
@@ -95,6 +108,31 @@ YourModel.__elasticsearch__.search
 ```ruby
 YourModel.solr_search
 ```
+
+### Rails 5 scaffold generators
+
+Active Admin requires the `inherited_resources` gem which may break scaffolding
+under Rails 5 as it replaces the default scaffold generator. The solution is to
+configure the default controller in `config/application.rb` as outlined in
+[activeadmin/inherited_resources#195](https://github.com/activeadmin/inherited_resources/issues/195)
+
+```ruby
+module SampleApp
+  class Application < Rails::Application
+    ...
+    config.app_generators.scaffold_controller = :scaffold_controller
+    ...
+  end
+end
+```
+
 ## Authentication & Application Controller
 
-The `ActiveAdmin::BaseController` inherits from the `ApplicationController`. Any authentication method(s) specified in the `ApplicationController` callbacks will be called instead of the authentication method in the active admin config file. For example, if the ApplicationController has a callback `before_action :custom_authentication_method` and the config file's authentication method is `config.authentication_method = :authenticate_active_admin_user`, then `custom_authentication_method` will be called instead of `authenticate_active_admin_user`.
+The `ActiveAdmin::BaseController` inherits from the `ApplicationController`. Any
+authentication method(s) specified in the `ApplicationController` callbacks will
+be called instead of the authentication method in the active admin config file.
+For example, if the ApplicationController has a callback `before_action
+:custom_authentication_method` and the config file's authentication method is
+`config.authentication_method = :authenticate_active_admin_user`, then
+`custom_authentication_method` will be called instead of
+`authenticate_active_admin_user`.

data/docs/2-resource-customization.md

@@ -1,3 +1,7 @@
+---
+redirect_from: /docs/2-resource-customization.html
+---
+
 # Working with Resources
 
 Every Active Admin resource corresponds to a Rails model. So before creating a
@@ -6,7 +10,7 @@ resource you must first create a Rails model for it.
 ## Create a Resource
 
 The basic command for creating a resource is `rails g active_admin:resource Post`.
-The generator will produce an empty `app/admin/post.rb` file like so:
+The generator will produce an empty `app/admin/posts.rb` file like so:
 
 ```ruby
 ActiveAdmin.register Post do
@@ -16,9 +20,6 @@ end
 
 ## Setting up Strong Parameters
 
-Rails 4 replaces `attr_accessible` with [Strong Parameters](https://github.com/rails/strong_parameters),
-which moves attribute whitelisting from the model to the controller.
-
 Use the `permit_params` method to define which attributes may be changed:
 
 ```ruby
@@ -27,8 +28,8 @@ ActiveAdmin.register Post do
 end
 ```
 
-Any form field that sends multiple values (such as a HABTM association, or an array attribute)
-needs to pass an empty array to `permit_params`:
+Any form field that sends multiple values (such as a HABTM association, or an
+array attribute) needs to pass an empty array to `permit_params`:
 
 If your HABTM is `roles`, you should permit `role_ids: []`
 
@@ -65,7 +66,17 @@ ActiveAdmin.register Post do
 end
 ```
 
-The `permit_params` call creates a method called `permitted_params`. You should use this method when overriding `create` or `update` actions:
+If your resource is nested, declare `permit_params` after `belongs_to`:
+
+```ruby
+ActiveAdmin.register Post do
+  belongs_to :user
+  permit_params :title, :content, :publisher_id
+end
+```
+
+The `permit_params` call creates a method called `permitted_params`. You should
+use this method when overriding `create` or `update` actions:
 
 ```ruby
 ActiveAdmin.register Post do
@@ -94,6 +105,26 @@ ActiveAdmin.register Post do
 end
 ```
 
+## Renaming Action Items
+
+You can use translations to override labels and page titles for actions such as
+new, edit, and destroy by providing a resource specific translation.  For
+example, to change 'New Offer' to 'Make an Offer' add the following in
+config/locales/[en].yml:
+
+```yaml
+en:
+  active_admin:
+    resources:
+      offer: # Registered resource
+        new_model: 'Make an Offer' # new action item
+        edit_model: 'Change Offer' # edit action item
+        delete_model: 'Cancel Offer' # delete action item
+```
+
+See the [default en.yml](/config/locales/en.yml) locale file for
+existing translations and examples.
+
 ## Rename the Resource
 
 By default, any references to the resource (menu, routes, buttons, etc) in the
@@ -172,6 +203,7 @@ end
 ### Conditionally Showing / Hiding Menu Items
 
 Menu items can be shown or hidden at runtime using the `:if` option.
+
 ```ruby
 ActiveAdmin.register Post do
   menu if: proc{ current_user.can_edit_posts? }
@@ -246,9 +278,15 @@ config.namespace :admin do |admin|
     menu.add label: "The Application", url: "/", priority: 0
 
     menu.add label: "Sites" do |sites|
-      sites.add label: "Google",   url: "http://google.com", html_options: { target: :blank }
-      sites.add label: "Facebook", url: "http://facebook.com"
-      sites.add label: "Github",   url: "http://github.com"
+      sites.add label: "Google",
+                url: "http://google.com",
+                html_options: { target: :blank }
+
+      sites.add label: "Facebook",
+                url: "http://facebook.com"
+
+      sites.add label: "Github",
+                url: "http://github.com"
     end
   end
 end
@@ -287,7 +325,8 @@ end
 
 ## Eager loading
 
-A common way to increase page performance is to elimate N+1 queries by eager loading associations:
+A common way to increase page performance is to eliminate N+1 queries by eager
+loading associations:
 
 ```ruby
 ActiveAdmin.register Post do
@@ -297,10 +336,13 @@ end
 
 ## Customizing resource retrieval
 
-Our controllers are built on [Inherited Resources](https://github.com/josevalim/inherited_resources),
-so you can use [all of its features](https://github.com/josevalim/inherited_resources#overwriting-defaults).
+Our controllers are built on [Inherited
+Resources](https://github.com/activeadmin/inherited_resources), so you can use
+[all of its
+features](https://github.com/activeadmin/inherited_resources#overwriting-defaults).
 
-If you need to customize the collection properties, you can overwrite the `scoped_collection` method.
+If you need to customize the collection properties, you can overwrite the
+`scoped_collection` method.
 
 ```ruby
 ActiveAdmin.register Post do
@@ -312,8 +354,9 @@ ActiveAdmin.register Post do
 end
 ```
 
-If you need to completely replace the record retrieving code (e.g., you have a custom
-`to_param` implementation in your models), override the `resource` method on the controller:
+If you need to completely replace the record retrieving code (e.g., you have a
+custom `to_param` implementation in your models), override the `find_resource` method
+on the controller:
 
 ```ruby
 ActiveAdmin.register Post do
@@ -325,8 +368,9 @@ ActiveAdmin.register Post do
 end
 ```
 
-Note that if you use an authorization library like CanCan, you should be careful to not
-write code like this, otherwise **your authorization rules won't be applied**:
+Note that if you use an authorization library like CanCan, you should be careful
+to not write code like this, otherwise **your authorization rules won't be
+applied**:
 
 ```ruby
 ActiveAdmin.register Post do
@@ -364,8 +408,8 @@ ActiveAdmin.register Project do
 
   sidebar "Project Details", only: [:show, :edit] do
     ul do
-      li link_to "Tickets",    admin_project_tickets_path(project)
-      li link_to "Milestones", admin_project_milestones_path(project)
+      li link_to "Tickets",    admin_project_tickets_path(resource)
+      li link_to "Milestones", admin_project_milestones_path(resource)
     end
   end
 end

data/docs/3-index-pages/custom-index.md

@@ -1,3 +1,7 @@
+---
+redirect_from: /docs/3-index-pages/custom-index.html
+---
+
 # Custom Index
 
 If the supplied Active Admin index components are insufficient for your project
@@ -26,6 +30,6 @@ The build method takes a PagePresenter object and collection of whatever you
 choose.
 
 The `index_name` class method takes no arguments and returns a string that should
-be representative of the the class name. If this method is not defined, your
+be representative of the class name. If this method is not defined, your
 index component will not be able take advantage of Active Admin's
 *multiple index pages* feature.

data/docs/3-index-pages/index-as-block.md

@@ -1,8 +1,6 @@
-<!--
-  WARNING: Please DO NOT edit this file! Update
-  source documentation in lib/active_admin/views
-  and execute rake yard to regenerate it.
--->
+---
+redirect_from: /docs/3-index-pages/index-as-block.html
+---
 
 # Index as a Block
 

data/docs/3-index-pages/index-as-blog.md

@@ -1,8 +1,6 @@
-<!--
-  WARNING: Please DO NOT edit this file! Update
-  source documentation in lib/active_admin/views
-  and execute rake yard to regenerate it.
--->
+---
+redirect_from: /docs/3-index-pages/index-as-blog.html
+---
 
 # Index as Blog
 
@@ -30,7 +28,7 @@ end
 ```
 
 Second, you can pass a block to the tile option which will then be
-used as the contents fo the title. The resource being rendered
+used as the contents of the title. The resource being rendered
 is passed in to the block. For Example:
 
 ```ruby

data/docs/3-index-pages/index-as-grid.md

@@ -1,8 +1,6 @@
-<!--
-  WARNING: Please DO NOT edit this file! Update
-  source documentation in lib/active_admin/views
-  and execute rake yard to regenerate it.
--->
+---
+redirect_from: /docs/3-index-pages/index-as-grid.html
+---
 
 # Index as a Grid
 

data/docs/3-index-pages/index-as-table.md

@@ -1,8 +1,6 @@
-<!--
-  WARNING: Please DO NOT edit this file! Update
-  source documentation in lib/active_admin/views
-  and execute rake yard to regenerate it.
--->
+---
+redirect_from: /docs/3-index-pages/index-as-table.html
+---
 
 # Index as a Table
 
@@ -86,8 +84,6 @@ index do
   column :title
   actions defaults: false do |post|
     item "View", admin_post_path(post)
-    item "Edit", edit_admin_post_path(post)
-    item "Delete", admin_post_path(post), method: :delete
   end
 end
 ```
@@ -115,7 +111,8 @@ index do
 end
 ```
 
-In addition, you can insert the position of the row in the greater collection by using the index_column special command:
+In addition, you can insert the position of the row in the greater
+collection by using the index_column special command:
 
 ```ruby
 index do
@@ -125,7 +122,8 @@ index do
 end
 ```
 
-index_column take an optional offset parameter to allow a developer to set the starting number for the index (default is 1).
+index_column take an optional offset parameter to allow a developer to set
+the starting number for the index (default is 1).
 
 ## Sorting
 
@@ -133,9 +131,7 @@ When a column is generated from an Active Record attribute, the table is
 sortable by default. If you are creating a custom column, you may need to give
 Active Admin a hint for how to sort the table.
 
-If a column is defined using a block, you must pass the key to turn on sorting. The key
-is the attribute which gets used to sort objects using Active Record.
-
+You can pass the key specifying the attribute which gets used to sort objects using Active Record.
 By default, this is the column on the resource's table that the attribute corresponds to.
 Otherwise, any attribute that the resource collection responds to can be used.
 
@@ -164,6 +160,24 @@ index do
 end
 ```
 
+## Custom sorting
+
+It is also possible to use database specific expressions and options for sorting by column
+
+```ruby
+order_by(:title) do |order_clause|
+   if order_clause.order == 'desc'
+     [order_clause.to_sql, 'NULLS LAST'].join(' ')
+   else
+     [order_clause.to_sql, 'NULLS FIRST'].join(' ')
+   end
+end
+
+index do
+  column :title
+end
+```
+
 ## Associated Sorting
 
 You're normally able to sort columns alphabetically, but by default you
@@ -179,6 +193,13 @@ controller do
 end
 ```
 
+You can also define associated objects to include outside of the
+`scoped_collection` method:
+
+```ruby
+includes :publisher
+```
+
 Then it's simple to sort by any Publisher attribute from within the index table:
 
 ```ruby