netzke-basepack 0.12.9 → 1.0.0.0.pre

data/lib/netzke/{basepack/form/javascripts/form.js → form/base/client/base.js}

@@ -1,3 +1,7 @@
+/**
+ * Client-side code for [Netzke::Form::Base](http://www.rubydoc.info/github/netzke/netzke-basepack/Netzke/Form/Base)
+ * @class Netzke.Form.Base
+ */
 {
   bodyStyle     : 'padding:5px 5px 0',
   autoScroll    : true,
@@ -33,35 +37,37 @@
     // Now let Ext.form.Form do the rest
     this.callParent(arguments);
 
-    if (this.applyOnReturn) {
-      Ext.each(this.query('field'), function(field) {
-        field.on('specialkey', function(field, event) {
-          if (event.getKey() == 13) this.up('form').onApply();
-        });
+    Ext.each(this.query('field'), function(field) {
+      field.on('specialkey', function(field, event) {
+        if (event.getKey() == 13) this.up('form').netzkeOnApply();
       });
-    }
+    });
   },
 
   afterRender: function(){
     this.callParent();
 
     // have a record to be displayed?
-    if (this.record) { this.setFormValues(this.record); }
+    if (this.record) { this.netzkeSetFormValues(this.record); }
 
     // render in display mode?
-    if (this.locked || this.readOnly) this.setReadonlyMode(true);
+    if (this.locked || this.readOnly) this.netzkeSetReadonlyMode(true);
   },
 
-  onEdit: function(){
-    this.setReadonlyMode(false);
+  netzkeOnEdit: function(){
+    this.netzkeSetReadonlyMode(false);
   },
 
-  onCancel: function(){
+  netzkeOnCancel: function(){
     this.getForm().reset();
-    this.setReadonlyMode(true, true);
+    this.netzkeSetReadonlyMode(true, true);
   },
 
-  updateToolbar: function(){
+  /**
+   * In lockable mode, dynamically updates the toolbar depending on the read-only state.
+   * @method netzkeUpdateToolbar
+   */
+  netzkeUpdateToolbar: function(){
     var tbar = this.child('toolbar');
     if (!tbar) return;
 
@@ -96,7 +102,11 @@
     tbar.doLayout();
   },
 
-  onApply: function() {
+  /**
+   * Handler for the `apply` action.
+   * @method netzkeOnApply
+   */
+  netzkeOnApply: function() {
     if (this.fireEvent('apply', this)) {
       var values = this.getForm().getValues();
       for (var fieldName in values) {
@@ -135,9 +145,10 @@
       // We must use a different approach when the form is multipart, as we can't use the endpoint
       if (this.getForm().hasUpload()) {
         this.getForm().submit({ // normal submit
-          url: this.netzkeEndpointUrl("netzke_submit"),
+          url: this.netzkeEndpointUrl("submit"),
           params: {
-            data: Ext.encode(values) // here are the correct values that may be different from display values
+            data: Ext.encode(values), // here are the correct values that may be different from display values
+            configs: Ext.encode(this.netzkeBuildParentConfigs())
           },
           failure: function(form, action){
             var respObj = Ext.decode(action.response.responseText);
@@ -153,27 +164,33 @@
           scope: this
         });
       } else {
-        this.netzkeSubmit(Ext.apply((this.baseParams || {}), { data:Ext.encode(values) }), function(){ this.setLoading(false); }, this);
+        this.server.submit(Ext.apply((this.baseParams || {}), { data:Ext.encode(values) }), function(){ this.setLoading(false); });
       }
     }
     this.fireEvent('afterApply', this);
   },
 
-  // called from the server
-  onSubmitSuccess: function() {
+  /**
+   * Called by the server on successful submit.
+   * @method netzkeOnSubmitSuccess
+   */
+  netzkeOnSubmitSuccess: function() {
     this.fireEvent("submitsuccess");
-    if (this.mode == "lockable") this.setReadonlyMode(true);
+    if (this.mode == "lockable") this.netzkeSetReadonlyMode(true);
     this.setLoading(false);
   },
 
-  setFormValues: function(values){
+  /**
+   * Sets form values (including associations).
+   * @method netzkeSetFormValues
+   */
+  netzkeSetFormValues: function(values){
     var assocValues = values.meta.associationValues || {};
     for (var assocFieldName in assocValues) {
 
       var assocField = this.getForm().getFields().filter('name', assocFieldName).first();
       if (assocField.isXType('combobox')) {
-        // HACK: using private property 'store' here!
-        assocField.store.loadData([[values[assocFieldName], assocValues[assocFieldName]]]);
+        assocField.getStore().loadData([[values[assocFieldName], assocValues[assocFieldName]]]);
         delete assocField.lastQuery; // force loading the store next time user clicks the trigger
       } else {
         assocField.setValue(assocValues[assocFieldName]);
@@ -184,42 +201,64 @@
     this.getForm().setValues(values);
   },
 
-  setReadonlyMode: function(onOff, cancel){
+  /**
+   * Dynamically changes form's read-only state.
+   * @method netzkeSetReadonlyMode
+   * @param {Boolean} onOff
+   */
+  netzkeSetReadonlyMode: function(onOff){
     if (this.inReadonlyMode == onOff) return;
     this.getForm().getFields().each(function(i){
-      if (i.setReadonlyMode) i.setReadonlyMode(onOff);
+      if (i.netzkeSetReadonlyMode) i.netzkeSetReadonlyMode(onOff);
     });
 
     // this.getForm().cleanDestroyed(); // because fields inside of composite fields are not auto-cleaned!
     this.doLayout();
     this.inReadonlyMode = onOff;
-    if (this.mode == "lockable") this.updateToolbar();
+    if (this.mode == "lockable") this.netzkeUpdateToolbar();
   },
 
-  // recursively extract field names
-  extractFields: function(items){
+  /**
+   * Recursively extract field names from `items`.
+   * @method netzkeExtractFields
+   * @param {Array} items
+   */
+  netzkeExtractFields: function(items){
     Ext.each(items, function(i){
-      if (i.items) {this.extractFields(i.items);}
+      if (i.items) {this.netzkeExtractFields(i.items);}
       else if (i.name) {this.fieldNames.push(i.name);}
     }, this);
   },
 
-  applyFormErrors: function(errors) {
+  /**
+   * Called by the server to display varidation errors.
+   * @method netzkeApplyFormErrors
+   * @param {Array} errors Array of errors as provided by the `submit` endpoint
+   */
+  netzkeApplyFormErrors: function(errors) {
     var field;
     Ext.iterate(errors, function(fieldName, message){
       fieldName = fieldName.underscore();
-      if ( field = this.getForm().findField(fieldName) || 
-           this.getForm().findField(fieldName.replace(/([a-z]+)([0-9])/g, '$1_$2')) || 
-           this.getForm().getFields().findBy(function(f){ return fieldName == f.getName().replace(/(.+)__.+/g, '$1'); }) || 
-           this.getForm().getFields().findBy(function(f){ 
-             str = f.getName().camelize(); 
-             first = str.substring(0,1); 
-             matchingName = (first.toLowerCase()+str.substring(1)).underscore(); 
+      if ( field = this.getForm().findField(fieldName) ||
+           this.getForm().findField(fieldName.replace(/([a-z]+)([0-9])/g, '$1_$2')) ||
+           this.getForm().getFields().findBy(function(f){ return fieldName == f.getName().replace(/(.+)__.+/g, '$1'); }) ||
+           this.getForm().getFields().findBy(function(f){
+             str = f.getName().camelize();
+             first = str.substring(0,1);
+             matchingName = (first.toLowerCase()+str.substring(1)).underscore();
              return fieldName == matchingName;
            })
       ) {
         field.markInvalid(message.join('<br/>'));
       }
     }, this);
-  }
+  },
+
+  netzkeDisplayFormErrors: function(errors){
+    var body = "";
+    Ext.each(errors, function(error){
+      body += error.msg + "<br/>"
+    });
+    this.netzkeNotify(body);
+  },
 }

data/lib/netzke/form/base/client/readonly_mode.css

@@ -0,0 +1,4 @@
+input.readonly, textarea.readonly {
+  background-color: #f5f5f5;
+  background-image: none;
+}

data/lib/netzke/{basepack/form/javascripts → form/base/client}/readonly_mode.js

@@ -1,8 +1,8 @@
-// Overrides that implement setReadonlyMode for form fields.
+// Overrides that implement netzkeSetReadonlyMode for form fields.
 //
 
 Ext.form.field.Base.override({
-  setReadonlyMode: function(onOff){
+  netzkeSetReadonlyMode: function(onOff){
     if (this.hidden) return;
 
     if (!this.initialConfig.readOnly) {
@@ -21,15 +21,15 @@ Ext.form.field.Base.override({
 
 // Also the FieldContainer
 Ext.form.FieldContainer.override({
-  setReadonlyMode: function(onOff){
+  netzkeSetReadonlyMode: function(onOff){
     this.items.each(function(i){
-      i.setReadonlyMode(onOff);
+      i.netzkeSetReadonlyMode(onOff);
     });
   }
 });
 
 Ext.form.field.Checkbox.override({
-  setReadonlyMode: function(onOff){
+  netzkeSetReadonlyMode: function(onOff){
     this.setDisabled(onOff);
   }
 });

data/lib/netzke/form/endpoints.rb

@@ -0,0 +1,33 @@
+module Netzke
+  module Form
+    module Endpoints
+      extend ActiveSupport::Concern
+
+      included do
+        # Called when the form gets submitted (e.g. by pressing the Apply button)
+        endpoint :submit do |params|
+          data = ActiveSupport::JSON.decode(params[:data])
+          submit(data, client)
+        end
+
+        # Can be called when the form needs to load a record with given ID. E.g.:
+        #
+        #     someForm.server.load({id: 100});
+        endpoint :load do |params|
+          @record = model && model_adapter.find_record(params[:id])
+          client.netzke_set_form_values js_record_data
+        end
+
+        # Returns options for a combobox
+        # params receive:
+        # +attr+ - column's name
+        # +query+ - what's typed-in in the combobox
+        # +id+ - selected record id
+        endpoint :get_combobox_options do |params|
+          attr = fields[params[:attr].to_sym]
+          client.data = model_adapter.combo_data(attr, params[:query])
+        end
+      end
+    end
+  end
+end

data/lib/netzke/form/services.rb

@@ -0,0 +1,74 @@
+module Netzke
+  module Form
+    module Services
+      extend ActiveSupport::Concern
+
+      def submit(data, client)
+        # File uploads are in raw params instead of "data" hash, so, mix them in into "data"
+        controller.params.each_pair do |k,v|
+          data[k] = v if v.is_a?(ActionDispatch::Http::UploadedFile)
+        end
+
+        success = create_or_update_record(data)
+
+        if success
+          client.netzke_set_form_values(js_record_data)
+          client.success = true # respond to classic form submission with {success: true}
+          client.netzke_on_submit_success # inform the Netzke endpoint caller about success
+        else
+          errors = model_adapter.errors_array(@record).map do |error|
+            {level: :error, msg: error}
+          end
+          client.netzke_display_form_errors(errors)
+          client.netzke_apply_form_errors(build_form_errors(record))
+        end
+      end
+
+      def values
+        record && record.netzke_hash(fields)
+      end
+
+      private
+
+      # Builds the form errors
+      def build_form_errors(record)
+        form_errors = {}
+        foreign_keys = model_adapter.hash_fk_model
+        record.errors.to_hash.map{|field, error|
+          # some ORM return an array for error
+          error = error.join ', ' if error.kind_of? Array
+          # Get the correct field name for the errors on foreign keys
+          if foreign_keys.has_key?(field)
+            fields.each do |k, v|
+              # Hack to stop to_nifty_json from camalizing model__field
+              field = k.to_s.gsub('__', '____') if k.to_s.split('__').first == foreign_keys[field].to_s
+            end
+          end
+          form_errors[field] ||= []
+          form_errors[field] << error
+        }
+        form_errors
+      end
+
+      # Creates/updates a record from hash
+      def create_or_update_record(hsh)
+        hsh.merge!(config[:strong_values]) if config[:strong_values]
+
+        # only pick the record specified in the params if it was not provided in the configuration
+        @record ||= model_adapter.find_record hsh.delete(model.primary_key.to_s)
+
+        #model.find(:first, :conditions => model.primary_key => hsh.delete(model.primary_key)})
+        success = true
+
+        @record = model.new if @record.nil?
+
+        hsh.each_pair do |k,v|
+          model_adapter.set_record_value_for_attribute(@record, fields[k.to_sym].nil? ? {:name => k} : fields[k.to_sym], v)
+        end
+
+        # did we have complete success?
+        success && model_adapter.save_record(@record)
+      end
+    end
+  end
+end

data/lib/netzke/grid/actions.rb

@@ -0,0 +1,52 @@
+module Netzke
+  module Grid
+    module Actions
+      extend ActiveSupport::Concern
+
+      included do
+        action :add do |a|
+          a.icon = :add
+        end
+
+        action :edit do |a|
+          a.disabled = true # initial
+          a.icon = :table_edit
+        end
+
+        action :delete do |a|
+          a.disabled = true # initial
+          a.icon = :table_row_delete
+        end
+
+        action :apply do |a|
+          a.icon = :tick
+        end
+
+        action :search do |a|
+          a.enable_toggle = true
+          a.icon = :magnifier
+        end
+      end
+
+      def has_add_action?
+        allowed_to?(:create)
+      end
+
+      def has_edit_action?
+        allowed_to?(:update)
+      end
+
+      def has_apply_action?
+        config.edit_inline && (allowed_to?(:create) || allowed_to?(:update))
+      end
+
+      def has_delete_action?
+        allowed_to?(:delete)
+      end
+
+      def has_search_action?
+        true
+      end
+    end
+  end
+end

data/lib/netzke/grid/base.rb

@@ -0,0 +1,289 @@
+module Netzke
+  module Grid
+    # Ext.grid.Panel-based component with the following features:
+    #
+    # * infinite scrolling or pagination
+    # * automatic default attribute configuration (overridable via config)
+    # * multi-line CRUD operations
+    # * adding/editing records via a form
+    # * editing multiple records simultaneously
+    # * one-to-many association support
+    # * server-side sorting and filtering
+    # * permissions
+    # * persistent column resizing, moving and toggling
+    # * complex query search with preset management
+    #
+    # Client-side methods are documented here: http://api.netzke.org/client/classes/Netzke.Grid.Base.html.
+    #
+    # == Configuration
+    #
+    # The following config options are supported:
+    #
+    # [model]
+    #
+    #   Name of the ActiveRecord model that provides data to this Grid (e.g. "User") or the model's class (e.g. User).
+    #   Required.
+    #
+    # [columns]
+    #
+    #   Explicit list of columns to be displayed in the grid; each column may be represented by a symbol (attribute name),
+    #   or a hash, which contains the +name+ key pointing to the attribute name and additional configuration keys (see
+    #   the "Configuring attributes" section below). For example:
+    #
+    #      class Users < Netzke::Grid::Base
+    #        def configure(c)
+    #          super
+    #          c.model = User
+    #          c.columns = [
+    #            :first_name,
+    #            :last_name,
+    #            { name: :salary, with: 50 }
+    #          ]
+    #        end
+    #      end
+    #
+    #   Defaults to model attribute list.
+    #
+    #   Note, that you can also individually override column configs (e.g. setting a column's width) by using the
+    #   +column+ DSL method (see +Basepack::Columns+), and override attributes (e.g. making an attribute read-only) by
+    #   using the +attribute+ DSL method (see +Basepack::Attributes+).
+    #
+    # [form_items]
+    #
+    #   Array of form items. This may define arbitrary form layout. An item that represents a specific attribute, should
+    #   be specified as either a symbol (attribute name), or a hash containing the +name+ key pointing to the attribute
+    #   name, as well as additional configuration keys.
+    #
+    #      class Users < Netzke::Basepack::Grid
+    #        def configure(c)
+    #          super
+    #          c.model = User
+    #          c.form_items = [
+    #            {
+    #              xtype: 'fieldset', title: 'Name', items: [:first_name, :last_name]
+    #            },
+    #            { name: :salary, disabled: true }
+    #          ]
+    #        end
+    #      end
+    #
+    #   Defaults to model attribute list.
+    #
+    # [attribute_overrides]
+    #
+    #   Hash of per-attribute configurations. This allows overriding attributes configs that will be reflected by both
+    #   corresponding grid column and form field.
+    #
+    #   Using this option may be convenient when building composite components containing multiple grids. From inside a
+    #   given grid class it's easier to use the +attribute+ DSL method (see "Configuring attributes").
+    #
+    # [scope]
+    #
+    #   A Proc object used to scope out grid data. Receives the current relation as a parameter and must return the
+    #   modified relation. For example:
+    #
+    #      class Books < Netzke::Basepack::Grid
+    #        def configure(c)
+    #          c.model = "Book"
+    #          super
+    #          c.scope = lambda {|r| r.where(author_id: 1) }
+    #        end
+    #      end
+    #
+    # [strong_values]
+    #
+    #   A hash of attributes to be merged atop of every created/updated record, e.g. +role_id: 1+
+    #
+    # [edit_inline]
+    #   Whether record editing should happen inline (as opposed to using a form). When set to +true+, automatically sets
+    #   +paging+ to +true+. Defaults to +false+.
+    #
+    # [context_menu]
+    #
+    #   An array of actions (e.g. [:edit, "-", :delete] - see the Actions section) or +false+ to disable the context menu.
+    #
+    # [paging]
+    #
+    #   Set to +true+ to use pagination instead of infinite scrolling. Is automatically set to
+    #   +true+ if +edit_inline+ is +true+. Defaults to +false+.
+    #
+    # [store_config]
+    #
+    #   Extra configuration for the JS class's internal store (Ext.data.ProxyStore), which will override Netzke's
+    #   defaults. For example, to modify amount of records per page (defaults to 25), do:
+    #
+    #     def configure(c)
+    #       c.paging = true
+    #       c.store_config = {page_size: 100}
+    #       super
+    #     end
+    #
+    #   Another example, enable (multi) sorting initially:
+    #
+    #     def configure(c)
+    #       c.store_config = {sorters: [:title, {property: :author__first_name, direction: :DESC}]}
+    #       super
+    #     end
+    #
+    # [disable_dirty_page_warning]
+    #
+    #   Do not warn the user about dirty records on the page when changing the page. Defaults to +false+.
+    #
+    # [permissions]
+    #
+    #   Hash that can have a combination of the following boolean keys: +create+, +read+, +update+, +delete+ that
+    #   set corresponding permissions on the grid. For example, to disable deleting records:
+    #
+    #       c.permissions = {delete: false}
+    #
+    # == Configuring attributes (columns and form fields)
+    #
+    # === Overriding individual attributes
+    #
+    # To override configuration for a specific attribute, you may either use the +attribute_overrides+ configuration
+    # option (see above), or the +attribute+ DSL method, for example:
+    #
+    #      class Books < Netzke::Grid::Base
+    #        attribute :price do |c|
+    #          c.read_only = true
+    #        end
+    #
+    #        def configure(c)
+    #          c.model = Book
+    #          super
+    #        end
+    #      end
+    #
+    # This will make the 'price' column (as well as corresponding form field) read-only.
+    #
+    # The same DSL method may be used for defining virtual attributes. For details, refer to +Basepack::Attributes+.
+    #
+    # === Overriding individual column settings
+    #
+    # To override configuration for a column (like making the column hidden or specyfing its initial width), either add
+    # the +column_config+ key to the +attribute_overrides+ (see above), or use the +column+ DSL method, for example:
+    #
+    #       column :full_name do |c|
+    #         c.width = 200
+    #       end
+    #
+    # For details, refer to +Basepack::Columns+.
+    #
+    # === Specifying column list
+    #
+    # To explicitely specify columns in the grid, use the +columns+ config option, or override +Grid#columns+:
+    #
+    #     def columns
+    #       super + [:extra_column]
+    #     end
+    #
+    # == One-to-many association support
+    #
+    # If the model bound to a grid +belongs_to+ another model, Grid can display an "assocition column" - where the user
+    # can select the associated record from a drop-down box. You can specify which method of the association should be
+    # used as the display value for the drop-down box options by using the double-underscore notation on the column
+    # name, where the association name is separated from the association method by "__" (double underscore). For
+    # example, let's say we have a Book that +belongs_to+ model Author, and Author responds to +first_name+. This way,
+    # the book grid can have a column defined as follows:
+    #
+    #     {name: "author__first_name"}
+    #
+    # Grid will detect it to be an association column, and will use the drop-down box for selecting an author, where the
+    # list of authors will be represented by the author's first name.
+    #
+    # In order to scope out the records displayed in the drop-down box, the +scope+ column option can be used, e.g.:
+    #
+    #     {name: "author__first_name", scope: lambda {|relation| relation.where(popular: true).limit(10)}
+    #
+    # == Add/Edit forms
+    #
+    # Add/Edit forms are each wrapped in a separate +Window::Base+-descending component (called +RecordFormWindow+
+    # for the add/edit forms, and can be overridden individually as any other child component.
+    #
+    # === Overriding form windows
+    #
+    # Override the following direct child components to change the looks of the pop-up windows: +:add_window+,
+    # +:edit_window+, +:multiedit_window+, and +:search_window+. For example, to override the title of the Add form,
+    # do:
+    #
+    #     component :add_window do |c|
+    #       super c
+    #       c.title = "Adding new record"
+    #       c.width = "90%"
+    #     end
+    #
+    # === Modifying forms
+    #
+    # The forms will by default display the fields that correspond to the configured columns, taking over meaningful
+    # configuration options (e.g. +text+ will be converted into +fieldLabel+).
+    # You may override the default fields displayed in the all add/edit forms by overriding the
+    # +default_form_items+ method, which should return an array understood by the +items+ config property of the
+    # +Form+. If you need to use a custom +Form::Base+-descending class instead of +Form+, you need to override the
+    # +configure_form_window+ method:
+    #
+    #     def configure_form_window(c)
+    #       super
+    #       c.form_config.klass = UserForm
+    #     end
+    #
+    # To individually override forms, you should override the wrapping window components, as shown in the previous
+    # session. E.g., to modify the set of fields in the Add form:
+    #
+    #     component :add_window do |c|
+    #       super c
+    #       c.form_config.items = [:title]
+    #     end
+    #
+    # == Actions
+    #
+    # You can override Grid's actions to change their text, icons, and tooltips (see
+    # http://rdoc.info/github/netzke/netzke-core/Netzke/Core/Actions).
+    #
+    # Grid implements the following actions:
+    #
+    # [add]
+    #
+    #   Add record
+    #
+    # [delete]
+    #
+    #   Delete record(s)
+    #
+    # [edit]
+    #
+    #   Edit record(s)
+    #
+    # [apply]
+    #
+    #   Applying inline changes (after inline adding/editing of record)
+    #
+    # [search]
+    #
+    #   Show advanced search query builder
+    class Base < Netzke::Base
+      include Netzke::Grid::Configuration
+      include Netzke::Grid::Endpoints
+      include Netzke::Grid::Services
+      include Netzke::Grid::Actions
+      include Netzke::Grid::Components
+      include Netzke::Grid::Permissions
+      include Netzke::Grid::Client
+      include Netzke::Basepack::Attributes
+      include Netzke::Basepack::Columns
+      include Netzke::Basepack::DataAccessor
+
+      client_class do |c|
+        c.extend = "Ext.grid.Panel"
+        c.include :advanced_search
+        c.include :remember_selection
+
+        c.mixins << "Netzke.Grid.Columns"
+        c.mixins << "Netzke.Grid.EventHandlers"
+
+        c.translate :are_you_sure, :confirmation, :proceed_with_unapplied_changes
+
+        c.require :extensions
+      end
+    end
+  end
+end