activeadmin 1.0.0.pre1 → 2.9.0

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,12 +28,14 @@ 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: []`
 
 ```ruby
 ActiveAdmin.register Post do
-  permit_params :title, :content, :publisher_id, roles: []
+  permit_params :title, :content, :publisher_id, role_ids: []
 end
 ```
 
@@ -63,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
@@ -92,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
@@ -131,7 +164,8 @@ 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 id (or label) of the parent used for this menu
+* `:parent` - The string id (or label) of the parent used for this menu, or an array
+  of string ids (or labels) for a nested 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, which defaults to `10`
@@ -170,6 +204,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? }
@@ -193,6 +228,14 @@ end
 Note that the "Blog" parent menu item doesn't even have to exist yet; it can be
 dynamically generated for you.
 
+To further nest an item under a submenu, provide an array of parents.
+
+```ruby
+ActiveAdmin.register Post do
+  menu parent: ["Admin", "Blog"]
+end
+```
+
 ### Customizing Parent Menu Items
 
 All of the options given to a standard menu item are also available to
@@ -244,9 +287,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
@@ -285,7 +334,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
@@ -295,7 +345,13 @@ end
 
 ## Customizing resource retrieval
 
-If you need to customize the collection properties, you can overwrite the `scoped_collection` method.
+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.
 
 ```ruby
 ActiveAdmin.register Post do
@@ -307,21 +363,33 @@ 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
   controller do
     def find_resource
-      Post.where(id: params[:id]).first!
+      scoped_collection.where(id: params[:id]).first!
     end
   end
 end
 ```
 
-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).
+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
+  controller do
+    def find_resource
+      Post.where(id: params[:id]).first!
+    end
+  end
+end
+```
 
 ## Belongs To
 
@@ -336,7 +404,7 @@ ActiveAdmin.register Ticket do
 end
 ```
 
-Projects will be available as usual and tickets will be availble by visiting
+Projects will be available as usual and tickets will be available by visiting
 `/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.
@@ -349,8 +417,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
@@ -367,7 +435,7 @@ 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:
+separate menu which you can use if you so wish. To use:
 
 ```ruby
 ActiveAdmin.register Ticket do

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
 
@@ -55,6 +53,8 @@ index do
 end
 ```
 
+## Defining Actions
+
 To setup links to View, Edit and Delete a resource, use the `actions` method:
 
 ```ruby
@@ -94,7 +94,7 @@ Or append custom action with custom html via arbre:
 index do
   column :title
   actions do |post|
-    a link_to "View", admin_post_path(post)
+    a "View", href: admin_post_path(post)
   end
 end
 ```
@@ -111,15 +111,27 @@ index do
 end
 ```
 
+In addition, you can insert the position of the row in the greater
+collection by using the index_column special command:
+
+```ruby
+index do
+  selectable_column
+  index_column
+  column :title
+end
+```
+
+index_column take an optional offset parameter to allow a developer to set
+the starting number for the index (default is 1).
+
 ## Sorting
 
 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.
 
@@ -148,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
@@ -163,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

data/docs/3-index-pages.md

@@ -1,3 +1,7 @@
+---
+redirect_from: /docs/3-index-pages.html
+---
+
 # Customizing the Index Page
 
 Filtering and listing resources is one of the most important tasks for
@@ -77,7 +81,8 @@ end
 
 Out of the box, Active Admin supports the following filter types:
 
-* *:string* - A search field
+* *:string* -  A drop down for selecting "Contains", "Equals", "Starts with",
+  "Ends with" and an input for a value.
 * *:date_range* - A start and end date field with calendar inputs
 * *:numeric* - A drop down for selecting "Equal To", "Greater Than" or "Less
   Than" and an input for a value.
@@ -100,6 +105,24 @@ the collection as a proc to be called at render time.
 filter :author, as: :check_boxes, collection: proc { Author.all }
 ```
 
+To override options for string or numeric filter pass `filters` option.
+
+```ruby
+  filter :title, filters: [:starts_with, :ends_with]
+```
+
+Also, if you don't need the select with the options 'contains', 'equals',
+'starts_with' or 'ends_with' just add the option to the filter name with an
+underscore.
+
+For example:
+
+```ruby
+filter :name_equals
+# or
+filter :name_contains
+```
+
 You can change the filter label by passing a label option:
 
 ```ruby
@@ -108,9 +131,11 @@ filter :author, label: 'Something else'
 
 By default, Active Admin will try to use ActiveModel I18n to determine the label.
 
-You can also filter on more than one attribute of a model using the
-[Ransack search predicate syntax](https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching). If using a custom search method, you will
-also need to specify the field type using `:as` and the label.
+You can also filter on more than one attribute of a model using the [Ransack
+search predicate
+syntax](https://github.com/activerecord-hackery/ransack/wiki/Basic-Searching).
+If using a custom search method, you will also need to specify the field type
+using `:as` and the label.
 
 ```ruby
 filter :first_name_or_last_name_cont, as: :string, label: "Name"
@@ -152,11 +177,18 @@ preserve_default_filters!
 filter :author
 ```
 
+Or you can also remove a filter and still preserve the default filters:
+
+```ruby
+preserve_default_filters!
+remove_filter :id
+```
+
 ## Index Scopes
 
 You can define custom scopes for your index page. This will add a tab bar above
-the index table to quickly filter your collection on pre-defined scopes. There are
-a number of ways to define your scopes:
+the index table to quickly filter your collection on pre-defined scopes. There
+are a number of ways to define your scopes:
 
 ```ruby
 scope :all, default: true
@@ -174,11 +206,31 @@ scope ->{ Date.today.strftime '%A' }, :published_today
 scope("Inactive") { |scope| scope.where(active: false) }
 
 # conditionally show a custom controller scope
-scope "Published", if: proc { current_admin_user.can? :manage, Posts } do |posts|
+scope "Published", if: -> { current_admin_user.can? :manage, Posts } do |posts|
   posts.published
 end
 ```
 
+Scopes can be labelled with a translation, e.g.
+`active_admin.scopes.scope_method`.
+
+### Scopes groups
+
+You can assign group names to scopes to keep related scopes together and separate them from the rest.
+
+```ruby
+# a scope in the default group
+scope :all
+
+# two scopes used to filter by status
+scope :active, group: :status
+scope :inactive, group: :status
+
+# two scopes used to filter by date
+scope :today, group: :date
+scope :tomorrow, group: :date
+```
+
 ## Index default sort order
 
 You can define the default sort order for index pages:
@@ -207,11 +259,19 @@ ActiveAdmin.register Post do
 end
 ```
 
+Or allow users to choose themselves using dropdown with values
+
+```ruby
+ActiveAdmin.register Post do
+  config.per_page = [10, 50, 100]
+end
+```
+
 You can change it per request / action too:
 
 ```ruby
 controller do
-  before_filter :only => :index do
+  before_action only: :index do
     @per_page = 100
   end
 end
@@ -260,6 +320,9 @@ ActiveAdmin.setup do |config|
 end
 ```
 
-Note: you have to actually implement PDF rendering for your action, ActiveAdmin does not provide this feature. This setting just allows you to specify formats that you want to show up under the index collection.
+Note: you have to actually implement PDF rendering for your action, ActiveAdmin
+does not provide this feature. This setting just allows you to specify formats
+that you want to show up under the index collection.
 
-You'll need to use a PDF rendering library like PDFKit or WickedPDF to get the PDF generation you want.
+You'll need to use a PDF rendering library like PDFKit or WickedPDF to get the
+PDF generation you want.

data/docs/4-csv-format.md

@@ -1,3 +1,7 @@
+---
+redirect_from: /docs/4-csv-format.html
+---
+
 # Customizing the CSV format
 
 Active Admin provides CSV file downloads on the index screen for each Resource.
@@ -11,6 +15,7 @@ ActiveAdmin.register Post do
   csv do
     column :title
     column(:author) { |post| post.author.full_name }
+    column('bODY', humanize_name: false) # preserve case
   end
 end
 ```
@@ -37,3 +42,33 @@ config.csv_options = { col_sep: ';' }
 # Force the use of quotes
 config.csv_options = { force_quotes: true }
 ```
+
+You can customize the filename by overriding `csv_filename` in the controller block.
+
+```ruby
+ActiveAdmin.register User do
+  controller do
+    def csv_filename
+      'User Details.csv'
+    end
+  end
+end
+```
+
+## Streaming
+
+By default Active Admin streams the CSV response to your browser as it's generated.
+This is good because it prevents request timeouts, for example the infamous H12
+error on Heroku.
+
+However if an exception occurs while generating the CSV, the request will eventually
+time out, with the last line containing the exception message. CSV streaming is
+disabled in development to help debug these exceptions. That lets you use tools like
+better_errors and web-console to debug the issue. If you want to customize the
+environments where CSV streaming is disabled, you can change this setting:
+
+```ruby
+# config/initializers/active_admin.rb
+
+config.disable_streaming_in = ['development', 'staging']
+```