clevic 0.8.0 → 0.11.1

data/lib/clevic/item_delegate.rb

@@ -11,53 +11,52 @@ end
 module Clevic
 
 class ItemDelegate < Qt::ItemDelegate
+  attr_reader :field
   
-  def initialize( parent )
-    super
+  def initialize( parent, field )
+    super( parent )
+    @field = field
   end
   
-  # This catches the event that begins the edit process.
-  # Not used at the moment.
-  def editorEvent ( event, model, style_option_view_item, model_index )
-    #~ if $options[:debug]
-      #~ puts "editorEvent"
-      #~ puts "event: #{event.inspect}"
-      #~ puts "model: #{model.inspect}"
-      #~ puts "style_option_view_item: #{style_option_view_item.inspect}"
-      #~ puts "model_index: #{model_index.inspect}"
-    #~ end
-    super
+  def attribute
+    field.attribute
   end
   
-  def createEditor( parent_widget, style_option_view_item, model_index )
-    if model_index.metadata.type == :date
-      # not going to work here because being triggered by
-      # an alphanumeric keystroke (as opposed to F4)
-      # will result in the calendar widget being opened.
-      #~ Qt::CalendarWidget.new( parent_widget )
-      super
-    else
-      super
-    end
+  def entity_class
+    field.entity_class
   end
   
-  #~ def setEditorData( editor, model_index )
-    #~ editor.value = model_index.gui_value
-  #~ end
-  
-  #~ def setModelData( editor, abstract_item_model, model_index )
-    #~ model_index.gui_value = editor.value
-    #~ emit abstract_item_model.dataChanged( model_index, model_index )
-  #~ end
+  def find_options
+    field.find_options
+  end
   
+  # Figure out where to put the editor widget, taking into
+  # account the sizes of the headers
   def updateEditorGeometry( editor, style_option_view_item, model_index )
-    # figure out where to put the editor widget, taking into
-    # account the sizes of the headers
     rect = style_option_view_item.rect
     rect.set_width( [editor.size_hint.width,rect.width].max )
     rect.set_height( editor.size_hint.height )
     editor.set_geometry( rect )
   end
+
+  # This catches the event that begins the edit process.
+  #~ def editorEvent ( event, model, style_option_view_item, model_index )
+  #~ end
+
+  # This is called when one of the EditTriggers is pressed. So
+  # it's only good for opening a generic keystroke editor, not
+  # a specific one, eg a calendar-style date editor.
+  #~ def createEditor( parent_widget, style_option_view_item, model_index )
+  #~ end
+  
+  # Set the data for the given editor widget
+  #~ def setEditorData( editor_widget, model_index )
+  #~ end
+  
+  # Set the data for the given model and index from the given
+  #~ def setModelData( editor_widget, abstract_item_model, model_index )
+  #~ end
+  
 end
 
 end

data/lib/clevic/model_builder.rb

@@ -8,30 +8,57 @@ require 'clevic/field.rb'
 module Clevic
 
 =begin rdoc
-This is used to define a set of fields in a UI, any related tables,
-restrictions on data entry, formatting and that kind of thing. Essentially it
-defines a DSL for building a TableModel.
 
-Optional specifiers are:
-* :sample is used to size the columns. Will default to some hopefully sensible value from the db.
-* :format is something that can be understood by strftime (for time and date
-  fields) or understood by % (for everything else). It can also be a Proc
-  that has one parameter - the current entity.
-* :alignment is one of Qt::TextAlignmentRole, ie Qt::AlignRight, Qt::AlignLeft, Qt::AlignCenter
-* :set is the set of strings that are accepted by a RestrictedDelegate
+== View definition
 
-In the case of relational fields, all other options are passed to ActiveRecord::Base#find
+Clevic::ModelBuilder defines the DSL used to create a UI definition (which is 
+actually a set of Clevic::Field instances), including any related tables, 
+restrictions on data entry, formatting and so on. The intention was to make
+specifying a UI as painless as possible, with framework overhead only where
+you need it.
 
-For example, the UI for a model called Entry could be defined like this:
+To that end, there are 2 ways to define UIs:
 
-  # inherit from Clevic::Record, which itself inherits from ActiveRecord::Base
-  class Entry < Clevic::Record
+- an Embedded View as part of the ActiveRecord object (which is useful if you 
+  want minimal framework overhead). Just show me the data, dammit.
+
+- a Separate View in a separate class (which is useful when you want several 
+  diffent views of the same underlying table). I want a neato-nifty UI that does
+  (relatively) complex things.
+
+I've tried to consistently refer to an instance of an ActiveRecord::Base subclass
+as an 'entity'.
+
+==Embedded View
+Minimal embedded definition is
+
+  class Position < ActiveRecord::Base
+    include Clevic::Record
+  end
+
+which will build a fairly sensible default UI from the
+entity's metadata. Obviously you can use open classes to do
+
+  class Position
+    include Clevic::Record
+  end
+
+where Position is previously defined to inherit from ActiveRecord::Base.
+
+A full-featured UI for an entity called Entry (part of an accounting database)
+could be defined like this:
+
+  class Entry < ActiveRecord::Base
+    include Clevic::Record
+    
+    # ActiveRecord foreign key definition
     belongs_to :debit, :class_name => 'Account', :foreign_key => 'debit_id'
+    # ActiveRecord foreign key definition
     belongs_to :credit, :class_name => 'Account', :foreign_key => 'credit_id'
 
     define_ui do
-      # :format is optional
-      plain       :date, :format => '%d-%h-%y'
+      # :format and :edit_format are optional, in fact these are the defaults
+      plain       :date, :format => '%d-%h-%y', :edit_format => '%d-%h-%Y'
       plain       :start, :format => '%H:%M'
       plain       :amount, :format => '%.2f'
       # :set is mandatory for a restricted field
@@ -44,20 +71,27 @@ For example, the UI for a model called Entry could be defined like this:
         tooltip 'Is VAT included?'
       end
       
-      # distinct will show other values for this field in the combo
+      # distinct will retrieve from the table all other values for this field
+      # and display them in the combo.
       distinct    :description, :conditions => 'now() - date <= interval( 1 year )'
 
       # this is a read-only field
       plain       :origin, :read_only => true
       
-      # for these, :format will be a dotted attribute accessor for the related
+      # :format is an attribute on the related
       # ActiveRecord entity, in this case an instance of Account
-      relational  :debit, :format => 'name', :class_name => 'Account', :conditions => 'active = true', :order => 'lower(name)'
-      relational  :credit, :format => 'name', :class_name => 'Account', :conditions => 'active = true', :order => 'lower(name)'
+      # :order is an ActiveRecord option to find, defining the order in which related entries will be displayed.
+      # :conditions is an ActiveRecord option to find, defining the subset of related entries to be displayed.
+      relational  :debit, :format => 'name', :conditions => 'active = true', :order => 'lower(name)'
+      relational  :credit, :format => 'name', :conditions => 'active = true', :order => 'lower(name)'
       
-      # or like this to have an on-the-fly transform
-      # item will be an instance of Account
-      relational  :credit, :format => lambda {|item| item.name.downcase}, :class_name => 'Account', :conditions => 'active = true', :order => 'lower(name)', :sample => 'Leilani Member Loan'
+      # or like this to have an on-the-fly transform. item will be an instance of Account.
+      # This also takes a block parameter
+      relational :credit do |field|
+        field.format = lambda {|item| item.name.downcase}
+        field.conditions = 'active = true'
+        field.order = 'lower(name)'
+      end
       
       # this is a read-only display field from a related table
       # the Entry class should then define a method called currency
@@ -72,58 +106,215 @@ For example, the UI for a model called Entry could be defined like this:
       # You can also use a Proc for :display
       plain :some_field, :display => 'currency.rate', :label => 'Exchange Rate'
       
-      # this is optional
+      # this is optional. By default all records in id order will be displayed.
       records :order => 'date,start'
       
       # could also be like this, where a..e are instances of Entry
       records [ a,b,c,d,e ]
     end
   end
+
+== Separate View
+
+To define a separate ui class, do something like this:
+  class Prospect < Clevic::View
+    
+    # This is the ActiveRecord::Base descendant
+    entity_class Position
+    
+    # This must return a ModelBuilder instance, which is made easier
+    # by putting the block in a call to model_builder.
+    #
+    # With no parameter, the block
+    # will be evaluated in the context of a Clevic::ModelBuilder instance,
+    # otherwise the parameter will have the Clevic::ModelBuilder instance
+    # so you can still access the surrounding scope.
+    def define_ui
+      model_builder do |mb|
+        # use the define_ui block from Position
+        mb.exec_ui_block( Position )
+        
+        # use a different recordset
+        mb.records :conditions => "status in ('prospect','open')", :order => 'date desc,code'
+      end
+    end
+  end
   
-For ActiveRecord::Base classes, ModelBuilder knows how to build a
-fairly sensible default UI. For small tweaks, something like this
-can be used (where Subscriber is already defined elsewhere as a subclass
-of ActiveRecord::Base):
-  class Subscriber
-    post_default_ui do
-      plain :password # this field does not exist in the DB
-      hide :password_salt # these should be hidden
-      hide :password_hash
+And you can even inherit UIs:
+
+  class Extinct < Prospect
+    def define_ui
+      # reuse all UI definitions from Prospect
+      super
+      # and again another recordset
+      model_builder do |mb|
+        mb.records :conditions => "status in ('dead')", :order => 'date desc,code'
+      end
+    end
+  end
+
+Obviously you can use any of the Clevic::ModelBuilder calls described above, and exemplified
+in the embedded example, inside of the model_builder block.
+
+== DSL detail
+
+This section describes the syntax of the DSL.
+
+=== Field Types and specifiers
+
+There are only a few field types, with lots of options. All field definitions
+start with a field type, have an attribute, and take either a hash of options,
+or a block for options. If the block specifies a parameter, an instance of
+Clevic::Field will be passed. If the block has no parameter, it will be
+evaluated in the context of a Clevic::Field instance. All the options specified
+can use DSL-style acessors (no assignment =) or assignment statement.
+
+  plain
+is an ordinary editable field. Boolean values are displayed as checkboxes.
+
+  relational
+displays a set of values pulled from a belongs_to (many-to-one) relationship.
+In other words all the possible related entities that this one could belong_to. Some
+concise representation of the related entities are displayed in a combo box.
+:display is mandatory. All options applicable to ActiveRecord::Base#find can also be passed.
+
+  distinct
+fetches the set of values already in the field, so you don't have to re-type them.
+New values are added in the text field part of the combo box. There is some prefix matching.
+
+  restricted
+is a combo box that is not editable in the text field part - the user must select
+a value from the :set (an array of strings) supplied. If :set has a hash as its value, the field
+will display the hash values, and the hash keys will be stored in the db.
+
+  hide
+you won't see this field. Actually, it's only useful after a default_ui, or pulling the
+definition from somewhere else. It may go away and be replaced by remove.
+
+=== Attribute
+
+The attribute symbol is required, and is the first parameter after the field type. It must refer
+to a method already defined in the entity. In other words any of:
+- a db column
+- a relationship (belongs_to, has_many, etc)
+- a plain method that takes no parameters.
+
+will work. Named scopes might also work, but I haven't tried them yet.
+
+You can do things like this:
+
+  plain :entries, :label => 'First Entry', :display => 'first.date', :format => '%d-%b-%y'
+  plain :entries, :label => 'Last Entry', :display => 'last.date', :format => '%d-%b-%y'
+
+Where the attribute fetches a collection of related entities, and :display will cause
+exactly one of those values to be passed to :format.
+
+=== Options
+
+Optional specifiers follow the attribute, as hash parameters, or as a block. Many of them will
+accept as a value one of:
+- String, some kind of value
+- Symbol, referring to a method on the entity
+- Proc which takes the entity as a parameter
+
+See Clevic::Field properties for available options.
+
+=== Menu Items
+
+You can define view/model specific actions ( an Action is Qt talk for menu items and shortcuts).
+These will be added to the Edit menu, show up on context-click in the table
+display, and can have optional keyboard shortcuts:
+
+  def define_actions( table_view, action_builder )
+    action_builder.action :smart_copy, 'Smart Copy', :shortcut => 'Ctrl+"' do
+      # a method in the class containing define_actions
+      # view.current_index.entity will return the entity instance.
+      smart_copy( view )
+    end
+    
+    action_builder.action :invoice_from_project, 'Invoice from Project', :shortcut => 'Ctrl+Shift+I' do
+      # a method in the class containing define_actions
+      invoice_from_project( view.current_index, view )
     end
   end
+  
+=== Notifications
+
+The following method will be called whenever data is changed, ie a field edit is completed:
+
+  def notify_data_changed( table_view, top_left_model_index, bottom_right_model_index )
+  end
+  
+Key presses will be sent here:
+
+  def notify_key_press( table_view, key_press_event, current_model_index )
+  end
+
+The above may also be defined as class methods on an entity class.
+
+=== Tab Order
+
+Using an embedded definition, tab order in the browser is defined by the order in which view definitions
+are encountered. Which is really useful if you want to have several view definitions in one file and
+just execute clevic on that file.
+
+For more complex situations where your code needs to be separated into
+multiple files, as is traditional and useful for most non-trivial projects,
+the order can be accessed in Clevic::View.order, and specified by
+
+  Clevic::View.order = [Position, Target, Account]
 
-Subclasses of Clevic::Record may also implement <tt>self.key_press_event( event, current_index, view )</tt>
-and <tt>self.data_changed( top_left_index, bottom_right_index, view )</tt> methods so that
-they can respond to editing events and do Neat Stuff.
 =end
 class ModelBuilder
   
-  # Create a definition for model_class (subclass of ActiveRecord::Base
-  # or Clevic::Record). Then execute block using self.instance_eval.
-  # The builder will construct a default TableModel from the model_class
-  # unless can_build_default == false
-  def initialize( model_class, can_build_default = true, &block )
-    @model_class = model_class
+  # Create a definition for entity_view (subclass of Clevic::View).
+  # Then execute block using self.instance_eval.
+  def initialize( entity_view, &block )
+    @entity_view = entity_view
     @auto_new = true
     @read_only = false
     @fields = []
-    init_from_model( model_class, can_build_default, &block )
+    exec_ui_block( &block )
+  end
+  
+  attr_accessor :entity_view
+  
+  # execute a block containing method calls understood by Clevic::ModelBuilder
+  # arg can be something that responds to define_ui_block,
+  # or just the block will be executed. If both are present,
+  # values in the block will overwrite values in arg's block.
+  def exec_ui_block( arg = nil, &block )
+    if !arg.nil? and arg.respond_to?( :define_ui_block )
+      exec_ui_block( &arg.define_ui_block )
+    end
+
+    unless block.nil?
+      if block.arity == -1
+        instance_eval( &block )
+      else
+        block.call( self )
+      end
+    end
+    self
   end
   
-  # The collection of visible Clevic::Field objects
+  # The collection of Clevic::Field instances where visible == true.
+  # the visible may go away.
   def fields
     @fields.reject{|x| !x.visible}
   end
   
-  # return the index of the named field
+  # return the index of the named field in the collection of fields.
   def index( field_name_sym )
     retval = nil
     fields.each_with_index{|x,i| retval = i if x.attribute == field_name_sym.to_sym }
     retval
   end
   
-  # the ActiveRecord::Base or Clevic::Record class
-  attr_reader :model_class
+  # The ActiveRecord::Base subclass
+  def entity_class
+    @entity_view.entity_class
+  end
   
   # set read_only to true
   def read_only!
@@ -135,35 +326,36 @@ class ModelBuilder
     @auto_new = bool
   end
   
+  # should this table automatically show a new blank record?
   def auto_new?; @auto_new; end
 
   # an ordinary field, edited in place with a text box
   def plain( attribute, options = {}, &block )
-    # get values from block, if it's there
-    options = gather_block( options, &block )
-    
-    read_only_default( attribute, options )
-    @fields << Clevic::Field.new( attribute.to_sym, model_class, options )
+    read_only_default!( attribute, options )
+    @fields << Clevic::Field.new( attribute.to_sym, entity_class, options, &block )
   end
   
-  # edited with a combo box containing all previous entries in this field
+  # Returns a Clevic::Field with a DistinctDelegate, in other words
+  # a combo box containing all values for this field from the table.
   def distinct( attribute, options = {}, &block )
-    # get values from block, if it's there
-    options = gather_block( options, &block )
-    
-    field = Clevic::Field.new( attribute.to_sym, model_class, options )
-    field.delegate = DistinctDelegate.new( nil, attribute, model_class, options )
+    field = Clevic::Field.new( attribute.to_sym, entity_class, options, &block )
+    field.delegate = DistinctDelegate.new( nil, field )
     @fields << field
   end
 
-  # edited with a combo box, but restricted to a specified set
+  # Returns a Clevic::Field with a RestrictedDelegate, 
+  # a combo box, but restricted to a specified set, from the :set option.
   def restricted( attribute, options = {}, &block )
-    # get values from block, if it's there
-    options = gather_block( options, &block )
     
-    raise "restricted must have a set" unless options.has_key?( :set )
-    field = Clevic::Field.new( attribute.to_sym, model_class, options )
-    field.delegate = RestrictedDelegate.new( nil, attribute, model_class, options )
+    field = Clevic::Field.new( attribute.to_sym, entity_class, options, &block )
+    raise "field #{attribute} restricted must have a set" if field.set.nil?
+    
+    # TODO this really belongs in a separate 'map' field
+    if field.set.is_a? Hash
+      field.format = lambda{|x| field.set[x]}
+    end
+    
+    field.delegate = RestrictedDelegate.new( nil, field )
     @fields << field
   end
 
@@ -172,49 +364,58 @@ class ModelBuilder
   # if options[:format] has a value, it's used either as a block
   # or as a dotted path
   def relational( attribute, options = {}, &block )
-    unless options.has_key? :class_name
-      options[:class_name] = model_class.reflections[attribute].class_name || attribute.to_s.classify
+    field = Clevic::Field.new( attribute.to_sym, entity_class, options, &block )
+    if field.class_name.nil?
+      field.class_name = entity_class.reflections[attribute].class_name || attribute.to_s.classify
     end
     
-    # get values from block, if it's there
-    options = gather_block( options, &block )
-    
     # check after all possible options have been collected
-    raise ":display must be specified" if options[:display].nil?
-    
-    field = Clevic::Field.new( attribute.to_sym, model_class, options )
-    field.delegate = RelationalDelegate.new( nil, field.attribute_path, options )
+    raise ":display must be specified" if field.display.nil?
+    field.delegate = RelationalDelegate.new( nil, field )
     @fields << field
   end
 
   # mostly used in the new block to define the set of records
   # for the TableModel, but may also be
   # used as an accessor for records.
-  def records( *args )
+  def records( args = {} )
     if args.size == 0
       get_records
     else
-      set_records( args[0] )
+      set_records( args )
     end
   end
 
-  # make sure this field doesn't show up
-  # mainly intended to be called after default_ui has been called
+  # Tell this field not to show up in the UI.
+  # Mainly intended to be called after default_ui has been called.
   def hide( attribute )
     field( attribute ).visible = false
   end
 
   # Build a default UI. All fields except the primary key are displayed
   # as editable in the table. Any belongs_to relations are used to build
-  # combo boxes.
-  # Try to use a sensible :display option for the related class. In order:
-  # the name of the class, name, title, username
-  # order by the primary key. The class can use post_default_ui( &block )
-  # to do small tweaks.
+  # combo boxes. Default ordering is the primary key.
+  # Subscriber is already defined elsewhere as a subclass
+  # of ActiveRecord::Base:
+  #   class Subscriber
+  #     include Clevic::Record
+  #     define_ui do
+  #       default_ui
+  #       plain :password # this field does not exist in the DB
+  #       hide :password_salt # these should be hidden
+  #       hide :password_hash
+  #     end
+  #   end
+  #
+  # An attempt to use a sensible :display option for the related class. In order:
+  # * the name of the class
+  # * :name
+  # * :title
+  # * :username
   def default_ui
     # combine reflections and attributes into one set
-    reflections = model_class.reflections.keys.map{|x| x.to_s}
-    ui_columns = model_class.columns.reject{|x| x.name == model_class.primary_key }.map do |column|
+    reflections = entity_class.reflections.keys.map{|x| x.to_s}
+    ui_columns = entity_class.columns.reject{|x| x.name == entity_class.primary_key }.map do |column|
       # TODO there must be a better way to do this
       att = column.name.gsub( /_id$/, '' )
       if reflections.include?( att )
@@ -230,16 +431,19 @@ class ModelBuilder
     
     # build columns
     ui_columns.each do |column|
-      if model_class.reflections.has_key?( column.to_sym )
+      if entity_class.reflections.has_key?( column.to_sym )
         begin
-          reflection = model_class.reflections[column.to_sym]
+          reflection = entity_class.reflections[column.to_sym]
           if reflection.class == ActiveRecord::Reflection::AssociationReflection
-            # try to find a sensible display class. Default to to_s
             related_class = reflection.class_name.constantize
+            
+            # try to find a sensible display class. Default to to_s
             display_method =
-            %w{#{model_class.name} name title username}.find( lambda{ 'to_s' } ) do |m|
+            %w{#{entity_class.name} name title username}.find( lambda{ 'to_s' } ) do |m|
               related_class.column_names.include?( m ) || related_class.instance_methods.include?( m )
             end
+            
+            # set the display method
             relational column.to_sym, :display => display_method
           else
             plain column.to_sym
@@ -248,14 +452,14 @@ class ModelBuilder
           puts $!.message
           puts $!.backtrace
           # just do a plain
-          puts "Doing plain for #{model_class}.#{column}"
+          puts "Doing plain for #{entity_class}.#{column}"
           plain column.to_sym
         end
       else
         plain column.to_sym
       end
     end
-    records :order => model_class.primary_key
+    records :order => entity_class.primary_key
   end
   
   # return the named Clevic::Field object
@@ -264,14 +468,15 @@ class ModelBuilder
   end
   
   # This takes all the information collected
-  # by the other methods, and returns the new TableModel
+  # by the other methods, and returns a new TableModel
+  # with the given table_view as its parent.
   def build( table_view )
     # build the model with all it's collections
     # using @model here because otherwise the view's
     # reference to this very same model is garbage collected.
     @model = Clevic::TableModel.new( table_view )
-    @model.object_name = model_class.name
-    @model.model_class = model_class
+    table_view.object_name = @object_name
+    @model.entity_view = entity_view
     @model.fields = @fields
     @model.read_only = @read_only
     @model.auto_new = auto_new?
@@ -285,36 +490,12 @@ class ModelBuilder
     @model
   end
   
-private
-
-  def init_from_model( model_class, can_build_default, &block )
-    if model_class.respond_to?( :build_table_model )
-      # call build_table_model
-      method = model_class.method :build_table_model
-      method.call( builder )
-    elsif !model_class.define_ui_block.nil?
-      #define_ui is used, so use that block
-      instance_eval( &model_class.define_ui_block )
-    elsif can_build_default
-      # build a default UI
-      default_ui
-      
-      # allow for smallish changes to a default build
-      instance_eval( &model_class.post_default_ui_block ) unless model_class.post_default_ui_block.nil?
-    end
+protected
 
-    # the local block adds to the previous definitions
-    unless block.nil?
-      if block.arity == 0
-        instance_eval( &block )
-      else
-        yield( builder )
-      end
-    end
-  end
-  
-  # add AR :include options for foreign keys, but it takes up too much memory,
-  # and actually takes longer to load a data set
+  # Add ActiveRecord :include options for foreign keys, but it takes up too much memory,
+  # and actually takes longer to load a data set.
+  #--
+  # TODO ActiveRecord-2.1 has smarter includes
   def add_include_options
     fields.each do |field|
       if field.delegate.class == RelationalDelegate
@@ -324,9 +505,8 @@ private
     end
   end
 
-  # set a sensible read-only value if it isn't already
-  # specified in options doesn't alread
-  def read_only_default( attribute, options )
+  # set a sensible read-only value if it isn't already specified in options
+  def read_only_default!( attribute, options )
     # sensible defaults for read-only-ness
     options[:read_only] ||= 
     case
@@ -334,18 +514,18 @@ private
         # it's a Proc or a Method, so we can't set it
         true
         
-      when model_class.column_names.include?( options[:display].to_s )
+      when entity_class.column_names.include?( options[:display].to_s )
         # it's a DB column, so it's not read only
         false
         
-      when model_class.reflections.include?( attribute )
+      when entity_class.reflections.include?( attribute )
         # one-to-one relationships can be edited. many-to-one certainly can't
-        reflection = model_class.reflections[attribute]
+        reflection = entity_class.reflections[attribute]
         reflection.macro != :has_one
         
-      when model_class.instance_methods.include?( attribute.to_s )
+      when entity_class.instance_methods.include?( attribute.to_s )
         # read-only if there's no setter for the attribute
-        !model_class.instance_methods.include?( "#{attribute.to_s}=" )
+        !entity_class.instance_methods.include?( "#{attribute.to_s}=" )
       else
         # default to not read-only
         false
@@ -354,8 +534,8 @@ private
 
   # The collection of model objects to display in a table
   # arg can either be a Hash, in which case a new CacheTable
-  # is created, or it can be an array
-  # called by records( *args )
+  # is created, or it can be an array.
+  # Called by records( *args )
   def set_records( arg )
     if arg.class == Hash
       # need to defer this until all fields are collected
@@ -365,28 +545,15 @@ private
     end
   end
 
-  # return a collection of records. Usually this will be a CacheTable.
-  # called by records( *args )
+  # Return a collection of records. Usually this will be a CacheTable.
+  # Called by records( *args )
   def get_records
     if @records.nil?
       #~ add_include_options
-      @options[:auto_new] = auto_new?
-      @records = CacheTable.new( model_class, @options )
+      @records = CacheTable.new( entity_class, @options.merge( :auto_new => auto_new? ) )
     end
     @records
   end
-  # update options with the values in block, using FieldBuilder
-  # to evaluate block
-
-  def gather_block( options, &block )
-    unless block.nil?
-      fb = FieldBuilder.new( options )
-      fb.instance_eval( &block )
-      fb.to_hash
-    else
-      options
-    end
-  end
   
 end