activeadmin 0.6.6 → 1.0.0.pre1

data/docs/1-general-configuration.md

@@ -1,129 +1,140 @@
 # General Configuration
 
-Active Admin generates an initializer for you with sane defaults. The
-initializer can be found at `config/initializers/active_admin.rb`. For the most
-part, it is well documented. Here are a few common configurations.
+You can configure Active Admin settings in `config/initializers/active_admin.rb`.
+Here are a few common configurations:
 
 ## Authentication
 
 Active Admin requires two settings to authenticate and use the current user
-within your application. Both are set in `config/initializers/active_admin.rb`.
-By default they are setup for use with Devise and a model named AdminUser. If
-you chose a different model name, you will need to update these settings.
+within your application.
 
-Set the method that controllers should call to authenticate the current user
-with:
++ the method controllers used to force authentication
 
-    # config/initializers/active_admin.rb
-    config.authentication_method = :authenticate_admin_user!
+```ruby
+config.authentication_method = :authenticate_admin_user!
+```
 
-Set the method to call within the view to access the current admin user
++ the method used to access the current user
 
-    # config/initializers/active_admin.rb
-    config.current_user_method = :current_admin_user
+```ruby
+config.current_user_method = :current_admin_user
+```
 
 Both of these settings can be set to false to turn off authentication.
 
-    # Turn off authentication all together
-    config.authentication_method = false
-    config.current_user_method   = false
+```ruby
+config.authentication_method = false
+config.current_user_method   = false
+```
 
 ## Site Title Options
 
-You can update the title or use an optional image in the initializer also. In addition you can set the link.  By default
-there is no link and the title is set to the name of your Rails.application class name.
+Every page has what's called the site title on the left side of the menu bar.
+If you want, you can customize it.
 
-    # config/initializers/active_admin.rb
-    config.site_title = "My Admin Site"
-    config.site_title_link = "/"    ## Rails url helpers do not work here
-    config.site_title_image = "site_log_image.png"
+```ruby
+config.site_title       = "My Admin Site"
+config.site_title_link  = "/"
+config.site_title_image = "site_image.png"
+config.site_title_image = "http://www.google.com/images/logos/google_logo_41.png"
+config.site_title_image = ->(context) { context.current_user.company.logo_url }
+```
 
 ## Internationalization (I18n)
 
-To internationalize Active Admin or to change default strings, you can copy
-`lib/active_admin/locales/en.yml` to your application `config/locales` directory and
-change its content. You can contribute to the project with your translations too!
+To translate Active Admin to a new language or customize an existing translation, you can copy
+[config/locales/en.yml](https://github.com/activeadmin/activeadmin/blob/master/config/locales/en.yml)
+to your application's `config/locales` folder and update it. We welcome new/updated translations,
+so feel free to [contribute](https://github.com/activeadmin/activeadmin/blob/master/CONTRIBUTING.md)!
+To translate third party gems like devise, use for example devise-i18n.
 
 ## Namespaces
 
 When registering resources in Active Admin, they are loaded into a namespace.
 The default namespace is "admin".
 
-    # app/admin/posts.rb
-    ActiveAdmin.register Post do
-      # ...
-    end
+```ruby
+# app/admin/posts.rb
+ActiveAdmin.register Post do
+  # ...
+end
+```
 
 The Post resource will be loaded into the "admin" namespace and will be
-available at `/admin/posts`. Each namespace holds on to its own configuration
-settings which inherit from the application's general configurations.
+available at `/admin/posts`. Each namespace holds on to its own settings that
+inherit from the application's configuration.
 
-For example, if you have two namespaces: `:admin` and `super_admin` and want to
-have different site title's for each namespace. You can use the
-`config.namespace(name)` block within the initializer file to configure them
-individually.
+For example, if you have two namespaces (`:admin` and `:super_admin`) and want to
+have different site title's for each, you can use the `config.namespace(name)`
+block within the initializer file to configure them individually.
 
-    ActiveAdmin.setup do |config|
-      config.site_title = "My Default Site Title"
+```ruby
+ActiveAdmin.setup do |config|
+  config.site_title = "My Default Site Title"
 
-      config.namespace :admin do |admin|
-        admin.site_title = "Admin Site"
-      end
+  config.namespace :admin do |admin|
+    admin.site_title = "Admin Site"
+  end
 
-      config.namespace :super_admin do |super_admin|
-        super_admin.site_title = "Super Admin Site"
-      end
-    end
+  config.namespace :super_admin do |super_admin|
+    super_admin.site_title = "Super Admin Site"
+  end
+end
+```
 
 Each setting available in the Active Admin setup block is configurable on a per
 namespace basis.
 
 ## Load paths
 
-By default Active Admin files go under '/app/admin'. You can change this
+By default Active Admin files go inside `app/admin/`. You can change this
 directory in the initializer file:
 
-    ActiveAdmin.setup do |config|
-      config.load_paths = [File.join(Rails.root, "app", "ui")]
-    end
+```ruby
+ActiveAdmin.setup do |config|
+  config.load_paths = [File.join(Rails.root, "app", "ui")]
+end
+```
 
 ## Comments
 
 By default Active Admin includes comments on resources. Sometimes, this is
-undesired. To disable comments for the entire application:
-
-    ActiveAdmin.setup do |config|
-
-      config.allow_comments = false
-
-    end
-
-If you would like to enable / disable comments for just a namespace, do the
-following:
-
-    ActiveAdmin.setup do |config|
-
-      config.namespace :admin do |admin|
-        admin.allow_comments = false
-      end
-
-    end
-
-You can also disable comments for a specific resource:
-
-    ActiveAdmin.register Post do
-      config.comments = false
-    end
+undesired. To disable comments:
+
+```ruby
+# For the entire application:
+ActiveAdmin.setup do |config|
+  config.comments = false
+end
+
+# For a namespace:
+ActiveAdmin.setup do |config|
+  config.namespace :admin do |admin|
+    admin.comments = false
+  end
+end
+
+# For a given resource:
+ActiveAdmin.register Post do
+  config.comments = false
+end
+```
 
 ## Utility Navigation
 
-The "utility navigation" shown at the top right when logged in by default shows the current user email address and a link to "Log Out".  However, the utility navigation is just like any other menu in the system, so you can provide your own menu to be rendered in place if you like.
-
-    ActiveAdmin.setup do |config|
-      config.namespace :admin do |admin|
-        admin.build_menu :utility_navigation do |menu|
-          menu.add label: "ActiveAdmin.info", url: "http://www.activeadmin.info", html_options: { target: :blank }
-          admin.add_logout_button_to_menu menu # can also pass priority & html_options for link_to to use
-        end
-      end
+The "utility navigation" shown at the top right normally shows the current user
+and a link to log out. However, the utility navigation is just like any other
+menu in the system; you can provide your own menu to be rendered in its place.
+
+```ruby
+ActiveAdmin.setup do |config|
+  config.namespace :admin do |admin|
+    admin.build_menu :utility_navigation do |menu|
+      menu.add label: "ActiveAdmin.info", url: "http://www.activeadmin.info",
+                                          html_options: { target: :blank }
+      admin.add_current_user_to_menu  menu
+      admin.add_logout_button_to_menu menu
     end
+  end
+end
+```

data/docs/10-custom-pages.md

@@ -1,96 +1,96 @@
 # Custom Pages
 
-When you need a standalone page on your site, Custom Pages will be there with a familiar syntax to resource registration.
+If you have data you want on a standalone page that isn't tied to a resource,
+custom pages provide you with a familiar syntax and feature set:
 
-## Available Features
-* main page content
-* menu item
+* a menu item
 * sidebars
-* action_items
-* page_actions
+* action items
+* page actions
 
 ## Create a new Page
 
-Creating a page is a simple as calling the `register_page` method:
-
-    ActiveAdmin.register_page "My Page" do
-      content do
-        para "Hello World"
-      end
+Creating a page is as simple as calling `register_page`:
+
+```ruby
+# app/admin/calendar.rb
+ActiveAdmin.register_page "Calendar" do
+  content do
+    para "Hello World"
+  end
+end
+```
+
+Anything rendered within `content` will be the main content on the page.
+Partials behave exactly the same way as they do for resources:
+
+```ruby
+# app/admin/calendar.rb
+ActiveAdmin.register_page "Calendar" do
+  content do
+    render partial: 'calendar'
+  end
+end
+
+# app/views/admin/calendar/_calendar.html.arb
+table do
+  thead do
+    tr do
+      %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].each &method(:th)
     end
-
-In the above example, a new page will be created at `/admin/my_page` with the
-title "My Page" and the content of "Hello World". Anything rendered within
-`content` will be the main content on the page.
-
-## Page Title & I18n
-
-Coming soon...
+  end
+  tbody do
+    # ...
+  end
+end
+```
 
 ## Customize the Menu
 
-The menu item is available to customize just like
-[any other resource](2-resource-customization.md#customize-the-menu) in Active Admin.
+See the [Menu](2-resource-customization.md#customize-the-menu) documentation.
 
-## Add a Sidebar Section
+## Customize the Namespace
 
-You can add sidebar sections to your pages using the same DSL as other resources
-in Active Admin:
+We use the `admin` namespace by default, but you can use anything:
 
-    ActiveAdmin.register_page "My Page" do
+```ruby
+# Available at /today/calendar
+ActiveAdmin.register_page "Calendar", namespace: :today
 
-      sidebar :help do
-        ul do
-          li "First Line of Help"
-        end
-      end
+# Available at /calendar
+ActiveAdmin.register_page "Calendar", namespace: false
+```
 
-      content do
-        para "Hello World"
-      end
-    end
+## Add a Sidebar
 
-This creates a sidebar section named "Help" containing an unordered list.
-To view the full customization options, visit [Sidebars](7-sidebars.md).
+See the [Sidebars](7-sidebars.md) documentation.
 
 ## Add an Action Item
 
-Just like other resources, you can add Action Item's to pages:
-
-    ActiveAdmin.register_page "My Page" do
+Just like other resources, you can add action items. The difference here being that
+`:only` and `:except` don't apply because there's only one page it could apply to.
 
-      action_item do
-        link_to "View Site", "/"
-      end
-
-      content do
-        para "Hello World"
-      end
-    end
-
-This adds an action item that links to the root URL of the application.
+```ruby
+action_item :view_site do
+  link_to "View Site", "/"
+end
+```
 
 ## Add a Page Action
 
-`page_action` allows you to define controller actions specific to this page,
-and is the functional equivalent of `collection_action`.
+Page actions are custom controller actions (which mirror the resource DSL for the same feature).
 
-    ActiveAdmin.register_page "My Page" do
+```ruby
+page_action :add_event, method: :post do
+  # ...
+  redirect_to admin_calendar_path, notice: "Your event was added"
+end
 
-      page_action :ex, :method => :post do
-        # do stuff here
-        redirect_to admin_my_page_path, :notice => "You did stuff!"
-      end
-
-      action_item do
-        link_to "Do Stuff", admin_my_page_ex_path, :method => :post
-      end
-
-      content do
-        para "Hello World"
-      end
-    end
+action_item :add do
+  link_to "Add Event", admin_calendar_add_event_path, method: :post
+end
+```
 
-This defines the route `/admin/my_page/ex` which can handle HTTP POST requests.
+This defines the route `/admin/calendar/add_event` which can handle HTTP POST requests.
 
-Clicking on the `action_item` will reload page with the message "You did stuff!"
+Clicking on the action item will reload page and display the message "Your event was added"

data/docs/11-decorators.md

@@ -1,66 +1,55 @@
 # Decorators
 
-Active Admin supports the use of decorators for resources. Resources will be
-decorated for the index and show blocks. The
-[draper](https://github.com/drapergem/draper) gem is recommended but not required
-(more on requirements below). Note, that Active Admin works out of the box with
-Draper `>= 1.0.0`.
-
-## Configuration
-
-    ActiveAdmin.register Post do
-      decorate_with PostDecorator
-    end
-
-## Example Usage
-
-This example uses [draper](https://github.com/drapergem/draper).
-
-    # Gemfile
-    gem 'draper', '>= 1.0.0'
-
-Assuming a post and a post decorator
-
-    class Post < ActiveRecord::Base; end
-
-    class PostDecorator < ApplicationDecorator
-      decorates :post
-
-      def image
-        h.image_tag model.image_url
-      end
-    end
-
-Then the following is possible
-
-    ActiveAdmin.register Post do
-      decorate_with PostDecorator
-
-      index do
-        column(:title)
-        column(:image)
-      end
-
-      show do
-        attributes_table do
-          row(:title)
-          row(:image)
-        end
-      end
-    end
+Active Admin allows you to use the decorator pattern to provide view-specific
+versions of a resource. [Draper](https://github.com/drapergem/draper) is
+recommended but not required.
+
+To use decorator support without Draper, your decorator must support a variety
+of collection methods to support pagination, filtering, etc. See
+[this github issue discussion](https://github.com/activeadmin/activeadmin/issues/3600)
+and [this gem](https://github.com/kiote/activeadmin-poro-decorator) for more details.
+
+## Example usage
+
+```ruby
+# app/models/post.rb
+class Post < ActiveRecord::Base
+  # has title, content, and image_url
+end
+
+# app/decorators/post_decorator.rb
+class PostDecorator < Draper::Decorator
+  delegate_all
+
+  def image
+    h.image_tag model.image_url
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  decorate_with PostDecorator
+
+  index do
+    column :title
+    column :image
+    actions
+  end
+end
+```
 
 ## Forms
 
-Note that the resource proveded to form_for also gets decorated.
-
-In most cases this will work as expected. However, it is possible to disable
-automatic decoration in the form with the `decorate` option:
-
-    ActiveAdmin.register Post do
-      decorate_with PostDecorator
+By default, ActiveAdmin does *not* decorate the resource used to render forms.
+If you need ActiveAdmin to decorate the forms, you can pass `decorate: true` to the
+form block.
 
-      form decorate: false do
-        # ...
-      end
-    end
+```ruby
+ActiveAdmin.register Post do
+  decorate_with PostDecorator
 
+  form decorate: true do |f|
+    # ...
+  end
+end
+```