activeadministration 0.0.1

data/docs/3-index-pages.md

@@ -0,0 +1,245 @@
+# Customizing the Index Page
+
+Filtering and listing resources is one of the most important tasks for
+administering a web application. Active Admin provides many different tools for
+you to build a compelling interface into your data for the admin staff.
+
+Built in, Active Admin has the following index renderers:
+
+* *Table*: A table drawn with each row being a resource ([View Table Docs](3-index-pages/index-as-table.md))
+* *Grid*: A set of rows and columns each cell being a resource ([View Grid Docs](3-index-pages/index-as-grid.md))
+* *Blocks*: A set of rows (not tabular) each row being a resource ([View Blocks Docs](3-index-pages/index-as-block.md))
+* *Blog*: A title and body content, similar to a blog index ([View Blog Docs](3-index-pages/index-as-blog.md))
+
+All index pages also support scopes, filters, pagination, action items, and
+sidebar sections.
+
+## Multiple Index Pages
+
+Sometime you may want more than one index page for a resource to represent
+different views to the user. If multiple index pages exist, Active Admin will
+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.
+
+```ruby
+index do
+  id_column
+  column :image_title
+  default_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.
+
+```ruby
+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
+```
+
+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.
+
+```ruby
+index as: ActiveAdmin::Views::IndexAsTable do
+  column :image_title
+  default_actions
+end
+```
+
+## Index Filters
+
+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
+
+```ruby
+ActiveAdmin.register Post do
+  filter :title
+end
+```
+
+Out of the box, Active Admin supports the following filter types:
+
+* *:string* - A search field
+* *: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.
+* *:select* - A drop down which filters based on a selected item in a collection
+  or all.
+* *: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.
+
+```ruby
+filter :author, as: :check_boxes
+```
+
+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.
+
+```ruby
+filter :author, as: :check_boxes, collection: proc { Author.all }
+```
+
+You can change the filter label by passing a label option:
+
+```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:
+
+```ruby
+ActiveAdmin.register Post do
+  config.filters = false
+end
+```
+
+To disable for a namespace, in the initializer:
+
+```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:
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.filters = false
+end
+```
+
+You can also add a filter and still preserve the default filters:
+
+```ruby
+preserve_default_filters!
+filter :author
+```
+
+## 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:
+
+```ruby
+scope :all, default: true
+
+# assumes the model has a scope called ':active'
+scope :active
+
+# renames model scope ':leaves' to ':subcategories'
+scope "Subcategories", :leaves
+
+# Dynamic scope name
+scope ->{ Date.today.strftime '%A' }, :published_today
+
+# custom scope not defined on the model
+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|
+  posts.published
+end
+```
+
+## Index default sort order
+
+You can define the default sort order for index pages:
+
+```ruby
+ActiveAdmin.register Post do
+  config.sort_order = 'name_asc'
+end
+```
+
+## Index pagination
+
+You can set the number of records per page per resources:
+
+```ruby
+ActiveAdmin.register Post do
+  config.per_page = 10
+end
+```
+
+You can also disable pagination:
+
+```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
+
+You can easily remove or customize the download links you want displayed:
+
+```ruby
+# Per resource:
+ActiveAdmin.register Post do
+
+  index download_links: false
+  index download_links: [:pdf]
+  index download_links: proc{ current_user.can_view_download_links? }
+
+end
+
+# For the entire application:
+ActiveAdmin.setup do |config|
+
+  config.download_links = false
+  config.download_links = [:csv, :xml, :json, :pdf]
+  config.download_links = proc { current_user.can_view_download_links? }
+
+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/create-an-index.md

@@ -0,0 +1,31 @@
+# Create an 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

@@ -0,0 +1,21 @@
+<!--
+  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
+
+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.
+
+```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

@@ -0,0 +1,71 @@
+<!--
+  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.
+
+```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:
+
+```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:
+
+```ruby
+index as: :blog do
+  title do |post|
+    span post.title,      class: 'title'
+    span post.created_at, class: 'created_at'
+  end
+end
+```
+
+## Post Body
+
+The body is rendered underneath the title of each post. The same two
+style of options work as the Post Title above.
+
+Call a method on the resource as the body:
+
+```ruby
+index as: :blog do
+  title :my_title
+  body :my_body
+end
+```
+
+Or, render a block as the body:
+
+```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
+```

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

@@ -0,0 +1,29 @@
+<!--
+  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 Grid
+
+Sometimes you want to display the index screen for a set of resources as a grid
+(possibly a grid of thumbnail images). To do so, use the :grid option for the
+index block.
+
+```ruby
+index as: :grid do |product|
+  link_to image_tag(product.image_path), admin_product_path(product)
+end
+```
+
+The block is rendered within a cell in the grid once for each resource in the
+collection. The resource is passed into the block for you to use in the view.
+
+You can customize the number of columns that are rendered using the columns
+option:
+
+```ruby
+index as: :grid, columns: 5 do |product|
+  link_to image_tag(product.image_path), admin_product_path(product)
+end
+```

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

@@ -0,0 +1,163 @@
+<!--
+  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 Table
+
+By default, the index page is a table with each of the models content columns and links to
+show, edit and delete the object. There are many ways to customize what gets
+displayed.
+
+## Defining Columns
+
+To display an attribute or a method on a resource, simply pass a symbol into the
+column method:
+
+```ruby
+index do
+  selectable_column
+  column :title
+end
+```
+
+For association columns we make an educated guess on what to display by
+calling the following methods in the following order:
+
+```ruby
+:display_name, :full_name, :name, :username, :login, :title, :email, :to_s
+```
+
+This can be customized in `config/initializers/active_admin.rb`.
+
+If the default title does not work for you, pass it as the first argument:
+
+```ruby
+index do
+  selectable_column
+  column "My Custom Title", :title
+end
+```
+
+Sometimes that just isn't enough and you need to write some view-specific code.
+For example, say we wanted a "Title" column that links to the posts admin screen.
+
+`column` accepts a block that will be rendered for each of the objects in the collection.
+The block is called once for each resource, which is passed as an argument to the block.
+
+```ruby
+index do
+  selectable_column
+  column "Title" do |post|
+    link_to post.title, admin_post_path(post)
+  end
+end
+```
+
+To setup links to View, Edit and Delete a resource, use the `actions` method:
+
+```ruby
+index do
+  selectable_column
+  column :title
+  actions
+end
+```
+
+You can also append custom links to the default links:
+
+```ruby
+index do
+  selectable_column
+  column :title
+  actions do |post|
+    link_to "Preview", admin_preview_post_path(post), class: "member_link"
+  end
+end
+```
+
+Or forego the default links entirely:
+
+```ruby
+index do
+  column :title
+  actions defaults: false do |post|
+    link_to "View", admin_post_path(post)
+  end
+end
+```
+
+## 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.
+
+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.
+
+```ruby
+index do
+  column :title, sortable: :title do |post|
+    link_to post.title, admin_post_path(post)
+  end
+end
+```
+
+You can turn off sorting on any column by passing false:
+
+```ruby
+index do
+  column :title, sortable: false
+end
+```
+
+It's also possible to sort by PostgreSQL's hstore column key. You should set `sortable`
+option to a `column->'key'` value:
+
+```ruby
+index do
+  column :keywords, sortable: "meta->'keywords'"
+end
+```
+
+## Associated Sorting
+
+You're normally able to sort columns alphabetically, but by default you
+can't sort by associated objects. Though with a few simple changes, you can.
+
+Assuming you're on the Books index page, and Book has_one Publisher:
+
+```ruby
+controller do
+  def scoped_collection
+    super.includes :publisher # prevents N+1 queries to your database
+  end
+end
+```
+
+Then it's simple to sort by any Publisher attribute from within the index table:
+
+```ruby
+index do
+  column :publisher, sortable: 'publishers.name'
+end
+```
+
+## Showing and Hiding Columns
+
+The entire index block is rendered within the context of the view, so you can
+easily do things that show or hide columns based on the current context.
+
+For example, if you were using CanCan:
+
+```ruby
+index do
+  column :title, sortable: false
+  column :secret_data if can? :manage, Post
+end
+```