gridify 0.1.0

data/lib/gridify/grid_options.rb

@@ -0,0 +1,261 @@
+module Gridify
+  class Grid
+    # non persistent options:
+    #             :build_model
+    #             :only
+    #             :except     
+             
+    attr_accessor :name,                # name of the table (required)
+                  :resource,            # based on AR model class (assume tableized, plural, string)
+                                        # used as basis for all RESTful requests and data format
+
+    # model
+                  :columns,             # incoming: hash of presets (native jqGrid); internally: array of GridColumn objects
+                                        # { :body => { "title" => {"width" => 98} }} 
+
+                  #:widths,             # hash of column width (key = data type)
+                  :searchable,          # default: true (used in generating columns, changing has no effect on existing cols)
+                  :sortable,            # default: true (used in generating columns, changing has no effect on existing cols)
+                  :editable,            # default: false (used in generating columns, changing has no effect on existing cols)
+                      
+    # grid
+                  :dom_id,                # defaults to #{resource}_#{name} eg "notes_grid"
+                  
+                  :jqgrid_options,        # hash of additional jqGrid options that override any other settings
+
+
+    # grid layout options
+                  :width,                 # in pixels, or nil (nil means calculated based on overflow setting)
+                  :width_fit,             # :fluid, :scroll, or :visible
+                                          #   :fluid will always fit container (presently ignores width option)
+                                          #   :scroll uses horizontal scrollbars
+                                          #   :fitted scales columns to fit in width, not fluid
+                  
+                  :height,                # in pixels, '100%', or :auto (150) 
+                                          #   :auto means makes it as tall as needed per number of rows
+
+                  :resizable,             # allow gride resize with mouse, (true) (or {}) for default options; 
+                                          #   nil or false for disabled; or hash of jqUI options
+                                          #   see http://jqueryui.com/demos/resizable/
+                                          #   defaults (differ from jqUI ones) "minWidth" => 150, "minHeight" => 80
+                                          #   when overflow is fluid, "handles" => 's', otherwise 'e, s, se'
+
+                  :arranger,           # :sortable, :hide_show, :chooser, or nil for none (nil) , 
+                                          #   can combine with array of options
+                                          #   or can be a hash with options
+                                          #   see http://www.trirand.com/jqgridwiki/doku.php?id=wiki:show_hide_columns
+    
+    # rows    
+                  :alt_rows,              # true for odd/even row classes, or odd row style name string (nil)
+
+                  :row_numbers,           # true to display row numbers in left column; or numeric width in pixels (nil)
+
+                  :select_rows,           # true for rows are selectable (eg for pager buttons); or js function when row is selected, false disables hover (true if pager buttons else false)
+
+    # header layer
+                  :title,                 # title string (aka caption), or true for resource.titleize, nil for no title (nil)
+                  
+                  :collapsible,           # when true generates collapse icon (false) 
+                  :collapsed,             # when true initial state is collapsed (false)
+                  
+    # pager layer
+                  :pager,                 # id of the pager, or true => dom_id+"_pager", false or nil for no pager (nil)
+                  :paging_controls,       # false to disable all (true); or hash with native jqGrid options
+                  :paging_choices,        # array of rows_per_page choices ([10,25,50,100])
+
+    # nav buttons
+                  :view_button,           # true, or hash of native jqGrid parameters and events for the action
+                  :add_button,
+                  :edit_button,
+                  :delete_button,
+                  
+                  :search_button,         # enable search button and dialog
+                  :search_advanced,       # instead of search_button
+                  :search_toolbar,        # toggleable search bar, true or :visible, :hidden (other options?)  (nil)
+                  
+                  :refresh_button,
+                  :jqgrid_nav_options,    # native jqGrid button options (added to 2nd arg in navGrid method)
+                  
+                  
+    # data
+                  :restful,               # use restful url and mtype (true) for all actions
+                  :finder,                # default: :find
+                  :url,                   # request url (required unless table_to_grid or derived from resource)
+                                          #   if nil, uses "/#{resource}" eg "/notes"
+                                          #   note, to force "editurl" use jqgrid_options
+                  
+                  :data_type,             # :xml, :json, and other defined in jqGrid options doc (xml)
+                  :data_format,           # (defaults to rails conventin based on resource) <chickens><chicken><title><body> format
+                                          #   set false for jqGrid default <rows><records><row><cell> format
+                  
+                  :sort_by,           # name of sort column of next request
+                  :sort_order,            # sort direction of next request, 'asc' or 'desc' ('asc')
+                  :case_sensitive,        # sort and search are case sensitive (false)
+                  
+                  :current_page,                 # current page requested
+                  :rows_per_page,         # number of items to be requested in the next request (paging_choices.first or -1 if pager false)
+                  
+                  :table_to_grid,         # when true generates tableToGrid (false) from html table, then use as local data
+                                          #   note, we assume table rows are not selectable. 
+                                          #   (tableToGrid sets multiselect when first col has checkboxes or radio buttons, 
+                                          #   we dont know to preserve this so you also need to set in options)
+                                          
+                  :load_once,             # true to use local data after first load (false)
+                  :error_handler,         # javacript: method for crud error handling (default to "after_submit")
+                  :error_container,       # selector for posting error/flash messages (.errorExplanation)
+                                          
+               
+                  :z
+        
+    # ----------------------  
+    # attribute defaults and special value handling
+    # (sure it'd be easier to initialize defaults using a hash but we want nil to mean the jqGrid default - might be true - and not pass a value at all)
+    
+    def restful
+      @restful==false ? false : true
+    end
+    
+    def finder
+      @finder || :find
+    end
+    
+    def searchable
+      @searchable==false ? false : true
+    end
+    
+    def sortable
+      @sortable==false ? false : true
+    end
+        
+            
+    def dom_id
+      @dom_id || "#{resource}_#{name}"
+    end
+    
+    def jqgrid_options
+      @jqgrid_options || {}
+    end
+    
+    def width_fit
+      @width_fit || :fluid
+    end
+    
+    def resizable
+      return false if @resizable == false
+      rs = { "minWidth" => 150, "minHeight" => 80 }
+      rs.merge!({ "handles" => 's' }) if width_fit == :fluid
+      rs.merge!( @resizable ) if @resizable.is_a?(Hash)
+      rs
+    end
+    
+    def arranger_type #read-only
+      if arranger.is_a?(Hash)
+        arranger.keys
+      else
+        Array(arranger)
+      end
+    end
+    
+    def arranger_options(type) #read-only       
+      (arranger[type] if arranger.is_a?(Hash)) || {}
+    end
+    
+    def select_rows
+      if @select_rows
+        @select_rows
+      else
+        pager && (view_button || edit_button || delete_button)
+      end
+    end
+    
+    # header layer
+    def title
+      case @title
+      when String:  @title
+      when true:    resource.titleize
+      else          
+        ('&nbsp;' if collapsible || collapsed) #show header with blank title
+      end
+    end
+
+    def collapsible
+      @collapsible || @collapsed
+    end
+    
+    # pager layer
+    def pager
+      case @pager
+      when String:  @pager
+      when true:    dom_id+'_pager'
+      end
+    end
+    
+    def paging_controls
+      @paging_controls.nil? ? true : @paging_controls
+    end
+    
+    def paging_choices
+      @paging_choices || [10,25,50,100]
+    end
+    
+    # data
+    def url
+      @url || "/#{resource}"
+    end
+
+    def rows_per_page
+      #debugger
+      # all rows when pager controls or rows per page are off
+      if !pager || paging_controls==false || @rows_per_page==false || @rows_per_page==-1
+        -1
+      elsif @rows_per_page.nil?
+        paging_choices.first
+      else
+        @rows_per_page
+      end
+    end
+    
+    def data_type
+      @data_type || :xml
+    end
+
+    def data_format
+      if @data_format || @data_format==false #explicit false for no param
+        @data_format
+      elsif resource && data_type == :xml
+        {
+          :root        => resource,
+          :page        => resource+'>page',
+          :total       => resource+'>total_pages',
+          :records     => resource+'>total_records',
+          :row         => resource.singularize,
+          :repeatitems => false,
+          :id          => :id
+        }
+      elsif resource && data_type == :json
+        {
+          :root        => resource,
+          :page        => 'page',
+          :total       => 'total_pages',
+          :records     => 'total_records',
+          :row         => resource.singularize,
+          :repeatitems => false,
+          :id          => :id
+        }
+      end
+    end
+    
+    def error_handler
+      @error_handler || 'gridify_action_error_handler'
+    end
+    
+    def error_handler_return_value
+      error_handler ? error_handler : 'true;'
+    end
+    
+    def error_container
+      @error_container || '.errorExplanation'
+    end
+
+  end
+end

data/lib/gridify/grid_view.rb

@@ -0,0 +1,346 @@
+# reference: http://github.com/ahe/2dc_jqgrid
+
+module Gridify
+  class Grid
+    
+    # ----------------------
+    # generate the grid javascript for a view
+    # options:
+    #     :script => true generates <script> tag (true)
+    #     :ready  => true generates jquery ready function (true)
+    def to_javascript( options={} )
+      options = { :script => true, :ready => true }.merge(options)
+      
+      s = ''
+      if options[:script]
+        s << %Q^<script type="text/javascript">^       
+      end
+
+      s << js_helpers
+
+      if options[:ready]
+        s << %Q^jQuery(document).ready(function(){^    
+      end
+      
+      s << jqgrid_javascript(options)
+                  
+      if options[:ready]
+        s << %Q^});^ 
+      end
+      if options[:script]
+        s << %Q^</script>^
+      end
+      s     
+    end
+    
+    
+    def to_json
+      jqgrid_properties.to_json_with_js
+    end
+  
+    # alias :to_s, :to_javascript
+    def to_s( options={} )
+      to_javascript( options )
+    end
+            
+    # ------------------
+    protected
+    # ------------------
+  
+    # //{ url: '/notes/{id}', mtype: 'PUT', reloadAfterSubmit: false, closeAfterEdit: true },  // edit settings
+    # //{ url: '/notes', mtype: 'POST', reloadAfterSubmit: false, closeAfterEdit: true },  // add settings
+    # //{ url: '/notes/{id}', mtype: 'DELETE', reloadAfterSubmit: false },  // delete settings
+  
+    # get the button options
+    def edit_button_options
+      # 'url' => '/notes/{id}', 'mtype' => 'PUT'
+      #         {afterSubmit:function(r,data){return #{options[:error_handler_return_value]}(r,data,'edit');}},
+      
+      # note, closeAfterEdit will not close if response returns a non-empty string (even if "success" message)
+      merge_options_defaults( edit_button, 
+        'reloadAfterSubmit' => false, 
+        'closeAfterEdit' => true,
+        'afterSubmit' => "javascript: function(r,data){return #{error_handler_return_value}(r,data,'edit');}"
+      )
+    end
+    
+    def add_button_options
+      # 'url' => '/notes', 'mtype' => 'POST'
+      merge_options_defaults( add_button, 
+        'reloadAfterSubmit' => false, 
+        'closeAfterEdit' => true,
+        'afterSubmit' => "javascript: function(r,data){return #{error_handler_return_value}(r,data,'add');}"
+      )
+    end
+    
+    def delete_button_options
+      # 'url' => '/notes/{id}', 'mtype' => 'DELETE'
+      merge_options_defaults( delete_button, 
+        'reloadAfterSubmit' => false,
+        'afterSubmit' => "javascript: function(r,data){return #{error_handler_return_value}(r,data,'delete');}"
+      )
+    end
+    
+    def search_button_options
+      if search_advanced
+        merge_options_defaults( search_advanced, 'multipleSearch' => true)
+      else
+        merge_options_defaults( search_button)
+      end
+    end
+    
+    def view_button_options
+      merge_options_defaults( view_button)
+    end
+    
+    
+    # generate the jqGrid initial values in json
+    #   maps our attributes to jqGrid options; omit values when same as jqGrid defaults
+    def jqgrid_properties
+      vals                     = {}
+     
+      # data and request options
+      vals['url']               = url if url
+      vals['restful']           = true if restful
+      vals['postData']          = { :grid => name } #identify which grid making the request
+      # vals['colNames']          = column_names if columns.present?
+      vals['colModel']          = column_model if columns.present?
+      vals['datatype']          = data_type if data_type
+      if data_format.present?
+        if data_type == :xml
+          vals['xmlReader']     = data_format
+        elsif data_type == :json
+          vals['jsonReader']    = data_format
+        end
+      end
+        
+      vals['loadonce']          = load_once if load_once
+
+      vals['sortname']          = sort_by if sort_by
+      vals['sortorder']         = sort_order if sort_order && sort_by
+      vals['rowNum']            = rows_per_page if rows_per_page
+      vals['page']              = current_page if current_page
+
+       # grid options
+       vals['height']           = height if height
+       vals['gridview']         = true      # faster views, NOTE theres cases when this needs to be disabled
+      
+      case width_fit
+        when :fitted
+          #vals[:autowidth]    = false #default
+          #vals[:shrinkToFit]  = true #default
+          vals['forceFit']      = true
+          vals['width']         = width if width
+        
+        when :scroll
+          #vals[:autowidth]    = false #default
+          vals['shrinkToFit']   = false
+          #vals['forceFit']     = #ignored by jqGrid
+          vals['width']         = width if width
+        
+        else #when :fluid
+          vals['autowidth']     = true
+          #vals['shrinkToFit']  = true #default
+          vals['forceFit']      = true
+          #vals['width']        = is ignored
+          vals['resizeStop']    = 'javascript: gridify_fluid_recalc_width'
+      end
+      
+      vals['sortable']          = true if arranger_type.include?(:sortable)
+      
+      # header layer
+      vals['caption']           = title if title
+      vals['hidegrid']          = false unless collapsible
+      vals['hiddengrid']        = true if collapsed
+      
+      # row formatting
+      vals['altrows']           = true if alt_rows
+      vals['altclass']          = alt_rows if alt_rows.is_a?(String)
+      
+      vals['rowNumbers']        = true if row_numbers
+      vals['rownumWidth']       = row_numbers if row_numbers.is_a?(Numeric)
+      
+      if select_rows.present?
+        vals['scrollrows']      = true
+        #handler...
+      else
+        vals['hoverrows']       = false
+        vals['beforeSelectRow'] = "javascript: function(){ false; }"
+      end
+      
+      # pager layer
+      if pager
+        vals['pager']           = "##{pager}" 
+        vals['viewrecords']     = true     # display total records in the query (eg "1 - 10 of 25")
+        vals['rowList']         = paging_choices
+        if paging_controls.is_a?(Hash)
+          # allow override of jqGrid pager options
+          vals.merge!(paging_controls)
+        elsif !paging_controls
+          vals['rowList']       = []
+          vals['pgbuttons']     = false
+          vals['pginput']       = false
+          vals['recordtext']    = "{2} records"
+        end
+      end
+      
+      # allow override of native jqGrid options
+      vals.merge(jqgrid_options)
+    end
+    
+    # -----------------
+    def jqgrid_javascript( options={} )
+      s = ''
+
+      if table_to_grid
+        s << %Q^ tableToGrid("##{dom_id}", #{to_json});^
+        s << %Q^ grid = jQuery("##{dom_id}") ^ 
+      else
+        s << %Q^ grid = jQuery("##{dom_id}").jqGrid(#{to_json})^
+      end
+
+      # tag the grid as fluid so we can find it on resize events  
+      if width_fit == :fluid 
+        s << %Q^ .addClass("fluid")^                    
+      end
+
+      # override tableToGrid colmodel options as needed (sortable)
+      #s << %Q^ .jqGrid('setColProp','Title',{sortable: false})^
+
+      # resize method
+      if resizable
+        s << %Q^ .jqGrid('gridResize', #{resizable.to_json})^  
+      end
+
+      # pager buttons (navGrid)
+      if pager
+        nav_params = { 
+          'edit' => edit_button.present?,
+          'add' => add_button.present?,
+          'del' => delete_button.present?,
+          'search' => search_button.present? || search_advanced.present?,
+          'view' => view_button.present?,
+          'refresh' => refresh_button.present?
+        }.merge(jqgrid_nav_options||{})
+        
+        s << %Q^ .navGrid('##{pager}',
+                      #{nav_params.to_json},
+                      #{edit_button_options.to_json_with_js},
+                      #{add_button_options.to_json_with_js},
+                      #{delete_button_options.to_json_with_js},
+                      #{search_button_options.to_json_with_js},
+                      #{view_button_options.to_json_with_js}
+                    )^
+      end
+      
+      if arranger_type.include?(:hide_show)
+        s << %Q^ .jqGrid('navButtonAdd','##{pager}',{ 
+                      caption: "Columns", 
+                      title: "Hide/Show Columns", 
+                      onClickButton : function (){ jQuery("##{dom_id}").jqGrid('setColumns',
+                        #{arranger_options(:hide_show).to_json_with_js} );
+                        }
+                      })^
+      end
+      if arranger_type.include?(:chooser)
+        # hackey way to build the string but gets it done
+        chooser_code = %Q^ function (){ jQuery('##{dom_id}').jqGrid('columnChooser', {
+                          done : function (perm) {
+                            if (perm)  {
+                              this.jqGrid('remapColumns', perm, true);
+                              var gwdth = this.jqGrid('getGridParam','width');
+                              this.jqGrid('setGridWidth',gwdth);
+                            }
+                          } })}^
+        chooser_opts = {
+          'caption' => 'Columns',
+          'title' => 'Arrange Columns',
+          'onClickButton' => 'chooser_code'
+        }.merge(arranger_options(:chooser))
+        s << %Q^ .jqGrid('navButtonAdd','##{pager}', #{chooser_opts.to_json.gsub('"chooser_code"', chooser_code)} )^
+      end
+      
+      if search_toolbar
+        # I wish we could put this in the header rather than the pager
+        s << %Q^ .jqGrid('navButtonAdd',"##{pager}", { caption:"Toggle", title:"Toggle Search Toolbar", buttonicon: 'ui-icon-pin-s', onClickButton: function(){ grid[0].toggleToolbar() } })  
+                 .jqGrid('navButtonAdd',"##{pager}", { caption:"Clear", title:"Clear Search", buttonicon: 'ui-icon-refresh', onClickButton: function(){ grid[0].clearToolbar() } }) 
+                 .jqGrid('filterToolbar')^
+      end
+      
+      # TODO: built in event handlers, eg
+      # loadError 
+      # onSelectRow, onDblClickRow, onRightClickRow etc
+      
+      s << '; '
+      
+      unless search_toolbar == :visible
+        s << %Q^ grid[0].toggleToolbar(); ^
+      end
+
+      # # keep page controls centered (jqgrid bug) [eg appears when :width_fit => :scroll]
+      # s << %Q^ $("##{pager}_left").css("width", "auto"); ^
+        
+      s     
+    end
+
+    # ------------------
+    def js_helpers
+      # just move this into appliaction.js?
+
+      # gridify_fluid_recalc_width: allow grid resize on window resize events
+      # recalculate width of grid based on parent container; handles multiple grids
+      # ref: http://www.trirand.com/blog/?page_id=393/feature-request/Resizable%20grid/
+      
+      # afterSubmit: display error message in response
+      
+      %Q^ function gridify_fluid_recalc_width(){
+          if (grids = jQuery('.fluid.ui-jqgrid-btable:visible')) {
+            grids.each(function(index) {
+              gridId = jQuery(this).attr('id');
+              gridParentWidth = jQuery('#gbox_' + gridId).parent().width();
+              jQuery('#' + gridId).setGridWidth(gridParentWidth);
+            });
+          }
+        };
+
+        jQuery(window).bind('resize', gridify_fluid_recalc_width);
+        
+        function gridify_action_error_handler(r, data, action){
+          if (r.responseText != '') {
+            return [false, r.responseText];
+          } else  {
+            return true;
+          }
+        }
+      ^
+    end
+
+
+    # if(r.responseText != "") {
+    #   $('#{error_container}').html(r.responseText);
+    #   $('#{error_container}').slideDown();
+    #   //window.setTimeout(function() { // Hide error div after 6 seconds
+    #   // $('#{error_container}').slideUp();
+    #   //}, 6000);
+    #   return false;
+    # }
+    # return true;
+    
+    # lets options be true or a hash, merges into defaults and returns a hash
+    def merge_options_defaults( options, defaults={} )
+      if options
+        defaults.merge( options==true ? {} : options)
+      else
+        {}
+      end
+    end
+       
+  end
+end
+
+class Hash
+  # replace embedded '"javascript: foo"' with 'foo'
+  def to_json_with_js
+    self.to_json.gsub(/\"javascript: ([^"]*)\"/) {|string| string[1..-2].gsub('javascript:','') }
+  end
+end