activeadmin 0.6.6 → 1.0.0.pre1

data/docs/14-gotchas.md

@@ -0,0 +1,92 @@
+#Gotchas
+
+## 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 
+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)
+
+## Helpers
+
+There are two knowing gotchas with helpers. This hopefully will help you to
+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.
+
+### 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.
+
+#### Solutions
+
+##### First use a monkey patch
+
+This works for all ActiveAdmin resources at once.
+
+```ruby
+# config/initializers/active_admin_helpers.rb
+ActiveAdmin::BaseController.class_eval do
+  helper ApplicationHelper
+end
+```
+
+##### Second use the `controller` method
+
+This works only for one resource at a time.
+
+```ruby
+ActiveAdmin.register User do
+  controller do
+    helper UserHelper
+  end
+end
+```
+
+## CSS
+
+In order to avoid the override of your application style with the Active Admin one, you can do one of this things:
+* You can properly move the generated file `active_admin.css.scss` from `app/assets/stylesheets` to `vendor/assets/stylesheets`.
+* You can remove all `require_tree` comands from your root level css files, where the `active_admin.css.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 
+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 
+listed below.
+
+#### `tire`, `retire` and `elasticsearch-rails`
+
+This conflict can be solved, by using explicitly the `search` method of `tire`, 
+`retire` or `elasticsearch-rails`:
+
+##### For `tire` and `retire`
+
+```ruby
+YourModel.tire.search
+```
+
+##### For `elasticsearch-rails`
+
+```ruby
+YourModel.__elasticsearch__.search
+```
+
+### Sunspot Solr
+
+```ruby
+YourModel.solr_search
+```
+

data/docs/2-resource-customization.md

@@ -1,147 +1,258 @@
-# Customize The Resource
+# Working with Resources
+
+Every Active Admin resource corresponds to a Rails model. So before creating a
+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:
+
+```ruby
+ActiveAdmin.register Post do
+  # everything happens here :D
+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
+ActiveAdmin.register Post do
+  permit_params :title, :content, :publisher_id
+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`:
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params :title, :content, :publisher_id, roles: []
+end
+```
+
+Nested associations in the same form also require an array, but it
+needs to be filled with any attributes used.
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params :title, :content, :publisher_id,
+    tags_attributes: [:id, :name, :description, :_destroy]
+end
+
+# Note that `accepts_nested_attributes_for` is still required:
+class Post < ActiveRecord::Base
+  accepts_nested_attributes_for :tags, allow_destroy: true
+end
+```
+
+If you want to dynamically choose which attributes can be set, pass a block:
+
+```ruby
+ActiveAdmin.register Post do
+  permit_params do
+    params = [:title, :content, :publisher_id]
+    params.push :author_id if current_user.admin?
+    params
+  end
+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
+  controller do
+    def create
+      # Good
+      @post = Post.new(permitted_params[:post])
+      # Bad
+      @post = Post.new(params[:post])
+
+      if @post.save
+        # ...
+      end
+    end
+  end
+end
+```
+
+## Disabling Actions on a Resource
+
+All CRUD actions are enabled by default. These can be disabled for a given resource:
+
+```ruby
+ActiveAdmin.register Post do
+  actions :all, except: [:update, :destroy]
+end
+```
 
 ## Rename the Resource
 
 By default, any references to the resource (menu, routes, buttons, etc) in the
 interface will use the name of the class. You can rename the resource by using
-the <tt>:as</tt> option.
+the `:as` option.
 
-    ActiveAdmin.register Post, :as => "Article"
+```ruby
+ActiveAdmin.register Post, as: "Article"
+```
 
-The resource will then be available as /admin/articles
+The resource will then be available at `/admin/articles`.
 
 ## Customize the Namespace
 
-By default, resources live in the "admin" namespace.
-
-You can register resources in different namespaces:
-
-    # Available at /today/posts
-    ActiveAdmin.register Post, :namespace => "today"
+We use the `admin` namespace by default, but you can use anything:
 
-    # Available at /posts
-    ActiveAdmin.register Post, :namespace => false
+```ruby
+# Available at /today/posts
+ActiveAdmin.register Post, namespace: :today
 
+# Available at /posts
+ActiveAdmin.register Post, namespace: false
+```
 
 ## Customize the Menu
 
 The resource will be displayed in the global navigation by default. To disable
-the resource from being displayed in the global navigation, pass `false` to the
-`menu` method:
+the resource from being displayed in the global navigation:
 
-    ActiveAdmin.register Post do
-      menu false
-    end
+```ruby
+ActiveAdmin.register Post do
+  menu false
+end
+```
 
 The menu method accepts a hash with the following options:
 
 * `:label` - The string or proc label to display in the menu. If it's a proc, it
   will be called each time the menu is rendered.
-* `:parent` - The string label of the parent to set for this menu
+* `:parent` - The string id (or label) of the parent used for this menu
 * `:if` - A block or a symbol of a method to call to decide if the menu item
   should be displayed
-* `:priority` - The integer value of the priority. Defaults to 10
+* `:priority` - The integer value of the priority, which defaults to `10`
 
 ### Labels
 
 To change the name of the label in the menu:
 
-    ActiveAdmin.register Post do
-      menu :label => "My Posts"
-    end
-
-By default the menu uses a pluralized version of your resource name.
+```ruby
+ActiveAdmin.register Post do
+  menu label: "My Posts"
+end
+```
 
-If you wish to translate your label at runtime, store the label as a proc
-instead of a string. The proc will be called each time the menu is rendered.
+If you want something more dynamic, pass a proc instead:
 
-    ActiveAdmin.register Post do
-      menu :label => proc{ I18n.t("mypost") }
-    end
+```ruby
+ActiveAdmin.register Post do
+  menu label: proc{ I18n.t "mypost" }
+end
+```
 
 ### Menu Priority
 
-By default Active Admin sorts menus alphabetically. Some times you want specific
-resources to show up at the beginning or the end of your menu.
+Menu items are sorted first by their numeric priority, then alphabetically. Since
+every menu by default has a priority of `10`, the menu is normally alphabetical.
 
-Each menu item is given an integer priority value (default 10). You can set it
-to edit the location of the menu item.
+You can easily customize this:
 
-    ActiveAdmin.register Post do
-      menu :priority => 1
-    end
-
-This would ensure that the Post menu item, is at the beginning of the menu.
+```ruby
+ActiveAdmin.register Post do
+  menu priority: 1 # so it's on the very left
+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? }
+end
+```
 
-    ActiveAdmin.register Post do
-      menu :if => proc{ current_admin_user.can_edit_posts? }
-    end
-
-The `proc` will be called in the context of the view, so you have access to all
+The proc will be called in the context of the view, so you have access to all
 your helpers and current user session information.
 
 ### Drop Down Menus
 
-In many cases, a single level navigation will not be enough for the
-administration of a production application. In that case, you can categorize
-your resources and creating drop down menus to access them.
-
-To add the menu as a child of another menu:
+In many cases, a single level navigation will not be enough to manage a large
+application. In that case, you can group your menu items under a parent menu item.
 
-    ActiveAdmin.register Post do
-      menu :parent => "Blog"
-    end
+```ruby
+ActiveAdmin.register Post do
+  menu parent: "Blog"
+end
+```
 
-Note, the "Blog" menu does not even have to exist yet. It will be generated on
-the fly as a drop down list for you.
+Note that the "Blog" parent menu item doesn't even have to exist yet; it can be
+dynamically generated for you.
 
 ### Customizing Parent Menu Items
 
-All of the options given to a standard menu item are also available to the
-parent menu items. You can customize their attributes in the Active Admin
-initializer.
-
-    # config/initializers/active_admin.rb
-    ActiveAdmin.setup do |config|
-      config.namespace :admin do |admin|
-
-        # This block will edit the default menu
-        admin.build_menu do |menu|
-          menu.add :label => "Blog", :priority => 0
-        end
-
-      end
-    end
-
-Now, if you use `menu :parent => "Blog"`, your resource menu item will be a
-child of the Blog menu item with the priority of 0.
+All of the options given to a standard menu item are also available to
+parent menu items. In the case of complex parent menu items, you should
+configure them in the Active Admin initializer.
+
+```ruby
+# config/initializers/active_admin.rb
+config.namespace :admin do |admin|
+  admin.build_menu do |menu|
+    menu.add label: 'Blog', priority: 0
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  menu parent: 'Blog'
+end
+```
+
+### Dynamic Parent Menu Items
+
+While the above works fine, what if you want a parent menu item with a dynamic
+name? Well, you have to refer to it by its `:id`.
+
+```ruby
+# config/initializers/active_admin.rb
+config.namespace :admin do |admin|
+  admin.build_menu do |menu|
+    menu.add id: 'blog', label: proc{"Something dynamic"}, priority: 0
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  menu parent: 'blog'
+end
+```
 
 ### Adding Custom Menu Items
 
 Sometimes it's not enough to just customize the menu label. In this case, you
 can customize the menu for the namespace within the Active Admin initializer.
 
-    # config/initializers/active_admin.rb
-    ActiveAdmin.setup do |config|
-      config.namespace :admin do |admin|
-        admin.build_menu do |menu|
-          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"
-          end
-        end
-      end
+```ruby
+# config/initializers/active_admin.rb
+config.namespace :admin do |admin|
+  admin.build_menu do |menu|
+    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"
     end
+  end
+end
+```
 
-This block will be run once on application startup to build the menu before each
-of the resources are added to it.
+This will be registered on application start before your resources are loaded.
 
 ## Scoping the queries
 
@@ -149,77 +260,68 @@ If your administrators have different access levels, you may sometimes want to
 scope what they have access to. Assuming your User model has the proper
 has_many relationships, you can simply scope the listings and finders like so:
 
-    ActiveAdmin.register Post do
-      scope_to :current_user
+```ruby
+ActiveAdmin.register Post do
+  scope_to :current_user # limits the accessible posts to `current_user.posts`
 
-      # or if the association doesn't have the default name.
-      # scope_to :current_user, :association_method => :blog_posts
-    end
+  # Or if the association doesn't have the default name:
+  scope_to :current_user, association_method: :blog_posts
 
-That approach limits the posts an admin can access to ```current_user.posts```.
+  # Finally, you can pass a block to be called:
+  scope_to do
+    User.most_popular_posts
+  end
+end
+```
 
-If you want to conditionally apply the scope, then there are options for that as well:
+You can also conditionally apply the scope:
 
-    ActiveAdmin.register Post do
-      # Only scope the query if there is a user to scope to, helper provided via Devise
-      scope_to :current_user, :if => proc{ admin_user_signed_in? }
+```ruby
+ActiveAdmin.register Post do
+  scope_to :current_user, if:     proc{ current_user.limited_access? }
+  scope_to :current_user, unless: proc{ current_user.admin? }
+end
+```
 
-      # Don't scope the query if the user is an admin
-      scope_to :current_user, :unless => proc{ current_admin_user.admin? }
+## Eager loading
 
-      # Get fancy and can combine with block syntax
-      scope_to :if => proc{ admin_user_signed_in? } do
-        User.most_popular
-      end
-    end
-
-If you want to do something fancier, for example override a default scope, you can
-also use :association_method parameter with a normal method on your User model.
-The only requirement is that your method returns an instance of ActiveRecord::Relation.
+A common way to increase page performance is to elimate N+1 queries by eager loading associations:
 
-    class Ad < ActiveRecord::Base
-      default_scope lambda { where :published => true }
-    end
+```ruby
+ActiveAdmin.register Post do
+  includes :author, :categories
+end
+```
 
-    class User < ActiveRecord::Base
-      def managed_ads
-        # Overrides Ad's default_scope
-        Ad.unscoped
-      end
-    end
-
-    ActiveAdmin.register Ad do
-      scope_to :current_user, :association_method => :managed_ads
-    end
+## Customizing resource retrieval
 
-In case you just need to customize the query independently of the current user, you can
-override the `scoped_collection` method on the controller:
+If you need to customize the collection properties, you can overwrite the `scoped_collection` method.
 
-    ActiveAdmin.register Post do
-      controller do
-        def scoped_collection
-          Post.includes(:author)
-        end
-      end
+```ruby
+ActiveAdmin.register Post do
+  controller do
+    def scoped_collection
+      end_of_association_chain.where(visibility: true)
     end
-
-## Customizing resource retrieval
+  end
+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:
 
-    ActiveAdmin.register Post do
-      controller do
-        def resource
-          Post.where(id: params[:id]).first!
-        end
-      end
+```ruby
+ActiveAdmin.register Post do
+  controller do
+    def find_resource
+      Post.where(id: params[:id]).first!
     end
+  end
+end
+```
 
-In fact, the controllers use [Inherited Resource](https://github.com/josevalim/inherited_resources),
-so you can use all the
-[customization features in Inherited Resource](https://github.com/josevalim/inherited_resources#overwriting-defaults).
-
+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).
 
 ## Belongs To
 
@@ -227,66 +329,79 @@ It's common to want to scope a series of resources to a relationship. For
 example a Project may have many Milestones and Tickets. To nest the resource
 within another, you can use the `belongs_to` method:
 
-    ActiveAdmin.register Project do
-    end
-
-    ActiveAdmin.register Ticket do
-      belongs_to :project
-    end
+```ruby
+ActiveAdmin.register Project
+ActiveAdmin.register Ticket do
+  belongs_to :project
+end
+```
 
 Projects will be available as usual and tickets will be availble by visiting
-"/admin/projects/1/tickets" assuming that a Project with the id of 1 exists.
+`/admin/projects/1/tickets` assuming that a Project with the id of 1 exists.
 Active Admin does not add "Tickets" to the global navigation because the routes
 can only be generated when there is a project id.
 
 To create links to the resource, you can add them to a sidebar (one of the many
 possibilities for how you may with to handle your user interface):
 
-    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))
-        end
-      end
+```ruby
+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)
     end
+  end
+end
 
-    ActiveAdmin.register Ticket do
-      belongs_to :project
-    end
-
-    ActiveAdmin.register Milestone do
-      belongs_to :project
-    end
+ActiveAdmin.register Ticket do
+  belongs_to :project
+end
 
+ActiveAdmin.register Milestone do
+  belongs_to :project
+end
+```
 
 In some cases (like Projects), there are many sub resources and you would
 actually like the global navigation to switch when the user navigates "into" a
 project. To accomplish this, Active Admin stores the `belongs_to` resources in a
 seperate menu which you can use if you so wish. To use:
 
-    ActiveAdmin.register Ticket do
-      belongs_to :project
-      navigation_menu :project
-    end
+```ruby
+ActiveAdmin.register Ticket do
+  belongs_to :project
+  navigation_menu :project
+end
 
-    ActiveAdmin.register Milestone do
-      belongs_to :project
-      navigation_menu :project
-    end
+ActiveAdmin.register Milestone do
+  belongs_to :project
+  navigation_menu :project
+end
+```
 
 Now, when you navigate to the tickets section, the global navigation will
 only display "Tickets" and "Milestones". When you navigate back to a
 non-belongs_to resource, it will switch back to the default menu.
 
 You can also defer the menu lookup until runtime so that you can dynamically show
-different menus, say perhaps on user permissions or level.  For example:
-
-    ActiveAdmin.register Ticket do
-      belongs_to: :project
-      navigation_menu do
-        authorized?(:manage, SomeResource) ? :project : :restricted_menu
-      end
-    end
+different menus, say perhaps based on user permissions. For example:
+
+```ruby
+ActiveAdmin.register Ticket do
+  belongs_to :project
+  navigation_menu do
+    authorized?(:manage, SomeResource) ? :project : :restricted_menu
+  end
+end
+```
+
+If you still want your `belongs_to` resources to be available in the default menu
+and through non-nested routes, you can use the `:optional` option. For example:
+
+```ruby
+ActiveAdmin.register Ticket do
+  belongs_to :project, optional: true
+end
+```