activeadmin 0.1.1 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,4 +1,18 @@
-== 0.1.1
+== 0.2.0 (2011-05-12)
+
+0.2.0 is essentially an entire re-write of Active Admin. Here are some
+of the highlights. 250 commits. Enough said.
+
+* Features & Enhancements
+  * Full visual redesign
+  * Integrated Devise for authentication
+  * Brand new view and component layer called Arbre (Project coming soon)
+  * Added ActiveAdmin::Comments
+
+* Bug Fixes
+  * Too many to list! Been in production for close to a year
+
+== 0.1.1 (2010-09-15)
 
 * Bug Fixes
   * Fixed issues running on Ruby 1.9.2

data/Gemfile

@@ -1,16 +1,46 @@
 # These resources are needed to setup the test env
 source 'http://rubygems.org'
 
-# Rails & ActiveAdmin Dependencies
-gem 'rails',          '3.0.0'
-gem 'sqlite3-ruby',   :require => 'sqlite3'
-gem 'haml',           '3.0.18'
-gem 'formtastic',     '1.1.0.beta'
-gem 'will_paginate',  '3.0.pre2'
-gem "meta_search",    '0.9.2'
+# Set the RAILS env variable to test against diffirent versions of rails
+case ENV["RAILS"]
+when "3.0.0"
+  gem 'rails',          '= 3.0.0'
+when "3.0.1"
+  gem 'rails',          '= 3.0.1'
+when "3.0.2"
+  gem 'rails',          '= 3.0.2'
+when "3.0.3"
+  gem 'rails',          '= 3.0.3'
+when "3.0.4"
+  gem 'rails',          '= 3.0.4'
+when "3.0.5"
+  gem 'rails',          '= 3.0.5'
+when "3.0.6"
+  gem 'rails',          '= 3.0.6'
+else
+  # Default gems for in the gemspec
+  gem 'rails',          '>= 3.0.0'
+end
+
+gem "meta_search",    '>= 0.9.2'
+gem 'devise',         '>= 1.1.2'
+gem 'formtastic',     '>= 1.1.0'
+gem 'will_paginate',  '>= 3.0.pre2'
 gem 'inherited_views'
-gem 'jeweler'
+gem 'haml',           '>= 3.0.18'
+
+group :development, :test do
+  gem 'sqlite3-ruby',   :require => 'sqlite3'
+  gem 'jeweler',        '1.5.2'
+end
 
-# Testing Dependencies
-gem 'rspec',          '2.0.0.beta.20'
-gem 'rspec-rails',    '2.0.0.beta.20'
+group :test do
+  gem 'rspec',          '2.0.0.beta.22'
+  gem 'rspec-rails',    '2.0.0.beta.22'
+  gem 'capybara',       '0.3.9'
+  gem 'cucumber',       '0.9.2'
+  gem 'cucumber-rails', '0.3.2'
+  gem 'database_cleaner'
+  gem 'shoulda',        '2.11.2',           :require => nil
+  gem 'launchy'
+end

data/LICENSE

@@ -18,3 +18,8 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Iconic Icons are designed by P.J. Onori and are shared under
+the Creative Commons Attribution-Share Alike 3.0 license:
+http://creativecommons.org/licenses/by-sa/3.0/us
+http://somerandomdude.com/projects/iconic/

data/README.rdoc

@@ -1,143 +1,238 @@
 = Active Admin
 
-Active Admin is a tool to facilitate the generation of administration style interfaces.
-
+Active Admin is a framework for creating administration style interfaces. It
+abstracts common business application patterns to make it simple for developers
+to implement beautiful and elegant interfaces with very little effort.
 
 == Goals
 
-Although Active Admin is very young in its development cycle, here are its current goals:
+1. Allow developers to quickly create gorgeous administration interfaces 
+   <strong>(Not Just CRUD)</strong>
+2. Build a DSL for developers and an interface for businesses.
+3. Ensure that developers can easily customize every nook and cranny of the interface.
+4. Build common interfaces as shareable gems so that the entire community benefits.
 
-1. Build a toolset to quickly create template-able administration interfaces
-2. Allow the toolset to be entirely customizable (ie: we use standard rails coding practices
-   which can be overridden at any point)
-3. Design an interface which looks great!
-4. Build administration interfaces for common rails plugins as gems and share with the 
-   community (ie: devise admin)
 
-== Status
+== Getting Started
 
-Active Admin is very young. Although the code is well tested and is being used in production,
-the project is under heavy development. Once we get it to a point that has a relatively stable api,
-we will begin numbered releases starting with a 0.1 release.
+Active Admin is released as a Ruby Gem. The gem is to be installed within a Ruby
+on Rails 3 application. To install, simply add the following to your Gemfile:
 
-== Installation (Rails 3)
+  # Gemfile
+  gem 'activeadmin'
 
-Active Admin is released as a Gem. Installing the gem deals with all its dependencies, however 
-WillPaginate seems to have some Rails 3 issues still. For now:
+After updating your bundle, run the installer
 
-Add the following to your Gemfile:
+  $> rails generate active_admin:install
 
-  gem 'will_paginate',  :git => "git://github.com/mislav/will_paginate.git", :branch => 'rails3'
-  gem 'activeadmin'
+The installer creates an initializer used for configuring defaults used by Active Admin as well
+as a new folder at <tt>app/admin</tt> to put all your admin configurations. 
+
+Migrate your db and start the server:
+
+  $> rake db:migrate
+  $> rails server
+
+Visit http://localhost:3000/admin and log in using:
+
+* *User*: admin@example.com
+* *Password*: password
+
+Voila! You're on your brand new Active Admin dashboard.
+
+To register your first model, run:
+
+  $> rails generate active_admin:resource [MyModelName]
+
+This creates a file at <tt>app/admin/my_model_names.rb</tt> for configuring the resource.
+Refresh your web browser to see the interface.
+
+To learn how to further configure your admin section, keep on reading!
+
+== General Configuration
+
+=== Admin Users
+
+By default Active Admin will include Devise and create a new model called
+AdminUser. If you would like to use another name, you can pass it in to the
+installer through the user option:
+
+  $> rails generate active_admin:install UserClassName
+
+If you don't want the generator to create any user classes:
 
-Then, run the installer:
+  $> rails generate active_admin:install --skip-users
 
-  rails generate active_admin:install
+=== Authentication
 
-This will create an initializer which is used for configuring defaults used by Active Admin as well
-as a new folder at app/admin to put all your admin configurations. Note: All ruby files in 
-the Active Admin load path get loaded into the rails application.
+Active Admin requires two settings to authenticate and use the current user
+within your application. Both are set in
+<tt>config/initializers/active_admin.rb</tt>. 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.
 
-== Usage
+Set the method that controllers should call to authenticate the current user
+with:
 
-Let's build up an example using a Post model and the provided admin generator.
+  # config/initializers/active_admin.rb
+  config.authentication_method = :authenticate_admin_user!
 
-  rails generate active_admin:resource post
-  
-That's all you need to get a full CRUD, beautiful administration interface!
+Set the method to call within the view to access the current admin user
 
-The generator will create a new file app/admin/posts.rb that will
-look like the following:
+  # config/initializers/active_admin.rb
+  config.current_user_method = :current_admin_user
 
-  ActiveAdmin.register Post
+Both of these settings can be set to false to turn off authentication.
 
-=== Customize the Index Page
+  # Turn off authentication all together
+  config.authentication_method = false
+  config.current_user_method   = false
+
+=== Site Title
+
+You can update the title used for the site in the initializer also. By default
+it is set to the name of your Rails.application class name.
+
+  # config/initializers/active_admin.rb
+  config.site_title = "My Admin Site"
+
+== 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
+* *Grid*: A set of rows and columns each cell being a resource
+* *Blocks*: A set of rows (not tabular) each row being a resource
+* *Blog*: A title and body content, similar to a blog index
+
+All index pages also support scopes, filters, pagination, action items, and
+sidebar sections.
+
+=== 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:
+show, edit and delete the object. There are many ways to customize what gets
+displayed.
 
-==== Simple Columns
+==== Defining Columns
 
-If all you need to do is change the columns which get displayed, you can do so by passing
-them to the columns method:
+To display an attribute or a method on a resource, simply pass a symbol into the
+column method:
 
-  ActiveAdmin.register Post do
-    
-    index do |display|
-      display.columns :title, :comments_count, :created_at
+    index do
+      column :title
     end
 
-  end
+If the default title does not work for you, pass it as the first argument:
+
+    index do
+      column "My Custom Title", :title
+    end
 
-Or you can pass them in individually:
+Sometimes calling methods just isn't enough and you need to write some view
+specific code. For example, say we wanted a colum called Title which holds a
+link to the posts admin screen. 
 
-  ActiveAdmin.register Post do
-    
-    index do |display|
+The column method accepts a block as an argument which will then be rendered
+within the context of the view for each of the objects in the collection.
+
+    index do
+      column "Title" do |post| 
+        link_to post.title, admin_post_path(post)
+      end
+    end
 
-      # This will title the column 'Title' and call the #title method on each object
-      display.column :title
+The block gets called once for each resource in the collection. The resource gets passed into
+the block as an argument.
 
-      # This will title the column 'How many comments?' and call the #comments_count method on each object
-      display.column 'How many comments?', :comments_count
 
-      # You can add methods to the table builder which builds common things (ie: selectable checkboxes)
-      display.default_actions
+==== 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.
+
+  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:
+
+  index do
+    column :title, :sortable => false
   end
-  
-==== Advanced Columns
 
-Sometimes calling methods just isn't enough and you need to write some view specific code. For
-example, say we wanted a colum called Title which holds a link to the posts admin screen.
+==== Showing and Hiding Columns
 
-You can pass a block to a column which will then be rendered within the context of the view
-for each of the objects in the collection.
+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.
 
-  
-  ActiveAdmin.register Post do
-    
-    index do |display|
-      display.column("Title"){|post| link_to post.title, admin_post_path(post) }
+For example, if you were using CanCan:
+
+  index do
+    column :title, :sortable => false
+    if can? :manage, Post
+      column :some_secret_data
     end
+  end
+
+=== 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.
 
+  index :as => :grid do |product|
+    link_to(image_tag(product.image_path), admin_products_path(product))
   end
 
-The block gets called once for each resource in the collection. The resource gets passed into
-the block as an argument.
+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.
 
-==== Sorting
+You can customize the number of colums that are rendered using the columns
+option:
 
-The index views in Active Admin include sorting by default. 
-  
-  ActiveAdmin.register Post do
-    
-    index do |display|
+  index :as => :grid, :columns => 5 do |product|
+    link_to(image_tag(product.image_path), admin_products_path(product))
+  end
 
-      # A column created by a method call assumes its sortable
-      display.column :id
 
-      # 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.
-      display.column("Title", :sortable => :title){|post| link_to post.title, admin_post_path(post) }
+=== Index as a Block
 
-      # Turn off sorting by passing false
-      display.column :do_not_sort_me, :sortable => false
+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
 
 
-=== Customize the Form
+=== Index Filters
+
+=== Index Scopes
+
+== Customizing the Form
 
 Active Admin gives complete control over the output of the form by creating a thin DSL on top of
 the fabulous DSL created by Formtastic (http://github.com/justinfrench/formtastic).
-  
+
   ActiveAdmin.register Post do
-    
+
     form do |f|
       f.inputs "Details" do
         f.input :title
@@ -156,6 +251,21 @@ Please view the documentation for Formtastic to see all the wonderful things you
 http://github.com/justinfrench/formtastic
 
 
+== Customizing the Show Screen
+
+== Action Items
+
+== Sidebar Sections
+
+== The Dashboard
+
+== Custom Actions
+
+=== Collection Actions
+
+=== Member Actions
+
+
 == Tools Being Used
 
 We believe strongly in not writing code unless we have to, so Active Admin is built using many 
@@ -168,8 +278,12 @@ InheritedViews::
   Inherited Views is a thin addition to Inherited Resources which adds in html views to the mix
 Formtastic::
   A DSL for semantically building amazing forms.
+Devise::
+  User authentication is done using Devise
 WillPaginate::
   Pagination for rails apps
+Iconic Icons::
+  Excellent SVG icon set designed by P.J. Onori: http://somerandomdude.com/projects/iconic
 
 
 == Contributors
@@ -179,23 +293,24 @@ WillPaginate::
 * Sam Vincent     http://github.com/samvincent
 * Matt Vague      http://github.com/mattvague
 * Dan Kubb        http://github.com/dkubb
+* Sam Reh         http://github.com/samuelreh
 
 
 == Roadmap & Issue Tracking
 
-We are using the awesome Lighthouse ticketing system. The project can be found at:
-http://activeadmin.lighthouseapp.com
+We are using the awesome Github issues!
 
 == Note on Patches/Pull Requests
  
 * Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
+* Make your feature addition or bug fix on a new topic branch
+* Add specs and cukes for it. This is important so I don't break it in a
   future version unintentionally.
 * Commit, do not mess with rakefile, version, or history.
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+* Send me a pull request.
 
 == Copyright
 
 Copyright (c) 2010 Greg Bell, VersaPay Corporation. See LICENSE for details.
+