scaffolding_extensions 1.0.0

data/doc/advanced.txt

@@ -0,0 +1,154 @@
+Here are some advanced features of the plugin:
+
+== scaffold_session_value
+
+You can define this attribute in your model to control access to the model's
+objects based on a session variable.  For example, if you want to limit a users
+access via the scaffold to only objects that match his id, you can set the
+following in the model:
+
+  class Car < ActiveRecord::Base
+    @scaffold_session_value = :user_id
+  end
+
+Make sure that the session value is set to :user_id when the user logs in:
+
+  session[:user_id] = User.id
+
+Then, the user will only be able to see cars where car.user_id is equal to
+session[:user_id].  Any cars the user creates via the scaffolded forms will
+have user_id set correctly.
+
+You should make sure that :user_id is not in the @scaffold_fields for the model
+(which it will be by default).
+
+== Eager loading
+
+You can eagerly load associations when loading multiple model objects, via
+@scaffold_include. Here's an example scaffold_name (for an accounting entry):
+
+  def scaffold_name
+    "#{date.strftime('%Y-%m-%d')}-#{reference}-#{entity.name if entity}-#{debit_account.name if debit_account}-#{credit_account.name if credit_account}-#{money_amount}"
+  end
+
+Without @scaffold_include, this will cause 3 queries for each model object
+that calls scaffold_name.  However, if you add @scaffold_include to eagerly
+load the associations, there won't be any additionally queries:
+
+  @scaffold_include = [:entity, :credit_account, :debit_account]
+
+== Autocompleting
+
+Autocompleting is easy to set up in the model via:
+
+  @scaffold_use_auto_complete = true
+
+Any time the scaffold would use a select box to show a group of objects, it
+will instead use an autocompleting text box, allowing you to easily support a
+much greater number of objects (select boxes aren't good for collections with
+thousands of objects).  If the model doesn't have an SQL column named "name",
+you'll need to specify how to construct the SQL query for the object via:
+
+  @scaffold_auto_complete_options = {:sql_name=>'LOWER(name)', 
+    :format_string=>:substring,  :search_operator=>'LIKE', 
+    :results_limit=>10, :phrase_modifier=>:downcase}
+
+The defaults are shown.  You'll most likely need to change the :sql_name.  If
+you are using PostgreSQL, you'll probably want to include:
+
+  {:sql_name=>'name', :search_operator=>'ILIKE', :phrase_modifier=>:to_s}
+
+PostgreSQL can do case insensitive searching via ILIKE, and there is no reason
+to force the attribute or the search phrase to lowercase.
+
+You can get quite advanced, incorporating other tables if you use
+@scaffold_include.  Here's an example from an accounting application:
+
+  @scaffold_select_order = 'entries.date DESC, entities.name, accounts.name, debit_accounts_entries.name, entries.amount'
+  @scaffold_include = [:entity, :credit_account, :debit_account]
+  @scaffold_auto_complete_options = {:sql_name=>"reference || date::TEXT || entities.name ||  accounts.name || debit_accounts_entries.name || entries.amount::TEXT", :search_operator=>'ILIKE', :phrase_modifier=>:to_s}
+
+Note how :sql_name can pull in data from multiple tables, since they are
+specified via @scaffold_include.  Note that the syntax might be database
+specific (the accounting applation only supports PostreSQL).
+
+Autocompleting currently requires the Prototype library (prototype.js,
+effects.js, and controls.js).
+
+== Customization
+
+Scaffolding Extensions is extremely customizable.  The database layer is split
+from the presentation layer, and most of the interface between them has support
+for overriding based on either the association or action given.
+
+For example, if you want different fields shown on the show page than on the
+edit page (to make certain fields read only), you can define:
+
+  @scaffold_show_fields = [:name, :amount]
+  @scaffold_edit_fields = [:name]
+  
+Each of the different pages (e.g. new, browse, search, etc.) can have a
+different @scaffold_fields, @scaffold_select_order, or @scaffold_include via
+the above method.  You can also override any of those variables for a given
+association displayed on the edit page.  For example, let's say you have an 
+Employee model which belongs_to a Position model.  When you bring up the edit
+page for the employee, you will have a select box with all of the positions
+shown by default (with the currently associated position selected by default).
+This select box by default uses the @scaffold_select_order and
+@scaffold_include of the Position model, but you can override it just for its
+appearance on the employee's edit page via:
+  
+  class Employee < ActiveRecord::Base
+    @scaffold_position_select_order_association = ...
+    @scaffold_position_include_association = ...
+  end
+
+You can even change how the find is performed by defining a class method:
+
+  class Employee < ActiveRecord::Base
+    def self.scaffold_position_association_find_objects(options)
+      # This will be called to get the collection of positions
+      # for the select box.  The object on the edit page is in
+      # options[:object], in case you want to use that
+      # to filter the selection of possible objects
+    end
+  end
+
+This barely scratches the surface of customization possibilities, see the RDoc
+for details on which methods can be customized in this manner.
+
+== has_and_belongs_to_many scaffolding
+
+Scaffolding Extensions scaffolds all has_and_belongs_to_many associations via
+links on the edit page.  You can limit which associations are scaffolded via
+the model's @scaffold_habtm_associations.  By default, habtm scaffolding is
+enabled via a separate page with two select boxes, one choosing objects not
+currently associated that can be added, and the other showing currently
+associated objects that removed from the association.
+
+It is possible to change this to scaffold habtm associations on the edit page
+via a couple of Ajax enabled controls.  This is set with
+the model's @scaffold_habtm_with_ajax variable.  With that variable set,
+directly under the main edit form for the model will be select boxes with
+possible objects to associate (or autocompleting text boxes if the
+association's model uses autocompleting), as well as a button that adds those
+objects to the association via Ajax.  There is also a list of currently
+associated objects that can be removed from the associated via Ajax.  This
+allows for quick modification of habtm associations.
+
+HABTM Ajax functionality currently requires the Prototype library
+(prototype.js).
+
+== merge scaffolding
+
+By default, Scaffolding Extensions will produce a merge scaffold for every
+model.  Merging object A into object B will take all of the has_many and
+has_and_belongs_to_many association objects for object A and will instead
+associated them with object B.  It will then delete object B.  This can be used
+to fix issues caused by database denormalization.
+
+== search scaffolding
+
+By default, Scaffolding Extensions will produce a simple search scaffold for
+every model.  It will allow searching by substring for columns of type :text or
+:string, and exact matches for other columns.

data/doc/camping.txt

@@ -0,0 +1,25 @@
+Camping doesn't have a defined folder structure for models, so
+scaffold_all_models shouldn't be used unless you pass the :only option, which
+gives a list of models to scaffold.
+
+To use this plugin after installing the gem:
+
+  require 'scaffolding_extensions'
+
+If you want to use it without installing the gem, add this before requiring
+it:
+
+  $:.unshift('scaffolding_extensions/lib')
+
+To use the plugin, inside your app's Controllers module, you need to define
+a subclass of scaffold_R, and call one of the scaffold methods inside of it.
+For example:
+
+  Camping.goes :Cse
+  module Cse::Controllers
+    class Admin < scaffold_R("/admin")
+      scaffold_all_models :only=>[Model1, Model2, Model3]
+    end
+  end
+
+The path given to scaffold_R will be the root of the plugin.

data/doc/controller_spec.txt

@@ -0,0 +1,20 @@
+To work with Scaffolding Extensions, the controller class needs to define the
+following methods:
+
+Instance Methods
+----------------
+scaffold_flash
+scaffold_method_not_allowed
+scaffold_redirect_to(url)
+scaffold_render_template(action, options = {}, render_options = {})
+scaffold_request_action
+scaffold_request_env
+scaffold_request_id
+scaffold_request_method
+scaffold_request_param(v)
+scaffold_session
+scaffold_url(action, options = {})
+
+Class Methods
+-------------
+scaffolding_setup_helper

data/doc/conversion.txt

@@ -0,0 +1,102 @@
+Conversion from an svn revision prior to 90 to the current version of
+Scaffolding Extensions can be very easy or fairly tedious, depending on how
+much you relied on the implementation of the older version.
+
+Here's a list of things to check and fix, in the order of expected use:
+
+- @scaffold_fields is now a list of symbols and not a list of strings.  Other
+variables that let you choose from fields or associations also take symbols
+instead of strings, such as @scaffold_associations, @scaffold_column_types,
+and @scaffold_column_options_hash. Variables that are used directly in the SQL
+string, such as @scaffold_select_order, are still strings.
+
+- The scaffold templates no longer set the title of the page in an h1 tag.
+Now, that is done by the layout.  The title of the page is stored in
+@scaffold_title, and if you use a custom layout, you should incorporate that.
+
+- The scaffold method has fewer options and now takes the model class.  The
+only options available are :except and :only.  So instead of "scaffold :album",
+you use "scaffold Album".  It automatically scaffolds all habtm associations
+for the model (though you can override that with the model's
+@scaffold_habtm_associations). You can no longer scaffold without a suffix, and
+the suffix used is set by the class's @scaffold_name (defaulting to
+name.underscore).
+
+- The scaffold_habtm method no longer has options and now takes the model
+class and the association as a symbol.  So instead of 
+"scaffold_habtm :album, :artist" you use "scaffold_habtm Album, :artists".
+scaffold_habtm no longer scaffolds both ways, so you'll need two separate calls
+if you want it scaffolded in both directions.
+
+- The scaffold_all_models method only accepts a hash and not a list of models
+to scaffold.  Keys of the hash (other than :except and :only) should be
+model classes, defining options for each model.  :except and :only take lists
+of models instead of symbols.  options for each model can only be :except and
+:only.
+
+- The scaffolded pages no longer set variables such as @artist and @artists or
+variables like @scaffold_action. Now, they use the generic @scaffold_object and
+@scaffold_objects for holding model objects.  Variables that will definitely be
+defined are @scaffold_suffix, @scaffold_class, and @scaffold_options.
+
+- Overriding defaults for ActiveRecord classes is now done through 
+"::ActiveRecord::Base::SCAFFOLD_OPTIONS[option_name]", and the option names
+have changed.  Names for instance variables inside the class should still work.
+See the RDoc for details.
+
+- Setting auto_complete_skip_style is now a singleton option and not a
+per-model options.  It is set with
+"ScaffoldingExtensions.auto_complete_skip_style = true".
+
+- Scaffolded methods are no longer prefixed with _ and then aliased.  If you
+want to override a method but still call it later, alias it manually and 
+overwrite it to call the aliased version.
+
+- There is no ability to generate code, as eval is no longer used.  All dynamic
+methods are created with define_method.  This makes debugging much easier, and
+should make things quite a bit faster.
+
+- If you set the scaffold_fields by using a method instead of an instance
+variable, you'll have problems.  Switch to using instance variables for
+@scaffold_fields, @scaffold_select_order, etc..  If you want to override them
+for specific cases (scaffold_new_fields), it is ok to use a function for that,
+though I would still recommend using a variable (@scaffold_new_fields).
+
+- If you called methods such as scaffold_new_fields or
+scaffold_browse_select_order, you'll need to change those to
+scaffold_fields(:new) and scaffold_select_order(:browse).
+
+- scaffold_fields, scaffold_select_order, and scaffold_include methods all
+take an argument now, specifying the action being used, though to make things
+easier the argument has a default (:default).
+
+- all_models is now a method of ScaffoldExtensions, not of ActiveRecord::Base,
+and it returns model classes, not model name strings.
+
+- render_#{suffix}_scaffold is no longer called, now just
+scaffold_render_template is used.
+
+- All methods adding by Scaffolding Extensions start with scaffold.  If you
+used a method added by Scaffolding Extensions that didn't start with
+scaffold, it has definitely been renamed.
+
+- It is no longer possible to use scaffold_associations_path or
+scaffold_habtm_ajax_path for the model as those are now inline templates.
+
+- Rails' form tag helpers are no longer used, so setting some options (such as
+:size for a text area) no longer works.  You must specify html options (such as
+:cols and :rows) instead.
+
+- Fields named "password" are no longer set to be of input type password by
+default (that can be changed via @scaffold_column_types).
+
+I recommend searching for "scaffold" inside all of your application's files,
+and making sure every usage conforms to the current version's API.
+
+If you can't upgrade to the new version of the plugin and you want to use the
+old version, use the following svn revision depending on the version of Rails
+you are using:
+
+Rails 2.0: svn revision 89
+Rails 1.2: svn revision 81
+Rails 1.1: svn revision 61

data/doc/model_spec.txt

@@ -0,0 +1,54 @@
+To work with Scaffolding Extensions, the model class needs to define the
+following methods:
+
+Instance Methods
+----------------
+scaffold_error_messages
+scaffold_id
+scaffold_name
+scaffold_name_with_id
+scaffold_value(field)
+
+Class Methods
+-------------
+scaffold_add_associated_objects(association, object, options, *associated_object_ids)
+scaffold_associated_human_name(association)
+scaffold_associated_name(association)
+scaffold_associated_objects(association, object, options)
+scaffold_association_find_object(association, id, options)
+scaffold_association_find_objects(association, options)
+scaffold_association_list_class
+scaffold_association_type(association)
+scaffold_association_use_auto_complete(association)
+scaffold_associations
+scaffold_auto_complete_associations
+scaffold_auto_complete_find(phrase, options = {})
+scaffold_browse_find_objects(options)
+scaffold_column_name(column_name)
+scaffold_column_options(column_name)
+scaffold_column_type(column_name)
+scaffold_destroy(object)
+scaffold_field_id(field)
+scaffold_field_wrapper
+scaffold_fields(action)
+scaffold_find_object(action, id, options)
+scaffold_find_objects(action, options)
+scaffold_form_wrapper
+scaffold_habtm_associations
+scaffold_habtm_with_ajax
+scaffold_human_name
+scaffold_load_associations_with_ajax
+scaffold_merge_records(from, to, options)
+scaffold_name
+scaffold_new_associated_object_values(association, record)
+scaffold_new_object(attributes, options)
+scaffold_remove_associated_objects(association, object, options, *associated_object_ids)
+scaffold_save(action, object)
+scaffold_search(options)
+scaffold_search_null_options
+scaffold_search_object(attributes = {})
+scaffold_show_association_links?(association)
+scaffold_table_class(type)
+scaffold_unassociated_objects(association, object, options)
+scaffold_update_attributes(attributes, object)
+scaffold_use_auto_complete

data/doc/ramaze.txt

@@ -0,0 +1,20 @@
+To use this plugin after installing the gem:
+
+  require 'scaffolding_extensions'
+
+If you want to use it without installing the gem, add this before requiring
+it:
+
+  $:.unshift('scaffolding_extensions/lib')
+
+If your models are not located in model/, it is easiest to let Scaffolding
+Extensions know about them manually (this is only necessary if you are using
+scaffold_all_models without :only):
+
+  ScaffoldingExtensions.all_models = [Model1, Model2, Model3]
+
+You should add this code after your models have been loaded but before your
+controllers have been loaded.
+
+Also, note that Scaffolding Extensions uses the :Erubis engine in Ramaze,
+so you must have Erubis installed to use it.

data/doc/sinatra.txt

@@ -0,0 +1,20 @@
+Sinatra doesn't have a defined folder structure for models, so
+scaffold_all_models shouldn't be used unless you pass the :only option, which
+gives a list of models to scaffold.
+
+Sinatra has a defined structure for plugins.  To use it, put the plugin in the
+vendor directory of your application and it should be picked up automatically.
+Note that if you doing something Sinatra doesn't like (such as using ruby-style
+to deploy the Sinatra application, or just changing $0), this probably won't
+work, so you need to require it manually.
+
+To use the plugin if installing the gem:
+
+  require 'scaffolding_extensions'
+
+To use the plugin, just call one of the root level scaffold methods with the
+path at which you want the plugin mounted:
+
+  scaffold '/admin', Model1
+  scaffold_habtm '/admin', Model1, :things
+  scaffold_all_models '/admin', :only=>[Model1, Model2, Model3]

data/doc/testing.txt

@@ -0,0 +1,12 @@
+If you are using Rails and want some basic generic tests, looking the test
+folder for details on the Rails testing helper methods (e.g.
+test_scaffold_all_models).
+
+There is an automated test suite that tests the plugin against all supported
+web frameworks and ORMs.  You can get it via svn at:
+
+  svn://code.jeremyevans.net/scaffolding_extensions_test
+  
+It requires the ruby-sytle, hpricot, and mongrel gems, and does black box
+testing of the plugin by running a web crawler against a running application
+that uses the plugin.

data/lib/scaffolding_extensions.rb

@@ -0,0 +1,89 @@
+require 'set'
+
+# This is the base module for the plugin.  It has some constants that can be
+# changed:
+#
+# * TEMPLATE_DIR - the directory with the scaffold templates
+# * DEFAULT_METHODS - the default methods added by the scaffolding
+#
+# If you include the contents of auto_complete.css in your stylesheet, set
+# "auto_complete_skip_style = true", so the stylesheet isn't added for every
+# autocompleting text box.
+#
+# Scaffolding Extensions attempts to determine which framework/ORM you are
+# using and load the support for it (if it is supported).
+module ScaffoldingExtensions
+  AUTO_COMPLETE_CSS = <<-END
+    <style type='text/css'>
+      div.auto_complete {
+        width: 350px;
+        background: #fff;
+      }
+      div.auto_complete ul {
+        border:1px solid #888;
+        margin:0;
+        padding:0;
+        width:100%;
+        list-style-type:none;
+      }
+      div.auto_complete ul li {
+        margin:0;
+        padding:3px;
+      }
+      div.auto_complete ul li.selected { 
+        background-color: #ffb; 
+      }
+      div.auto_complete ul strong.highlight { 
+        color: #800; 
+        margin:0;
+        padding:0;
+      }
+    </style>
+  END
+  ROOT = File.dirname(File.dirname(__FILE__))
+  TEMPLATE_DIR = File.join(ROOT, "scaffolds")
+  DEFAULT_METHODS = [:manage, :show, :delete, :edit, :new, :search, :merge, :browse]
+  MODEL_SUPERCLASSES = []
+  
+  @auto_complete_skip_style = false
+    
+  class << self
+    attr_accessor :auto_complete_skip_style
+    attr_writer :all_models, :model_files
+
+    def all_models
+      return @all_models if @all_models
+      possible_models = model_files.collect{|file|File.basename(file).sub(/\.rb\z/, '')}.collect{|m| m.camelize.constantize}
+      possible_models.reject{|m| MODEL_SUPERCLASSES.reject{|klass| !m.ancestors.include?(klass)}.length == 0}
+    end
+
+    # The stylesheet for the autocompleting text box, or the empty string
+    # if auto_complete_skip_style is true.
+    def auto_complete_css
+      auto_complete_skip_style ? '' : AUTO_COMPLETE_CSS
+    end
+    
+    # The javascript library to use (defaults to Prototype)
+    def javascript_library=(jslib)
+      require "scaffolding_extensions/#{jslib.downcase}_helper"
+      ScaffoldingExtensions::Helper.send(:include, const_get("#{jslib}Helper"))
+    end
+  end
+end
+
+require 'scaffolding_extensions/controller'
+require 'scaffolding_extensions/helper'
+require 'scaffolding_extensions/meta_controller'
+require 'scaffolding_extensions/meta_model'
+require 'scaffolding_extensions/model'
+require 'scaffolding_extensions/overridable'
+
+require 'scaffolding_extensions/controller/action_controller' if defined? ActionController::Base
+require 'scaffolding_extensions/controller/camping' if defined? Camping::Controllers
+require 'scaffolding_extensions/controller/ramaze' if defined? Ramaze::Controller
+require 'scaffolding_extensions/controller/sinatra' if defined? Sinatra
+
+require 'scaffolding_extensions/model/active_record' if defined? ActiveRecord::Base
+require 'scaffolding_extensions/model/data_mapper' if defined? DataMapper::Base
+
+ScaffoldingExtensions.javascript_library = 'Prototype'