netzke-basepack 0.5.14 → 0.6.0

data/app/components/netzke/basepack/grid_panel.rb

@@ -0,0 +1,374 @@
+require "netzke/basepack/grid_panel/columns"
+require "netzke/basepack/grid_panel/services"
+require "netzke/basepack/grid_panel/javascript"
+# require "netzke/basepack/plugins/configuration_tool"
+# require "data_accessor"
+
+module Netzke
+  module Basepack
+    # == GridPanel
+    # Ext.grid.EditorGridPanel + server-side code
+    #
+    # == Features:
+    # * multi-line CRUD operations - get, post, delete, create
+    # * (multe-record) editing and adding records through a form
+    # * column resize, move and hide
+    # * permissions
+    # * sorting
+    # * pagination
+    # * filtering
+    # * extended configurable search
+    # * rows reordering (drag-n-drop)
+    # * dynamic configuration of properties and columns
+    #
+    # == Class configuration
+    # Configuration on this level is effective during the life-time of the application. They can be put into a .rb file
+    # inside of config/initializers like this:
+    # 
+    #     Netzke::GridPanel.column_filters_available = false
+    #     Netzke::GridPanel.default_config = {:enable_config_tool => false}
+    # 
+    # Most of these options directly influence the amount of JavaScript code that is generated for this component's class.
+    # The less functionality is enabled, the less code is generated.
+    # 
+    # The following configuration options are available:
+    # * <tt>:column_filters_available</tt> - (default is true) include code for the filters in the column's context menu
+    # * <tt>:config_tool_available</tt> - (default is true) include code for the configuration tool that launches the configuration panel
+    # * <tt>:edit_in_form_available</tt> - (defaults to true) include code for (multi-record) editing and adding records through a form
+    # * <tt>:extended_search_available</tt> - (defaults to true) include code for extended configurable search
+    # * <tt>:default_config</tt> - a hash of default configuration options for each instance of the GridPanel component.
+    # See the "Instance configuration" section below.
+    # 
+    # == Instance configuration
+    # The following config options are available:
+    # * <tt>:model</tt> - name of the ActiveRecord model that provides data to this GridPanel.
+    # * <tt>:strong_default_attrs</tt> - a hash of attributes to be merged atop of every created/updated record.
+    # * <tt>:query</tt> - specifies how the data should be filtered.
+    #   When it's a symbol, it's used as a scope name. 
+    #   When it's a string, it's a SQL statement (passed directly to +where+). 
+    #   When it's a hash, it's a conditions hash (passed directly to +where+). 
+    #   When it's an array, it's expanded into SQL statement with arguments (passed directly to +where+), e.g.:
+    #   
+    #     :query => ["id > ?", 100])
+    # 
+    #   When it's a Proc, it's passed the model class, and is expected to return a ActiveRecord::Relation, e.g.:
+    # 
+    #     :query => { |klass| klass.where(:id.gt => 100).order(:created_at) }  
+    #     
+    # * <tt>:enable_column_filters</tt> - enable filters in column's context menu
+    # * <tt>:enable_edit_in_form</tt> - provide buttons into the toolbar that activate editing/adding records via a form
+    # * <tt>:enable_extended_search</tt> - provide a button into the toolbar that shows configurable search form
+    # * <tt>:enable_context_menu</tt> - enable rows context menu
+    # * <tt>:enable_rows_reordering</tt> - enable reordering of rows with drag-n-drop; underlying model (specified in <tt>:model</tt>) must implement "acts_as_list"-compatible functionality; defaults to <tt>false</tt>
+    # * <tt>:enable_pagination</tt> - enable pagination; defaults to <tt>true</tt>
+    # * <tt>:rows_per_page</tt> - number of rows per page (ignored when <tt>:enable_pagination</tt> is set to <tt>false</tt>)
+    # * <tt>:load_inline_data</tt> - load initial data into the grid right after its instantiation (saves a request to server); defaults to <tt>true</tt>
+    # * <tt>:mode</tt> - when set to <tt>:config</tt>, GridPanel loads in configuration mode
+    # * <tt>:add/edit/multi_edit/search_form_config</tt> - additional configuration for add/edit/multi_edit/search form panel
+    # * <tt>:add/edit/multi_edit_form_window_config</tt> - additional configuration for the window that wrapps up add/edit/multi_edit form panel
+    # 
+    # Additionally supports Netzke::Base config options.
+    # 
+    # == Columns
+    # Here's how the GridPanel decides which columns in which sequence and with which configuration to display.
+    # First, the column configs are aquired from this GridPanel's persistent storage, as an array of hashes, each 
+    # representing a column configuration, such as:
+    #
+    #   {:name => :created_at, :header => "Created", :tooltip => "When the record was created"}
+    # 
+    # This hash *overrides* (deep_merge) the hard-coded configuration, an example of which can be specifying 
+    # columns for a GridPanel instance, e.g.:
+    # 
+    #   :columns => [{:name => :created_at, :sortable => false}]
+    # 
+    # ... which in its turn overrides the defaults provided by persistent storage managed by the AttributesConfigurator
+    # that provides *model-level* (as opposed to a component-level) configuration of a database model 
+    # (which is used by both grids and forms in Netzke).
+    # And lastly, the defaults for AttributesConfigurator are calculated from the database model itself (extended by Netzke).
+    # For example, in the model you can specify virtual attributes and their types that will be picked up by Netzke, the default
+    # order of columns, or excluded columns. For details see <tt>Netzke::ActiveRecord::Attributes</tt>.
+    #
+    # Each column supports the option :sorting_scope, which defines a scope used for sorting the column. This option would be
+    # useful for virtual columns for example. The scope will get one parameter which contains the direction (:asc or :desc)
+    # Example:
+    # { :name => complete_user_name, :sorting_scope => :sort_user_by_full_name }
+    # class User < ActiveRecord::Base
+    #     scope :sort_user_by_full_name, lambda { |dir|
+    #         order("users.first_name #{dir.to_s}, users.last_name #{dir.to_s}")
+    #     }
+    # end
+    # 
+    # The columns are displayed in the order specified by what's found first in the following sequence:
+    #   GridPanel instance's persistent storage
+    #   hardcoded config
+    #   AttributesConfigurator persistent storage
+    #   netzke_expose_attributes in the database model
+    #   database columns + (eventually) virtual attributes specified with netzke_attribute
+    class GridPanel < Netzke::Base
+      # Class-level configuration. These options directly influence the amount of generated
+      # javascript code for this component's class. For example, if you don't want filters for the grid, 
+      # set column_filters_available to false, and the javascript for the filters won't be included at all.
+      class_attribute :column_filters_available
+      self.column_filters_available = true
+    
+      class_attribute :config_tool_available
+      self.config_tool_available = true
+      
+      class_attribute :edit_in_form_available
+      self.edit_in_form_available = true
+    
+      class_attribute :extended_search_available
+      self.extended_search_available = true
+    
+      class_attribute :rows_reordering_available
+      self.rows_reordering_available = true
+    
+      class_attribute :default_config
+      self.default_config = {
+        :enable_edit_in_form    => true,
+        :enable_extended_search => true,
+        :enable_column_filters  => true,
+        :load_inline_data       => true,
+        :enable_rows_reordering => false, # column drag n drop
+        :enable_pagination      => true,
+        :rows_per_page          => 25,
+        :tools                  => %w{ refresh },
+      }
+      
+      include self::Javascript
+      include self::Services
+      include self::Columns
+    
+      include Netzke::DataAccessor
+      
+      # def self.enforce_config_consistency
+      #   default_config[:enable_edit_in_form]    &&= edit_in_form_available
+      #   default_config[:enable_extended_search] &&= extended_search_available
+      #   default_config[:enable_rows_reordering] &&= rows_reordering_available
+      # end
+    
+      # def initialize(*args)
+      #   # Deprecations
+      #   config[:scopes] && ActiveSupport::Deprecation.warn(":scopes option is not effective any longer for GridPanel. Use :scope instead.")
+      #   
+      #   super(*args)
+      # end
+
+      # Include extra javascript that we depend on
+      def self.include_js
+        res = ["#{File.dirname(__FILE__)}/grid_panel/javascripts/pre.js"]
+      
+        # Optional edit in form functionality
+        res << "#{File.dirname(__FILE__)}/grid_panel/javascripts/edit_in_form.js" if edit_in_form_available
+      
+        # Optional extended search functionality
+        res << "#{File.dirname(__FILE__)}/grid_panel/javascripts/advanced_search.js" if extended_search_available
+      
+        ext_examples = Netzke::Core.ext_location.join("examples")
+      
+        # Checkcolumn
+        res << ext_examples.join("ux/CheckColumn.js")
+      
+        # Filters
+        if column_filters_available
+          res << ext_examples + "ux/gridfilters/menu/ListMenu.js"
+          res << ext_examples + "ux/gridfilters/menu/RangeMenu.js"
+          res << ext_examples + "ux/gridfilters/GridFilters.js"
+      
+          %w{Boolean Date List Numeric String}.unshift("").each do |f|
+            res << ext_examples + "ux/gridfilters/filter/#{f}Filter.js"
+          end
+        end
+      
+        # DD
+        if rows_reordering_available
+          res << "#{File.dirname(__FILE__)}/grid_panel/javascripts/rows-dd.js"
+        end
+
+        res
+      end
+
+      # Fields to be displayed in the "General" tab of the configuration panel
+      def self.property_fields
+        [
+          # {:name => :ext_config__title,               :attr_type => :string},
+          # {:name => :ext_config__header,              :attr_type => :boolean, :default => true},
+          # {:name => :ext_config__enable_context_menu, :attr_type => :boolean, :default => true},
+          # {:name => :ext_config__enable_pagination,   :attr_type => :boolean, :default => true},
+          # {:name => :ext_config__rows_per_page,       :attr_type => :integer},
+          # {:name => :ext_config__prohibit_create,     :attr_type => :boolean},
+          # {:name => :ext_config__prohibit_update,     :attr_type => :boolean},
+          # {:name => :ext_config__prohibit_delete,     :attr_type => :boolean},
+          # {:name => :ext_config__prohibit_read,       :attr_type => :boolean}
+        ]
+      end
+    
+    
+      def default_bbar
+        res = %w{ add edit apply del }.map(&:to_sym).map(&:action)
+        res << "-" << :add_in_form.action << :edit_in_form.action if config[:enable_edit_in_form]
+        res << "-" << :search.action if config[:enable_extended_search]
+        # config[:enable_extended_search] && res << "-" << {
+        #   :text => "Search", 
+        #   :handler => :on_search, 
+        #   :enable_toggle => true, 
+        #   :icon => :find
+        # }
+        res
+      end
+    
+      def default_context_menu
+        res = %w{ edit del }.map(&:to_sym).map(&:action)
+        res << "-" << :edit_in_form.action if config[:enable_edit_in_form]
+        res
+      end
+    
+      def configuration_components
+        res = []
+        res << {
+          :persistent_config => true,
+          :name              => 'columns',
+          :class_name        => "FieldsConfigurator",
+          :active            => true,
+          :owner             => self
+        }
+        res << {
+          :name               => 'general',
+          :class_name  => "PropertyEditor",
+          :component             => self,
+          :title => false
+        }
+        res
+      end
+
+      action :add do
+        {
+          :text => I18n.t('netzke.basepack.grid_panel.add', :default => "Add"),
+          :disabled => config[:prohibit_create],
+          :icon => :add
+        }
+      end
+      
+      action :edit, {
+        :text => I18n.t('netzke.basepack.grid_panel.edit', :default => "Edit"),
+        :disabled => true,
+        :icon => :table_edit
+      }
+      
+      action :del, {
+        :text => I18n.t('netzke.basepack.grid_panel.delete', :default => "Delete"),
+        :disabled => true,
+        :icon => :table_row_delete
+      }
+      
+      action :apply do
+        {
+          :text => I18n.t('netzke.basepack.grid_panel.apply', :default => "Apply"),
+          :disabled => config[:prohibit_update] && config[:prohibit_create],
+          :icon => :tick
+        }
+      end
+      
+      action :add_in_form, {
+        :text => I18n.t('netzke.basepack.grid_panel.add_in_form', :default => "Add in form"),
+        :icon => :application_form_add
+      }
+      
+      action :edit_in_form, {
+        :text => I18n.t('netzke.basepack.grid_panel.edit_in_form', :default => "Edit in form"),
+        :disabled => true,
+        :icon => :application_form_edit
+      }
+      
+      action :search, {
+        :text => I18n.t('netzke.basepack.grid_panel.search', :default => "Search"),
+        :enable_toggle => true, 
+        :icon => :find
+      }
+      
+      component :add_form do
+        {
+          :lazy_loading => true,
+          :class_name => "Basepack::GridPanel::RecordFormWindow",
+          :title => "Add #{data_class.table_name.singularize.humanize}",
+          :button_align => "right",
+          :items => [{
+            :class_name => "Basepack::FormPanel",
+            :model => config[:model],
+            :items => default_fields_for_forms,
+            :persistent_config => config[:persistent_config],
+            :strong_default_attrs => config[:strong_default_attrs],
+            :border => true,
+            :bbar => false,
+            :header => false,
+            :mode => config[:mode],
+            :record => data_class.new
+          }.deep_merge(config[:add_form_config] || {})]
+        }.deep_merge(config[:add_form_window_config] || {})
+      end
+
+      component :edit_form do
+        {
+          :lazy_loading => true,
+          :class_name => "Basepack::GridPanel::RecordFormWindow",
+          :title => "Edit #{data_class.table_name.singularize.humanize}",
+          :button_align => "right",
+          :items => [{
+            :class_name => "Basepack::FormPanel",
+            :model => config[:model],
+            :items => default_fields_for_forms,
+            :persistent_config => config[:persistent_config],
+            :bbar => false,
+            :header => false,
+            :mode => config[:mode]
+            # :record_id gets assigned by deliver_component at the moment of loading
+          }.deep_merge(config[:edit_form_config] || {})]
+        }.deep_merge(config[:edit_form_window_config] || {})
+      end
+      
+      component :multi_edit_form do
+        {
+          :lazy_loading => true,
+          :class_name => "Basepack::GridPanel::RecordFormWindow",
+          :title => "Edit #{data_class.table_name.humanize}",
+          :button_align => "right",
+          :items => [{
+            :class_name => "Basepack::GridPanel::MultiEditForm",
+            :model => config[:model],
+            :items => default_fields_for_forms,
+            :persistent_config => config[:persistent_config],
+            :bbar => false,
+            :header => false,
+            :mode => config[:mode]
+          }.deep_merge(config[:multi_edit_form_config] || {})]
+        }.deep_merge(config[:multi_edit_form_window_config] || {})
+      end
+
+      component :search_form do
+        {
+          :lazy_loading => true,
+          :class_name => "Basepack::GridPanel::SearchWindow",
+          :model => config[:model],
+          :fields => default_fields_for_forms
+        }
+      end
+      
+    
+      # def search_panel
+      #   {
+      #     :class_name => "Basepack::FormPanel",
+      #     :model => "User",
+      #     # :items => default_fields_for_forms,
+      #     # :search_class_name => cronfig[:model],
+      #     # :persistent_config => config[:persistent_config],
+      #     :header => false,
+      #     :bbar => false,
+      #     # :mode => config[:mode]
+      #   }
+      # end
+
+      # include ::Netzke::Plugins::ConfigurationTool if config_tool_available # it will load ConfigurationPanel into a modal window
+ 
+    end
+  end
+end

data/app/components/netzke/basepack/grid_panel/columns.rb

@@ -0,0 +1,233 @@
+module Netzke
+  module Basepack
+    class GridPanel < Netzke::Base
+      module Columns
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+          # Columns to be displayed by the FieldConfigurator, "meta-columns". Each corresponds to a configuration
+          # option for each column in the grid.
+          def meta_columns
+            [
+              # Whether the column will be present in the grid, also in :hidden or :meta state. The value for this column will
+              # always be sent to/from the JS grid to the server
+              {:name => "included",      :attr_type => :boolean, :width => 40, :header => "Incl", :default_value => true},
+
+              # The name of the column. May be any accessible method or attribute of the data_class.
+              {:name => "name",          :attr_type => :string, :width => 200},
+
+              # The header for the column.
+              {:name => "label",         :attr_type => :string, :width => 200, :header => "Header"},
+
+              # The default value of this column. Is used when a new row in the grid gets created.
+              {:name => "default_value", :attr_type => :string, :width => 200},
+
+              # Options for drop-downs
+              {:name => "combobox_options",       :attr_type => :string, :editor => :textarea, :width => 200},
+
+              # Whether the column is editable in the grid.
+              {:name => "read_only",     :attr_type => :boolean, :header => "R/O", :tooltip => "Read-only"},
+
+              # Whether the column will be in the hidden state (hide/show columns from the column menu, if it's enabled).
+              {:name => "hidden",        :attr_type => :boolean},
+
+              # Whether the column should have "grid filters" enabled 
+              # (see here: http://www.extjs.com/deploy/dev/examples/grid-filtering/grid-filter-local.html)
+              {:name => "with_filters",  :attr_type => :boolean, :default_value => true, :header => "Filters"},
+
+              #
+              # Below some rarely used parameters, hidden by default (you can always un-hide them from the column menu).
+              #
+
+              # The column's width
+              {:name => "width",         :attr_type => :integer, :hidden => true},
+
+              # Whether the column should be hideable
+              {:name => "hideable",      :attr_type => :boolean, :default_value => true, :hidden => true},
+
+              # Whether the column should be sortable (why change it? normally it's hardcoded)
+              {:name => "sortable",      :attr_type => :boolean, :default_value => true, :hidden => true},
+            ]
+          end
+        
+        end
+      
+        # Normalized columns for the grid, e.g.:
+        # [{:name => :id, :hidden => true, ...}, {:name => :name, :editable => false, ...}, ...]
+        def columns(only_included = true)
+          @columns ||= begin
+            if cols = load_columns
+              filter_out_excluded_columns(cols) if only_included
+              reverse_merge_equally_named_columns(cols, initial_columns)
+              cols
+            else
+              initial_columns(only_included)
+            end
+          end
+        end
+      
+        # Columns that we fall back to when neither persistent columns, nor configured columns are present.
+        # If there's a model-level field configuration, it's being used.
+        # Otherwise the defaults straight from the ActiveRecord model ("netzke_attributes").
+        # Override this method if you want to provide a fix set of columns in your subclass.
+        def default_columns
+          @default_columns ||= load_model_level_attrs || data_class.netzke_attributes
+        end
+      
+        # Columns that represent a smart merge of default_columns and columns passed during the configuration.
+        def initial_columns(only_included = true)
+          # Normalize here, as from the config we can get symbols (names) instead of hashes
+          columns_from_config = config[:columns] && normalize_attrs(config[:columns])
+        
+        
+          if columns_from_config
+            # automatically add a column that reflects the primary key (unless specified in the config)
+            columns_from_config.insert(0, {:name => data_class.primary_key}) unless columns_from_config.any?{ |c| c[:name] == data_class.primary_key }
+          
+            # reverse-merge each column hash from config with each column hash from exposed_attributes 
+            # (columns from config have higher priority)
+            for c in columns_from_config
+              corresponding_default_column = default_columns.find{ |k| k[:name] == c[:name] }
+              c.reverse_merge!(corresponding_default_column) if corresponding_default_column
+            end
+            columns_for_create = columns_from_config
+          else
+            # we didn't have columns configured in component's config, so, use the columns from the data class
+            columns_for_create = default_columns
+          end
+        
+          filter_out_excluded_columns(columns_for_create) if only_included
+        
+          # Make the column config complete with the defaults
+          columns_for_create.each do |c|
+            detect_association(c)
+            set_default_header(c)
+            set_default_editor(c)
+            set_default_width(c)
+            set_default_hidden(c)
+            set_default_editable(c)
+            set_default_sortable(c)
+            set_default_filterable(c)
+          end
+
+          columns_for_create
+        end
+      
+        private
+          def filter_out_excluded_columns(cols)
+            cols.reject!{ |c| c[:included] == false }
+          end
+      
+          # Stores modified columns in persistent storage
+          def save_columns!
+            # NetzkeFieldList.update_list_for_current_authority(global_id, columns(false), original_data_class.name) if persistent_config_enabled?
+          end
+      
+          def load_columns
+            # NetzkeFieldList.read_list(global_id) if persistent_config_enabled?
+          end
+        
+          def load_model_level_attrs
+            # NetzkeModelAttrList.read_list(data_class.name) if persistent_config_enabled?
+          end
+        
+          def set_default_header(c)
+            c[:label] ||= c[:name].humanize
+          end
+        
+          def set_default_editor(c)
+            c[:editor] ||= editor_for_attr_type(c[:attr_type])
+            c[:editor] = {:xtype => c[:editor]} if c[:editor].is_a?(Symbol)
+          end
+        
+          def set_default_width(c)
+            c[:width] ||= 50 if c[:attr_type] == :boolean
+            c[:width] ||= 150 if c[:attr_type] == :datetime
+          end
+        
+          def set_default_hidden(c)
+            c[:hidden] = true if primary_key_attr?(c) && c[:hidden].nil?
+          end
+        
+          def set_default_editable(c)
+            c[:editable] = c[:read_only].nil? ? !(primary_key_attr?(c) || c[:virtual]) : !c[:read_only]
+            c.delete(:read_only)
+          end
+        
+          def set_default_sortable(c)
+            c[:sortable] = !c[:virtual] if c[:sortable].nil?
+          end
+        
+          def set_default_filterable(c)
+            c[:filterable] = !c[:virtual] if c[:filterable].nil?
+          end
+        
+          # Returns editor's xtype for a column type
+          def editor_for_attr_type(type)
+            attr_type_to_editor_map[type]
+          end
+        
+          def editor_for_association
+            :combobox
+          end
+   
+          # Returns a hash that maps a column type to the editor xtype. Override if you want different editors.
+          def attr_type_to_editor_map
+            {
+              :integer => :numberfield,
+              :boolean => :checkbox,
+              :date => :datefield,
+              :datetime => :xdatetime,
+              :text => :textarea,
+              :string => :textfield
+            }
+          end
+      
+          # Detects an association column and sets up the proper editor.
+          def detect_association(c)
+            # double-underscore notation? surely an association column
+            if c[:name].index('__')
+              assoc_name, assoc_method = c[:name].split('__')
+              assoc = data_class.reflect_on_association(assoc_name.to_sym)
+          
+              if assoc && assoc_method
+                assoc_column = assoc.klass.columns_hash[assoc_method]
+                assoc_method_type = assoc_column.try(:type)
+            
+                # if association column is boolean, display a checkbox (or alike), otherwise - a combobox (or alike)
+                c[:editor] ||= assoc_method_type == :boolean ? editor_for_attr_type(:boolean) : editor_for_association
+              end
+            end
+          end
+        
+          # Default fields that will be displayed in the Add/Edit/Search forms
+          def default_fields_for_forms
+            form_klass = "Netzke::ModelExtensions::#{config[:model]}ForFormPanel".constantize rescue nil
+            form_klass ||= original_data_class
+          
+            # Select only those fields that are known to the form_klass
+            selected_columns = columns.select do |c|
+              form_klass.column_names.include?(c[:name]) ||
+              form_klass.instance_methods.include?("#{c[:name]}=") ||
+              association_attr?(c[:name])
+            end
+          
+            selected_columns.map do |c|
+              field_config = {:name => c[:name]}
+            
+              # scopes for combobox options
+              field_config[:scopes] = c[:editor].is_a?(Hash) && c[:editor][:scopes]
+            
+              field_config
+            end
+          end
+        
+          # Receives 2 arrays of columns. Merges the missing config from the +source+ into +dest+, matching columns by name
+          def reverse_merge_equally_named_columns(dest, source)
+            dest.each{ |dc| dc.reverse_merge!(source.detect{ |sc| sc[:name] == dc[:name] } || {}) }
+          end
+
+      end
+    end
+  end
+end