admin_assistant 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+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.

data/README

@@ -0,0 +1,43 @@
+admin_assistant
+===============
+
+admin_assistant is a Rails plugin that automates a lot of features typically
+needed in admin interfaces. Current features include:
+
+* Your basic CReate / Update / Delete
+* Index with pagination and field ordering
+* Search, either by all text fields or by specific fields
+* Live querying of models to generate forms and indexes, meaning that adding
+  new columns to your admin controllers is easy
+* Simple handling of belongs_to association via drop-down selects
+* Built-in support for Paperclip and FileColumn
+
+I'm following a few design principles in building this:
+
+* admin_assistant's specs are written through an actual Rails app: I believe
+  this is the only sensible way to test a Rails plugin that deals with lots of 
+  controller actions and views.
+* admin_assistant will support multiple versions of Rails, so I'm experimenting
+  with a spec suite that can be run against all versions with one Rake task.
+* admin_assistant will be severely hookable. If you're copying and pasting
+  something out of vendor/plugins/admin_assistant, that's a design flaw.
+* admin_assistant will be minimally invasive to the rest of the Rails app. It
+  does not require that you add strange one-off methods to an important model
+  just to do something in an admin controller. And I'll try to avoid doing
+  anything silly like alias_method_chaining anything on ActionController::Base.
+* admin_assistant will have some safe defaults, including turning off the
+  destroy action by default, and not filling in dates and times with the
+  current date or time (which is almost always useless).
+  
+There are also some features I'm skimping on right now:
+
+* Super-pretty CSS: Because I suck at CSS. Submissions of themes are welcome
+  though.
+* Super-fancy Ajax: Because I think it's easy to do this wrong. But there will
+  be some Ajax at some point I spose.
+
+Basically, this plugin should act like a really great administrative assistant
+in your office. It tries to be extremely helpful, but it won't get underfoot or 
+tell you how to do your job.
+
+Copyright (c) 2009 Francis Hwang, released under the MIT license

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Default: run all specs across all supported Rails gem versions.'
+task :default => :spec
+
+desc 'Run all specs across all supported Rails gem versions.'
+task :spec do
+  %w(2.1.2 2.2.2 2.3.2).each do |rails_gem_version|
+    puts "*** RAILS #{rails_gem_version} ***"
+    cmd = "cd test_rails_app && RAILS_GEM_VERSION=#{rails_gem_version} rake"
+    puts cmd
+    puts `#{cmd}`
+    puts
+    puts
+  end
+end
+
+desc 'Generate documentation for the admin_assistant plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'AdminAssistant'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/admin_assistant/builder.rb

@@ -0,0 +1,104 @@
+class AdminAssistant
+  class Builder
+    attr_reader :admin_assistant
+    
+    def initialize(admin_assistant)
+      @admin_assistant = admin_assistant
+    end
+    
+    def actions(*a)
+      if a.empty?
+        @admin_assistant.actions
+      else
+        @admin_assistant.actions = a
+      end
+    end
+    
+    def inputs
+      @admin_assistant.form_settings.inputs
+    end
+    
+    def label(column, label)
+      @admin_assistant.custom_column_labels[column.to_s] = label
+    end
+      
+    def form
+      yield @admin_assistant.form_settings
+    end
+      
+    def index
+      yield @admin_assistant.index_settings
+    end
+  end
+  
+  class Settings
+    attr_reader :column_names
+    
+    def initialize(admin_assistant)
+      @admin_assistant = admin_assistant
+    end
+    
+    def columns(*args)
+      @column_names = args
+    end
+  end
+  
+  class FormSettings < Settings
+    attr_reader :inputs, :submit_buttons
+    
+    def initialize(admin_assistant)
+      super
+      @inputs = {}
+      @submit_buttons = []
+      @read_only = []
+    end
+    
+    def read_only(*args)
+      if args.empty?
+        @read_only
+      else
+        args.each do |arg| @read_only << arg.to_s; end
+      end
+    end
+  end
+  
+  class IndexSettings < Settings
+    attr_reader :actions, :link_to_args, :search_fields, :sort_by
+    attr_accessor :total_entries
+    
+    def initialize(admin_assistant)
+      super
+      @actions = {}
+      @sort_by = 'id desc'
+      @boolean_labels = {}
+      @link_to_args = {}
+      @search_fields = []
+    end
+    
+    def boolean_labels(*args)
+      if args.size == 1
+        args.first.each do |column_name, pairs|
+          @boolean_labels[column_name.to_s] = pairs
+        end
+      else
+        @boolean_labels
+      end
+    end
+    
+    def conditions(&block)
+      block ? (@conditions = block) : @conditions
+    end
+    
+    def search(*fields)
+      @search_fields = fields
+    end
+    
+    def sort_by(*sb)
+      if sb.empty?
+        @sort_by
+      else
+        @sort_by = sb
+      end
+    end
+  end
+end

data/lib/admin_assistant/column.rb

@@ -0,0 +1,383 @@
+class AdminAssistant
+  class Column
+    attr_accessor :custom_label
+
+    def view(action_view, opts = {})
+      klass = self.class.const_get 'View'
+      klass.new self, action_view, opts
+    end
+  
+    class View < Delegator
+      attr_reader :sort_order
+      
+      def initialize(column, action_view, opts)
+        super(column)
+        @column, @action_view, @opts = column, action_view, opts
+        @input = opts[:input]
+        @link_to_args = opts[:link_to_args]
+        @search = opts[:search]
+        @sort_order = opts[:sort_order]
+      end
+      
+      def __getobj__
+        @column
+      end
+      
+      def __setobj__(column)
+        @column = column
+      end
+      
+      def form_value(record)
+        value_method = "#{@column.name}_value"
+        if @action_view.respond_to?(value_method)
+          @action_view.send value_method, record
+        else
+          field_value record
+        end
+      end
+      
+      def index_header_css_class
+        "sort #{sort_order}" if sort_order
+      end
+      
+      def index_td_css_class
+        'sort' if sort_order
+      end
+      
+      def index_html(record)
+        html_for_index_method = "#{name}_html_for_index"
+        html = if @action_view.respond_to?(html_for_index_method)
+          @action_view.send html_for_index_method, record
+        elsif @link_to_args
+          @action_view.link_to(
+            @action_view.send(:h, index_value(record)),
+            @link_to_args.call(record)
+          )
+        else
+          @action_view.send(:h, index_value(record))
+        end
+        html = '&nbsp;' if html.blank?
+        html
+      end
+      
+      def index_value(record)
+        value_method = "#{@column.name}_value"
+        if @action_view.respond_to?(value_method)
+          @action_view.send value_method, record
+        else
+          field_value record
+        end
+      end
+      
+      def label
+        if @column.custom_label
+          @column.custom_label
+        elsif @column.name.to_s == 'id'
+          'ID'
+        else
+          @column.name.to_s.capitalize.gsub(/_/, ' ') 
+        end
+      end
+    
+      def next_sort_params
+        name_for_sort = name
+        next_sort_order = 'asc'
+        if sort_order
+          if sort_order == 'asc'
+            next_sort_order = 'desc'
+          else
+            name_for_sort = nil
+            next_sort_order = nil
+          end
+        end
+        {:sort => name_for_sort, :sort_order => next_sort_order}
+      end
+      
+      def paperclip?
+        @column.is_a?(PaperclipColumn)
+      end
+      
+      def sort_possible?
+        @column.is_a?(ActiveRecordColumn) || @column.is_a?(BelongsToColumn)
+      end
+    end
+  end
+  
+  class ActiveRecordColumn < Column
+    attr_accessor :search_terms
+    
+    def initialize(ar_column)
+      @ar_column = ar_column
+    end
+    
+    def add_to_query(ar_query)
+      unless @search_terms.blank?
+        ar_query.boolean_join = :and
+        case sql_type
+          when :boolean
+            ar_query.condition_sqls << "#{name} = ?"
+            ar_query.bind_vars << search_value
+          else
+            ar_query.condition_sqls << "#{name} like ?"
+            ar_query.bind_vars << "%#{@search_terms}%"
+        end
+      end
+    end
+    
+    def contains?(column_name)
+      column_name.to_s == @ar_column.name
+    end
+    
+    def name
+      @ar_column.name
+    end
+    
+    def search_value
+      case sql_type
+        when :boolean
+          @search_terms.blank? ? nil : (@search_terms == 'true')
+        else
+          @search_terms
+      end
+    end
+    
+    def sql_type
+      @ar_column.type
+    end
+    
+    class View < AdminAssistant::Column::View
+      def initialize(column, action_view, opts)
+        super
+        @boolean_labels = opts[:boolean_labels]
+      end
+      
+      def add_to_form(form)
+        case @input || @column.sql_type
+          when :text
+            form.text_area name
+          when :boolean
+            form.check_box name
+          when :datetime
+            form.datetime_select name, :include_blank => true
+          when :date
+            form.date_select name, :include_blank => true
+          when :us_state
+            form.select(
+              name, ordered_us_state_names_and_codes, :include_blank => true
+            )
+          else
+            form.text_field name
+          end
+      end
+
+      def field_value(record)
+        record.send(name) if record.respond_to?(name)
+      end
+      
+      def index_value(record)
+        value = super
+        if @boolean_labels
+          value = value ? @boolean_labels.first : @boolean_labels.last
+        end
+        value
+      end
+      
+      def ordered_us_state_names_and_codes
+        {
+          'Alabama' => 'AL', 'Alaska' => 'AK', 'Arizona' => 'AZ',
+          'Arkansas' => 'AR', 'California' => 'CA', 'Colorado' => 'CO', 
+          'Connecticut' => 'CT', 'Delaware' => 'DE',
+          'District of Columbia' => 'DC', 'Florida' => 'FL', 'Georgia' => 'GA',
+          'Hawaii' => 'HI', 'Idaho' => 'ID', 'Illinois' => 'IL',
+          'Indiana' => 'IN', 'Iowa' => 'IA', 'Kansas' => 'KS',
+          'Kentucky' => 'KY', 'Louisiana' => 'LA', 'Maine' => 'ME',
+          'Maryland' => 'MD', 'Massachusetts' => 'MA', 'Michigan' => 'MI', 
+          'Minnesota' => 'MN', 'Mississippi' => 'MS', 'Missouri' => 'MO', 
+          'Montana' => 'MT', 'Nebraska' => 'NE', 'Nevada' => 'NV',
+          'New Hampshire' => 'NH', 'New Jersey' => 'NJ', 'New Mexico' => 'NM', 
+          'New York' => 'NY', 'North Carolina' => 'NC', 'North Dakota' => 'ND',
+          'Ohio' => 'OH', 'Oklahoma' => 'OK', 'Oregon' => 'OR',
+          'Pennsylvania' => 'PA', 'Puerto Rico' => 'PR',
+          'Rhode Island' => 'RI', 'South Carolina' => 'SC',
+          'South Dakota' => 'SD', 'Tennessee' => 'TN', 'Texas' => 'TX',
+          'Utah' => 'UT', 'Vermont' => 'VT', 'Virginia' => 'VA',
+          'Washington' => 'WA', 'West Virginia' => 'WV', 'Wisconsin' => 'WI', 
+          'Wyoming' => 'WY'
+        }.sort_by { |name, code| name }
+      end
+      
+      def search_html
+        input = case @column.sql_type
+          when :boolean
+            opts = [['', nil]]
+            if @boolean_labels
+              opts << [@boolean_labels.first, true]
+              opts << [@boolean_labels.last, false]
+            else
+              opts << ['true', true]
+              opts << ['false', false]
+            end
+            @action_view.select("search", name, opts)
+          else
+            @action_view.text_field_tag("search[#{name}]", @search[name])
+        end
+        "<p><label>#{label}</label> <br/>#{input}</p>"
+      end
+    end
+  end
+  
+  class AdminAssistantColumn < Column
+    attr_reader :name
+    
+    def initialize(name)
+      @name = name.to_s
+    end
+    
+    def contains?(column_name)
+      column_name.to_s == @name
+    end
+    
+    class View < AdminAssistant::Column::View
+      def field_value(record)
+        nil
+      end
+    end
+  end
+  
+  class BelongsToColumn < Column
+    def initialize(belongs_to_assoc)
+      @belongs_to_assoc = belongs_to_assoc
+    end
+    
+    def associated_class
+      @belongs_to_assoc.klass
+    end
+    
+    def association_foreign_key
+      @belongs_to_assoc.association_foreign_key
+    end
+    
+    def contains?(column_name)
+      column_name.to_s == name
+    end
+    
+    def default_name_method
+      [:name, :title, :login, :username].detect { |m|
+        associated_class.columns.any? { |column| column.name.to_s == m.to_s }
+      }
+    end
+    
+    def name
+      @belongs_to_assoc.name.to_s
+    end
+    
+    def order_sql_field
+      sql = "#{@belongs_to_assoc.table_name}. "
+      sql << if default_name_method
+        default_name_method.to_s
+      else
+        @belongs_to_assoc.association_foreign_key
+      end
+    end
+    
+    class View < AdminAssistant::Column::View
+      def add_to_form(form)
+        form.select(
+          association_foreign_key,
+          associated_class.
+              find(:all).
+              sort_by { |model| model.send(default_name_method) }.
+              map { |model| [model.send(default_name_method), model.id] }
+        )
+      end
+    
+      def field_value(record)
+        assoc_value = record.send name
+        if assoc_value.respond_to?(:name_for_admin_assistant)
+          assoc_value.name_for_admin_assistant
+        elsif assoc_value && default_name_method
+          assoc_value.send default_name_method
+        end
+      end
+    end
+  end
+  
+  class DefaultSearchColumn < Column
+    attr_reader :terms
+    
+    def initialize(terms, model_class)
+      @terms, @model_class = terms, model_class
+    end
+    
+    def add_to_query(ar_query)
+      unless @terms.blank?
+        ar_query.boolean_join = :or
+        searchable_columns.each do |column|
+          ar_query.condition_sqls << "#{column.name} like ?"
+          ar_query.bind_vars << "%#{@terms}%"
+        end
+      end
+    end
+    
+    def searchable_columns
+      @model_class.columns.select { |column|
+        [:string, :text].include?(column.type)
+      }
+    end
+    
+    class View < AdminAssistant::Column::View
+      def search_html
+        @action_view.text_field_tag("search", @column.terms)
+      end
+    end
+  end
+  
+  class FileColumnColumn < Column
+    attr_reader :name
+    
+    def initialize(name)
+      @name = name.to_s
+    end
+    
+    def contains?(column_name)
+      column_name.to_s == @name
+    end
+    
+    class View < AdminAssistant::Column::View
+      def add_to_form(form)
+        form.file_field name
+      end
+      
+      def index_html(record)
+        @action_view.instance_variable_set :@record, record
+        @action_view.image_tag(
+          @action_view.url_for_file_column('record', @column.name)
+        )
+      end
+    end
+  end
+  
+  class PaperclipColumn < Column
+    attr_reader :name
+    
+    def initialize(name)
+      @name = name.to_s
+    end
+    
+    def contains?(column_name)
+      column_name.to_s == @name ||
+      column_name.to_s =~
+          /^#{@name}_(file_name|content_type|file_size|updated_at)$/
+    end
+    
+    class View < AdminAssistant::Column::View
+      def add_to_form(form)
+        form.file_field name
+      end
+      
+      def index_html(record)
+        @action_view.image_tag record.send(@column.name).url
+      end
+    end
+  end
+end

data/lib/admin_assistant/form_view.rb

@@ -0,0 +1,124 @@
+class AdminAssistant
+  class FormView
+    def initialize(record, admin_assistant, action_view)
+      @record, @admin_assistant, @action_view =
+          record, admin_assistant, action_view
+    end
+    
+    def action
+      if %w(new create).include?(controller.action_name)
+        'create'
+      else
+        'update'
+      end
+    end
+    
+    def after_column_html(column)
+      if after = render_from_custom_template("_after_#{column.name}_input")
+        after
+      else
+        helper_method = "after_#{column.name}_input"
+        if @action_view.respond_to?(helper_method)
+          @action_view.send(helper_method, @record)
+        end
+      end
+    end
+    
+    def column_html(column, rails_form)
+      hff = render_from_custom_template "_#{column.name}_input"
+      hff ||= column_html_from_helper_method(column)
+      hff ||= if settings.read_only.include?(column.name)
+        column.form_value(@record)
+      elsif column.respond_to?(:add_to_form)
+        column.add_to_form(rails_form)
+      else
+        virtual_column_html column
+      end
+      if ah = after_column_html(column)
+        hff << ah
+      end
+      hff
+    end
+    
+    def column_html_from_helper_method(column)
+      html_method = "#{column.name}_html_for_form"
+      if @action_view.respond_to?(html_method)
+        @action_view.send(html_method, @record)
+      end
+    end
+    
+    def column_names
+      settings.column_names ||
+          model_class.columns.reject { |ar_column|
+            %w(id created_at updated_at).include?(ar_column.name)
+          }.map { |ar_column|
+            @admin_assistant.column_name_or_assoc_name(ar_column.name)
+          }
+    end
+    
+    def columns
+      @admin_assistant.columns(column_names).map { |c|
+        c.view(@action_view, :input => settings.inputs[c.name.to_sym])
+      }
+    end
+    
+    def controller
+      @action_view.controller
+    end
+    
+    def extra_submit_buttons
+      settings.submit_buttons
+    end
+    
+    def form_for_args
+      args = {:url => {:action => action, :id => @record.id}}
+      unless @admin_assistant.paperclip_attachments.empty? &&
+             @admin_assistant.file_columns.empty?
+        args[:html] = {:multipart => true}
+      end
+      args
+    end
+    
+    def model_class
+      @admin_assistant.model_class
+    end
+    
+    def render_from_custom_template(slug)
+      template = File.join(
+        RAILS_ROOT, 'app/views', controller.controller_path, "#{slug}.html.erb"
+      )
+      if File.exist?(template)
+        @action_view.render(
+          :file => template,
+          :locals => {model_class.name.underscore.to_sym => @record}
+        )
+      end
+    end
+    
+    def settings
+      @admin_assistant.form_settings
+    end
+    
+    def submit_value
+      action.capitalize
+    end
+    
+    def title
+      (@record.id ? "Edit" : "New") + " #{@admin_assistant.model_class_name}"
+    end
+    
+    def virtual_column_html(column)
+      input_name = "#{model_class.name.underscore}[#{column.name}]"
+      input_type = settings.inputs[column.name.to_sym]
+      fv = column.form_value @record
+      if input_type
+        if input_type == :check_box
+          @action_view.send(:check_box_tag, input_name, '1', fv) +
+              @action_view.send(:hidden_field_tag, input_name, '0')
+        end
+      else
+        @action_view.send(:text_field_tag, input_name, fv)
+      end
+    end
+  end
+end