activeadmin 0.6.6 → 1.0.0.pre1

data/docs/3-index-pages.md

@@ -22,35 +22,44 @@ automatically build links at the top of the default index page. Including
 multiple views is simple and requires creating multiple index components in
 your resource.
 
-    index do
-      column :image_title
-      default_actions
-    end
-
-    index :as => :grid do |product|
-      link_to(image_tag(product.image_path), admin_product_path(product))
-    end
+```ruby
+index do
+  id_column
+  column :image_title
+  actions
+end
+
+index as: :grid do |product|
+  link_to image_tag(product.image_path), admin_product_path(product)
+end
+```
 
 The first index component will be the default index page unless you indicate
-otherwise by setting :default to true.
+otherwise by setting `:default` to true.
+
+```ruby
+index do
+  column :image_title
+  actions
+end
 
-    index do
-      column :image_title
-      default_actions
-    end
+index as: :grid, default: true do |product|
+  link_to image_tag(product.image_path), admin_product_path(product)
+end
+```
 
-    index :as => :grid, :default => true do |product|
-      link_to(image_tag(product.image_path), admin_product_path(product))
-    end
+## Custom Index
 
 Active Admin does not limit the index page to be a table, block, blog or grid.
-If you've [created your own index page](3-index-pages/create-an-index.md) it can be included by setting :as to the
-class of the index component you created.
+If you've created your own [custom index](3-index-pages/custom-index.md) page it
+can be included by setting `:as` to the class of the index component you created.
 
-    index :as => ActiveAdmin::Views::IndexAsTable do
-      column :image_title
-      default_actions
-    end
+```ruby
+index as: ActiveAdmin::Views::IndexAsMyIdea do
+  column :image_title
+  actions
+end
+```
 
 ## Index Filters
 
@@ -58,11 +67,13 @@ By default the index screen includes a "Filters" sidebar on the right hand side
 with a filter for each attribute of the registered model. You can customize the
 filters that are displayed as well as the type of widgets they use.
 
-To display a filter for an attribute, use the filter method
+To display a filter for an attribute, use the `filter` method
 
-    ActiveAdmin.register Post do
-      filter :title
-    end
+```ruby
+ActiveAdmin.register Post do
+  filter :title
+end
+```
 
 Out of the box, Active Admin supports the following filter types:
 
@@ -75,117 +86,180 @@ Out of the box, Active Admin supports the following filter types:
 * *:check_boxes* - A list of check boxes users can turn on and off to filter
 
 By default, Active Admin will pick the most relevant filter based on the
-attribute type. You can force the type by passing the :as option.
+attribute type. You can force the type by passing the `:as` option.
 
-    filter :author, :as => :check_boxes
+```ruby
+filter :author, as: :check_boxes
+```
 
-The :check_boxes and :select types accept options for the collection. By default
+The `:check_boxes` and `:select` types accept options for the collection. By default
 it attempts to create a collection based on an association. But you can pass in
 the collection as a proc to be called at render time.
 
-    # Will call available
-    filter :author, :as => :check_boxes, :collection => proc { Author.all }
+```ruby
+filter :author, as: :check_boxes, collection: proc { Author.all }
+```
 
 You can change the filter label by passing a label option:
 
-    filter :author, :label => 'Author'
+```ruby
+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.
+
+```ruby
+filter :first_name_or_last_name_cont, as: :string, label: "Name"
+```
+
 Filters can also be disabled for a resource, a namespace or the entire
 application.
 
 To disable for a specific resource:
 
-    ActiveAdmin.register Post do
-      config.filters = false
-    end
+```ruby
+ActiveAdmin.register Post do
+  config.filters = false
+end
+```
 
 To disable for a namespace, in the initializer:
 
-    ActiveAdmin.setup do |config|
-      config.namespace :my_namespace do |my_namespace|
-        my_namespace.filters = false
-      end
-    end
+```ruby
+ActiveAdmin.setup do |config|
+  config.namespace :my_namespace do |my_namespace|
+    my_namespace.filters = false
+  end
+end
+```
 
 Or to disable for the entire application:
 
-    ActiveAdmin.setup do |config|
-      config.filters = false
-    end
+```ruby
+ActiveAdmin.setup do |config|
+  config.filters = false
+end
+```
 
 You can also add a filter and still preserve the default filters:
 
-    preserve_default_filters!
-    filter :author
+```ruby
+preserve_default_filters!
+filter :author
+```
 
-## Index default sort order
+## Index Scopes
 
-You can define the default sort order for index pages:
+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:
 
-    ActiveAdmin.register Post do
-      config.sort_order = "name_asc"
-    end
+```ruby
+scope :all, default: true
 
-## Index pagination
+# assumes the model has a scope called ':active'
+scope :active
 
+# renames model scope ':leaves' to ':subcategories'
+scope "Subcategories", :leaves
 
-You can set the number of records per page per resources:
+# Dynamic scope name
+scope ->{ Date.today.strftime '%A' }, :published_today
 
-    ActiveAdmin.register Post do
-      config.per_page = 10
-    end
+# custom scope not defined on the model
+scope("Inactive") { |scope| scope.where(active: false) }
 
-You can also disable pagination:
+# conditionally show a custom controller scope
+scope "Published", if: proc { current_admin_user.can? :manage, Posts } do |posts|
+  posts.published
+end
+```
 
-    ActiveAdmin.register Post do
-      config.paginate = false
-    end
+## Index default sort order
 
-If you have a very large database, you might want to disable SELECT COUNT(*) queries caused by the pagination info at the bottom of the page:
+You can define the default sort order for index pages:
 
-    ActiveAdmin.register Post do
+```ruby
+ActiveAdmin.register Post do
+  config.sort_order = 'name_asc'
+end
+```
 
-      # disable pagination total
-      index :pagination_total => false do
-        #...
-      end
+## Index pagination
 
-    end
+You can set the number of records per page as default:
 
-## Disable CSV, XML and JSON export
+```ruby
+ActiveAdmin.setup do |config|
+  config.default_per_page = 30
+end
+```
 
-You can remove links to download CSV, XML and JSON exports:
+You can set the number of records per page per resources:
 
-    index :download_links => false do
-    end
+```ruby
+ActiveAdmin.register Post do
+  config.per_page = 10
+end
+```
 
-## Customizing Download Links
+You can change it per request / action too:
 
-There are multiple ways to either remove the download links per resource listing, or customize the formats that are shown.  Customize the formats by passing an array of symbols, or pass false to hide entirely.
+```ruby
+controller do
+  before_filter :only => :index do
+    @per_page = 100
+  end
+end
+```
 
-Customizing the download links per resource:
+You can also disable pagination:
 
-    ActiveAdmin.register Post do
+```ruby
+ActiveAdmin.register Post do
+  config.paginate = false
+end
+```
+
+If you have a very large database, you might want to disable `SELECT COUNT(*)`
+queries caused by the pagination info at the bottom of the page:
+
+```ruby
+ActiveAdmin.register Post do
+  index pagination_total: false do
+    # ...
+  end
+end
+```
+
+## Customizing Download Links
 
-      # hide the links entirely
-      index :download_links => false
+You can easily remove or customize the download links you want displayed:
 
-      # only show a PDF export
-      index :download_links => [:pdf]
+```ruby
+# Per resource:
+ActiveAdmin.register Post do
 
-    end
+  index download_links: false
+  index download_links: [:pdf]
+  index download_links: proc{ current_user.can_view_download_links? }
 
-If you want to customize download links for every resource throughout the application, configure that in the `active_admin` initializer.
+end
 
-    ActiveAdmin.setup do |config|
+# For the entire application:
+ActiveAdmin.setup do |config|
 
-      # Disable entirely
-      config.download_links = false
+  config.download_links = false
+  config.download_links = [:csv, :xml, :json, :pdf]
+  config.download_links = proc { current_user.can_view_download_links? }
 
-      # Want PDF added to default download links
-      config.download_links = [:csv, :xml, :json, :pdf]
+end
+```
 
-    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.
 
+You'll need to use a PDF rendering library like PDFKit or WickedPDF to get the PDF generation you want.

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

@@ -0,0 +1,31 @@
+# Custom Index
+
+If the supplied Active Admin index components are insufficient for your project
+feel free to define your own. Index classes inherit from `ActiveAdmin::Component`
+and require a `build` method and an `index_name` class method.
+
+```ruby
+module ActiveAdmin
+  module Views
+    class IndexAsMyIdea < ActiveAdmin::Component
+
+      def build(page_presenter, collection)
+        # ...
+      end
+
+      def self.index_name
+        "my_idea"
+      end
+
+    end
+  end
+end
+```
+
+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
+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,4 +1,8 @@
-<!-- Please don't edit this file. It will be clobbered. -->
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
 
 # Index as a Block
 
@@ -6,11 +10,12 @@ If you want to fully customize the display of your resources on the index
 screen, Index as a Block allows you to render a block of content for each
 resource.
 
-    index :as => :block do |product|
-      div :for => product do
-        h2 auto_link(product.title)
-        div do
-          simple_format product.description
-        end
-      end
-    end
+```ruby
+index as: :block do |product|
+  div for: product do
+    resource_selection_cell product
+    h2  auto_link     product.title
+    div simple_format product.description
+  end
+end
+```

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

@@ -1,40 +1,46 @@
-<!-- Please don't edit this file. It will be clobbered. -->
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
 
 # Index as Blog
 
 Render your index page as a set of posts. The post has two main options:
 title and body.
 
-    index :as => :blog do
-      title :my_title # Calls #my_title on each resource
-      body  :my_body  # Calls #my_body on each resource
-    end
+```ruby
+index as: :blog do
+  title :my_title # Calls #my_title on each resource
+  body  :my_body  # Calls #my_body on each resource
+end
+```
 
 ## Post Title
 
 The title is the content that will be rendered within a link to the
 resource. There are two main ways to set the content for the title
 
-First, you can pass in a method to be called on your
-resource. For example:
-
-    index :as => :blog do
-      title :a_method_to_call
-    end
+First, you can pass in a method to be called on your resource. For example:
 
-This will result in the title of the post being the return value of
-Resource#a_method_to_call
+```ruby
+index as: :blog do
+  title :a_method_to_call
+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
 is passed in to the block. For Example:
 
-    index :as => :blog do
-      title do |post|
-        span post.title, :class => 'title'
-        span post.created_at, :class => 'created_at'
-      end
-    end
+```ruby
+index as: :blog do
+  title do |post|
+    span post.title,      class: 'title'
+    span post.created_at, class: 'created_at'
+  end
+end
+```
 
 ## Post Body
 
@@ -43,19 +49,23 @@ style of options work as the Post Title above.
 
 Call a method on the resource as the body:
 
-    index :as => :blog do
-      title :my_title
-      body :my_body # Return value of #my_body will be the body
-    end
+```ruby
+index as: :blog do
+  title :my_title
+  body :my_body
+end
+```
 
 Or, render a block as the body:
 
-    index :as => :blog do
-      title :my_title
-      body do |post|
-        div truncate(post.title)
-        div :class => 'meta' do
-          span "Post in #{post.categories.join(', ')}"
-        end
-      end
+```ruby
+index as: :blog do
+  title :my_title
+  body do |post|
+    div truncate post.title
+    div class: 'meta' do
+      span "Post in #{post.categories.join(', ')}"
     end
+  end
+end
+```