netzke-core 0.4.4 → 0.4.5

data/CHANGELOG.rdoc

@@ -1,3 +1,17 @@
+= edge
+* API change: Netzke::Base: <tt>id_name</tt> accessor renamed to <tt>global_id</tt>
+* Code: several internal code changes
+* Code: lightly better test coverage
+* New: <tt>Netzke::Base#global_id_by_reference</tt> method
+* Compatibility: resolving conflicts with the <tt>api</tt> property in some Ext v3.0 components
+* Fix: <tt>load_aggregatee_with_cache</tt> was throwing exception when the requested aggregatee wasn't defined
+* New: <tt>persistent_config_id</tt> configuration option allows specifying an id by which persistent configuration is identified for the widget. Handy if different homogeneous widgets need to share the same persistent configuration.
+* New: <tt>Netzke::Base#persistent_config</tt> method now accepts an optional boolean parameter signalizing that the configuration is global (not bound to a widget)
+* Impr: cleaner handling of actions and toolbars; fbar configuration introduced.
+* Impr: calling an API method now provides for the result value (if return by the server) in the callback.
+* Impr: allows name spaced creation of Netzke widgets, e.g. widgets can now be defined under any module under Netzke, not only *directly* under Netzke.
+* New: support for Ext.Window-based widgets (it'll call show() on them when the "*_widget_render" helper is used).
+
 = v0.4.4 - 2009-10-12
 * API change: default handlers for actions and tools are now supposed to be prefixed with "on". E.g.: if you declare an action named <tt>clear_table</tt>, the handler must be called (in Ruby) <tt>on_clear_table</tt> (mapped to <tt>onClearTable</tt> in JavaScript).
 * Internal: the JavaScript instance now knows if persistent config is enabled (by checking this.persistentConfig).

data/README.rdoc

@@ -6,10 +6,15 @@ This is the bare bones of the Netzke framework. Use it to build your own widgets
 The idea behind the Netzke framework is that it allows you write reusable client/server code. Create a widget, and then embed it (or load it dynamically) into your Ext-based applications or HTML pages. For more info, see the links below.
 
 == Instalation
-  
+The gem is hosted on gemcutter. If you haven't yet enabled gemcutter, run the following:
+
+    sudo gem install gemcutter && gem tumble
+
+Install the gem 
+
     sudo gem install netzke-core
     
-If you want the most recent changes, install this as a plugin:
+If you want to experiment with the most recent changes, install this as a plugin:
 
     script/plugin install git://github.com/skozlov/netzke-core.git
     

data/Rakefile

@@ -1,20 +1,22 @@
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |gemspec|
+    gemspec.version = "0.4.5"
     gemspec.name = "netzke-core"
     gemspec.summary = "Build ExtJS/Rails widgets with minimum effort"
-    gemspec.description = "Build ExtJS/Rails widgets with minimum effort"
+    gemspec.description = "Allows building ExtJS/Rails reusable code in a DRY way"
     gemspec.email = "sergei@playcode.nl"
     gemspec.homepage = "http://github.com/skozlov/netzke-core"
     gemspec.rubyforge_project = "netzke-core"
     gemspec.authors = ["Sergei Kozlov"]
   end
-  Jeweler::RubyforgeTasks.new do |rubyforge|
-    rubyforge.doc_task = "rdoc"
-  end
+  Jeweler::GemcutterTasks.new
+  # Jeweler::RubyforgeTasks.new do |rubyforge|
+  #   rubyforge.doc_task = "rdoc"
+  # end
     
 rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
 end
 
 require 'rake/rdoctask'

data/javascripts/core.js

@@ -4,8 +4,7 @@ This file gets loaded along with the rest of Ext library at the initial load
 
 Ext.BLANK_IMAGE_URL = "/extjs/resources/images/default/s.gif";
 Ext.namespace('Ext.netzke'); // namespace for extensions that depend on Ext
-Ext.namespace('Netzke'); // namespace for extensions that do not depend on Ext
-Ext.netzke.cache = {};
+Ext.namespace('Netzke.classes'); // namespace for extensions that do not depend on Ext
 
 Ext.QuickTips.init(); // seems obligatory in Ext v2.2.1, otherwise Ext.Component#destroy() stops working properly
 
@@ -88,18 +87,19 @@ Ext.widgetMixIn = {
   height: 400,
   // width: 800,
   border: false,
-  is_netzke: true, // to distinguish Netzke components from regular Ext components
+  isNetzke: true, // to distinguish Netzke components from regular Ext components
+  latestResult: {}, // latest result returned from the server via an API call
   
   /*
   Loads aggregatee into a container.
   */
   loadAggregatee: function(params){
-    // params that will be provided for the server API call (load_aggregatee_with_cache); all what's passed in params.params is merged in
+    // params that will be provided for the server API call (load_aggregatee_with_cache); all what's passed in params.params is merged in. This way we exclude from sending along such things as :scope, :callback, etc.
     var apiParams = Ext.apply({id: params.id, container: params.container}, params.params); 
     
     // build the cached widgets list to send it to the server
     var cachedWidgetNames = [];
-    for (name in Ext.netzke.cache) {
+    for (name in Netzke.classes) {
       cachedWidgetNames.push(name);
     }
     apiParams.cache = Ext.encode(cachedWidgetNames);
@@ -112,7 +112,7 @@ Ext.widgetMixIn = {
     // visually disable the container while the widget is being loaded
     // Ext.getCmp(params.container).disable();
 
-    Ext.getCmp(params.container).removeChild(); // remove the old widget
+    if (params.container) Ext.getCmp(params.container).removeChild(); // remove the old widget if the container is specified
     
     // do the remote API call
     this.loadAggregateeWithCache(apiParams);
@@ -177,7 +177,11 @@ Ext.widgetMixIn = {
   */
   renderWidgetInContainer : function(params){
     var cont = Ext.getCmp(params.container);
-    cont.instantiateChild(params.config);
+    if (cont) {
+      cont.instantiateChild(params.config);
+    } else {
+      this.instantiateChild(params.config);
+    }
   },
   
   /*
@@ -261,13 +265,18 @@ Ext.widgetMixIn = {
     }
   },
   
-  // Common handler for actions
-  actionHandler : function(action){
+  // Common handler for all widget's actions. <tt>comp</tt> is the Component that triggered the action (e.g. button or menu item)
+  actionHandler : function(comp){
+    var actionName = comp.name;
     // If firing corresponding event doesn't return false, call the handler
-    if (this.fireEvent(action.name+'click', action)) {
-      var methodName = action.fn || "on"+action.name.camelize();
-      if (!this[methodName]) {throw "Netzke: handler for action '" + action.name + "' is undefined"}
-      this[methodName](action);
+    if (this.fireEvent(actionName+'click', comp)) {
+      var action = this.actions[actionName];
+      var customHandler = action.initialConfig.customHandler;
+      var methodName = (customHandler && customHandler.camelize(true)) || "on" + actionName.camelize();
+      if (!this[methodName]) {throw "Netzke: action handler '" + methodName + "' is undefined"}
+      
+      // call the handler passing it the triggering component
+      this[methodName](comp);
     }
   },
 
@@ -292,10 +301,10 @@ Ext.widgetMixIn = {
           // execute commands from server
           this.bulkExecute(Ext.decode(response.responseText));
           
-          // provade callback if needed
+          // provide callback if needed
           if (typeof callback == 'function') { 
             if (!scope) scope = this;
-            callback.apply(scope);
+            callback.apply(scope, [this.latestResult]);
           }
         }
       },
@@ -303,9 +312,15 @@ Ext.widgetMixIn = {
     });
   },
 
-  /* Parse the bbar and tbar (both Arrays), replacing the strings with the corresponding methods. For example:
-    replaceStringsWithActions( ['add', {text:'Menu', menu:['edit', 'delete']}] )
-    => [scope.actions['add'], {text:'Menu', menu:[scope.actions['edit'], scope.actions['delete']]}]
+  setResult: function(result) {
+    this.latestResult = result;
+  },
+
+  /* Normalize an array of abstracted button configs into an array of Ext button configs according to the following rules:
+    - if the element is a string and <tt>scope</tt> has an action with this name, replace this element with that action; if <tt>scope</tt> has no corresponding action, don't do anything (Ext will take care of it - display as text, or a separator, etc)
+    - if the element is an object, then:
+    -- if this object has a <tt>menu</tt> property - it's a nested menu; the value is expected to be an array of abstracted button configs, so, proceed recursively.
+    -- if this object has a <tt>handler</tt> property and the value correspond to a function in <tt>scope</tt> - replace this value with the reference to that function
   */
   normalizeMenuItems: function(arry, scope){
     var res = []; // new array
@@ -315,58 +330,64 @@ Ext.widgetMixIn = {
         if (scope.actions[camelized]){
           res.push(scope.actions[camelized]);
         } else {
-          // if there's no action with this name, maybe it's a separator or something
+          // if there's no action with this name, maybe it's a separator or text or whatever
           res.push(o);
         }
       } else if (Netzke.isObject(o)) {
         // look inside the objects...
-        for (var key in o) {
-          if (Ext.isArray(o[key])) {
-            // ... and recursively process inner arrays found
-            o[key] = this.normalizeMenuItems(o[key], scope);
-          }
+        if (o.menu) {
+          // ... and recursively process nested menus
+          o.menu = this.normalizeMenuItems(o.menu, scope);
+        } else if (o.handler && Ext.isFunction(scope[o.handler.camelize(true)])) {
+          // This button config has a handler specified as string - replace it with reference to a real function if it exists
+          o.handler = scope[o.handler.camelize(true)];
         }
         res.push(o);
       }
     }, this);
+    
+    delete arry;
+    
     return res;
   },
   
 
-  // Every Netzke widget 
+  // Code run before calling Ext's constructor - normalizing config to provide Netzke additional functionality
   commonBeforeConstructor : function(config){
-    this.actions = {};
-
-    // Generate methods for api points
-    if (!config.api) { config.api = []; }
-    config.api.push('load_aggregatee_with_cache'); // all netzke widgets get this API
-    Ext.each(config.api, function(intp){
+    // Dynamically create methods for api points, so that we could later call them like: this.myApiMethod()
+    var apiPoints = config.netzkeApi || [];
+    apiPoints.push('load_aggregatee_with_cache'); // all netzke widgets get this API point
+    Ext.each(apiPoints, function(intp){
       this[intp.camelize(true)] = function(args, callback, scope){ this.callServer(intp, args, callback, scope); }
     }, this);
 
-    // Create Ext.Actions based on config.actions
+    // This will contain Ext.Action instances
+    this.actions = {};
+
+    // Create Ext.Action instances based on config.actions
     if (config.actions) {
-      this.testActions = {};
       for (var name in config.actions) {
         // Create an event for each action (so that higher-level widgets could interfere)
         this.addEvents(name+'click');
 
         // Configure the action
         var actionConfig = config.actions[name];
-        actionConfig.handler = this.actionHandler.createDelegate(this);
+        actionConfig.customHandler = actionConfig.handler || actionConfig.fn; //DEPRECATED: .fn is kept for backward compatibility, preferred way is to specify handler
+        actionConfig.handler = this.actionHandler.createDelegate(this); // ! this is the "wrapper-handler", which is common for all actions!
         actionConfig.name = name;
         this.actions[name] = new Ext.Action(actionConfig);
       }
-
-      config.bbar = config.bbar && this.normalizeMenuItems(config.bbar, this);
-      config.tbar = config.tbar && this.normalizeMenuItems(config.tbar, this);
-      config.menu = config.menu && this.normalizeMenuItems(config.menu, this);
-      config.contextMenu = config.contextMenu && this.normalizeMenuItems(config.contextMenu, this);
       
       // TODO: need to rethink this action related stuff
       config.actions = this.actions;
-      
     }
+    
+    config.bbar = config.bbar && this.normalizeMenuItems(config.bbar, this);
+    config.tbar = config.tbar && this.normalizeMenuItems(config.tbar, this);
+    config.fbar = config.fbar && this.normalizeMenuItems(config.fbar, this);
+    config.contextMenu = config.contextMenu && this.normalizeMenuItems(config.contextMenu, this);
+
+    config.menu = config.menu && this.normalizeMenuItems(config.menu, this);
 
     // Normalize tools
     if (config.tools) {
@@ -382,7 +403,13 @@ Ext.widgetMixIn = {
     }
     
     // Set title
-    if (!config.title) config.title = config.id.humanize();
+    if (!config.title) {
+      config.title = config.id.humanize();
+    } else {
+      if (config.mode === "config") {
+        config.title = config.title + ' (' + config.id + ')';
+      }
+    }
   },
 
   // At this moment component is fully initializied
@@ -486,17 +513,30 @@ Ext.override(Ext.Container, {
     return this.items ? this.items.get(0) : null; // need this check in case when the container is not yet rendered, like an inactive tab in the TabPanel
   },
   
+  // Remove the child
   removeChild : function(){
     this.remove(this.getWidget());
   },
 
-  instantiateChild : function(config){
-    this.remove(this.getWidget()); // first delete previous widget 
-
-    if (!config) return false; // simply remove current widget if null is passed
+  // Given a scoped class name, returns the actual class, e.g.: "Netzke.GridPanel" => Netzke.classes.Netzke.GridPanel
+  classifyScopedName : function(n){
+    var klass = Netzke.classes;
+    Ext.each(n.split("."), function(s){
+      klass = klass[s];
+    });
+    return klass;
+  },
 
-    var instance = new Ext.netzke.cache[config.widgetClassName](config);
-    this.add(instance);
-    this.doLayout();
+  // Instantiates an aggregatee by its config. If it appears to be a window, shows it instead of adding as item.
+  instantiateChild : function(config){
+    var klass = this.classifyScopedName(config.scopedClassName);
+    var instance = new klass(config);
+    if (instance.isXType("netzkewindow")) {
+      instance.show();
+    } else {
+      this.remove(this.getWidget()); // first delete previous widget 
+      this.add(instance);
+      this.doLayout();
+    }
   }
 });

data/lib/netzke/base.rb

@@ -38,138 +38,129 @@ module Netzke
   #     netzke :form_panel, 
   #       :data_class_name => "User" # FormPanel specific option
   class Base
+    extend ActiveSupport::Memoizable
+    
     include Netzke::BaseJs # javascript (client-side)
 
-    module ClassMethods
-      # Class-level Netzke::Base configuration. The defaults also get specified here.
-      def config
-        set_default_config({
-          # which javascripts and stylesheets must get included at the initial load (see netzke-core.rb)
-          :javascripts               => [],
-          :stylesheets               => [],
-          
-          :persistent_config_manager => "NetzkePreference",
-          :ext_location              => defined?(RAILS_ROOT) && "#{RAILS_ROOT}/public/extjs",
-          :default_config => {
-            :persistent_config => true
-          }
-        })
-      end
-
-      def configure(*args)
-        if args.first.is_a?(Symbol)
-          # first arg is a Symbol
-          config[args.first] = args.last
-        else
-          config.deep_merge!(args.first)
-        end
-
-        enforce_config_consistency
+    attr_accessor :parent, :name, :global_id, :permissions, :session
+
+    # Class-level Netzke::Base configuration. The defaults also get specified here.
+    def self.config
+      set_default_config({
+        # which javascripts and stylesheets must get included at the initial load (see netzke-core.rb)
+        :javascripts               => [],
+        :stylesheets               => [],
+        
+        :persistent_config_manager => "NetzkePreference",
+        :ext_location              => defined?(RAILS_ROOT) && "#{RAILS_ROOT}/public/extjs",
+        :default_config => {
+          :persistent_config => true
+        }
+      })
+    end
+    
+    def self.set_default_config(c) #:nodoc:
+      @@config ||= {}
+      @@config[self.name] ||= c
+    end
+    
+    # Override class-level defaults specified in <tt>Netzke::Base.config</tt>. 
+    # E.g. in config/initializers/netzke-config.rb:
+    # 
+    #     Netzke::GridPanel.configure :default_config => {:persistent_config => true}
+    def self.configure(*args)
+      if args.first.is_a?(Symbol)
+        config[args.first] = args.last
+      else
+        # first arg is hash
+        config.deep_merge!(args.first)
       end
       
-      def enforce_config_consistency; end
-
-      # "Netzke::SomeWidget" => "SomeWidget"
-      def short_widget_class_name
-        self.name.split("::").last
-      end
-
-      # Multi-user support (deprecated in favor of controller sessions)
-      def user
-        @@user ||= nil
-      end
-
-      def user=(user)
-        @@user = user
-      end
-
-      # Access to controller sessions
-      def session
-        @@session ||= {}
-      end
+      # widget may implement some kind of control for configuration consistency
+      enforce_config_consistency if respond_to?(:enforce_config_consistency)
+    end
+    
+    # Short widget class name, e.g.: 
+    #   Netzke::Module::SomeWidget => Module::SomeWidget
+    def self.short_widget_class_name
+      self.name.sub("Netzke::", "")
+    end
 
-      def session=(s)
-        @@session = s
-      end
+    # Access to controller sessions
+    def self.session
+      @@session ||= {}
+    end
 
-      # called by controller at the moment of successfull login
-      def login
-        session[:_netzke_next_request_is_first_after_login] = true
-      end
-      
-      # called by controller at the moment of logout
-      def logout
-        session[:_netzke_next_request_is_first_after_logout] = true
-      end
+    def self.session=(s)
+      @@session = s
+    end
 
-      # Use this class method to declare connection points between client side of a widget and its server side. 
-      # A method in a widget class with the same name will be (magically) called by the client side of the widget. 
-      # See netzke-basepack's GridPanel for an example.
-      def api(*api_points)
-        apip = read_inheritable_attribute(:api_points) || []
-        api_points.each{|p| apip << p}
-        write_inheritable_attribute(:api_points, apip)
-
-        # It may be needed later for security
-        api_points.each do |apip|
-          module_eval <<-END, __FILE__, __LINE__
-          def api_#{apip}(*args)
-            #{apip}(*args).to_nifty_json
-          end
-          # FIXME: commented out because otherwise ColumnOperations stop working
-          # def #{apip}(*args)
-          #   flash :warning => "API point '#{apip}' is not implemented for widget '#{short_widget_class_name}'"
-          #   {:flash => @flash}
-          # end
-          END
+    # Should be called by session controller at the moment of successfull login
+    def self.login
+      session[:_netzke_next_request_is_first_after_login] = true
+    end
+    
+    # Should be called by session controller at the moment of logout
+    def self.logout
+      session[:_netzke_next_request_is_first_after_logout] = true
+    end
+
+    # Declare connection points between client side of a widget and its server side. For example:
+    #
+    #     api :reset_data
+    # 
+    # will provide JavaScript side with a method <tt>resetData</tt> that will result in a call to Ruby 
+    # method <tt>reset_data</tt>, e.g.:
+    # 
+    #     this.resetData({hard:true});
+    # 
+    # See netzke-basepack's GridPanel for an example.
+    def self.api(*api_points)
+      apip = read_inheritable_attribute(:api_points) || []
+      api_points.each{|p| apip << p}
+      write_inheritable_attribute(:api_points, apip)
+
+      # It may be needed later for security
+      api_points.each do |apip|
+        module_eval <<-END, __FILE__, __LINE__
+        def api_#{apip}(*args)
+          #{apip}(*args).to_nifty_json
         end
+        # FIXME: commented out because otherwise ColumnOperations stop working
+        # def #{apip}(*args)
+        #   flash :warning => "API point '#{apip}' is not implemented for widget '#{short_widget_class_name}'"
+        #   {:flash => @flash}
+        # end
+        END
       end
+    end
 
-      def api_points
-        read_inheritable_attribute(:api_points)
-      end
-      
-      # returns an instance of a widget defined in the config
-      def instance_by_config(config)
-        widget_class = "Netzke::#{config[:widget_class_name]}".constantize
-        widget_class.new(config)
-      end
-      
-      # persistent_config and layout manager classes
-      def persistent_config_manager_class
-        Netzke::Base.config[:persistent_config_manager].try(:constantize)
-      rescue NameError
-        nil
-      end
+    api :load_aggregatee_with_cache # every widget gets this api
 
-      # Return persistent config class
-      def persistent_config
-        # if the class is not present, fake it (it will not store anything, and always return nil)
-        if persistent_config_manager_class.nil?
-          {}
-        else
-          persistent_config_manager_class
-        end
-      end
-      
-      private
-      def set_default_config(c)
-        @@config ||= {}
-        @@config[self.name] ||= c
-      end
-      
+    # Array of API-points specified with <tt>Netzke::Base.api</tt> method
+    def self.api_points
+      read_inheritable_attribute(:api_points)
     end
-    extend ClassMethods
     
-    # If the widget has persistent config in its disposal
-    def persistent_config_enabled?
-      !persistent_config_manager_class.nil? && config[:persistent_config]
+    # Instance of widget by config
+    def self.instance_by_config(config)
+      widget_class = "Netzke::#{config[:widget_class_name]}".constantize
+      widget_class.new(config)
     end
     
-    attr_accessor :parent, :name, :id_name, :permissions, :session
-
-    api :load_aggregatee_with_cache # every widget gets this api
+    # Persistent config manager class
+    def self.persistent_config_manager_class
+      Netzke::Base.config[:persistent_config_manager].try(:constantize)
+    rescue NameError
+      nil
+    end
 
+    # Return persistent config class
+    # def self.persistent_config
+    #   # if the class is not present, fake it (it will not store anything, and always return nil)
+    #   persistent_config_manager_class || {}
+    # end
+    
     # Widget initialization process
     # * the config hash is available to the widget after the "super" call in the initializer
     # * override/add new default configuration options into the "default_config" method 
@@ -179,49 +170,78 @@ module Netzke
       @passed_config = config # configuration passed at the moment of instantiation
       @parent        = parent
       @name          = config[:name].nil? ? short_widget_class_name.underscore : config[:name].to_s
-      @id_name       = parent.nil? ? @name : "#{parent.id_name}__#{@name}"
+      @global_id     = parent.nil? ? @name : "#{parent.global_id}__#{@name}"
       @flash         = []
     end
 
-    # add flatten method to Hash
-    Hash.class_eval do 
-      def flatten(preffix = "")
-        res = []
-        self.each_pair do |k,v|
-          if v.is_a?(Hash)
-            res += v.flatten(k)
-          else
-            res << {
-              :name => ((preffix.to_s.empty? ? "" : preffix.to_s + "__") + k.to_s).to_sym, 
-              :value => v,
-              :type => (["TrueClass", "FalseClass"].include?(v.class.name) ? 'Boolean' : v.class.name).to_sym
-            }
-          end
-        end
-        res
-      end
-    end
+    #
+    # Configuration
+    # 
 
+    # Default config - before applying any passed configuration
     def default_config
-      self.class.config[:default_config].nil? ? {} : {}.merge!(self.class.config[:default_config])
+      self.class.config[:default_config].nil? ? {} : {}.merge(self.class.config[:default_config])
+    end
+    
+    # Static, hardcoded config. Consists of default values merged with config that was passed during instantiation
+    def initial_config
+      default_config.deep_merge(@passed_config)
+    end
+    memoize :initial_config
+    
+    # Config that is not overwritten by parents and sessions
+    def independent_config
+      initial_config.deep_merge(persistent_config_hash)
     end
+    memoize :independent_config
 
-    # Access to the config that takes into account all possible ways to configure a widget. *Read only*.
+    # If the widget has persistent config in its disposal
+    def persistent_config_enabled?
+      !persistent_config_manager_class.nil? && initial_config[:persistent_config]
+    end
+
+    # Store some setting in the database as if it was a hash, e.g.:
+    #     persistent_config["window.size"] = 100
+    #     persistent_config["window.size"] => 100
+    # This method is user-aware
+    def persistent_config(global = false)
+      if persistent_config_enabled? || global
+        config_class = self.class.persistent_config_manager_class
+        config_class.widget_name = global ? nil : persistent_config_id # pass to the config class our unique name
+        config_class
+      else
+        # if we can't use presistent config, all the calls to it will always return nil, 
+        # and the "="-operation will be ignored
+        logger.debug "==> NETZKE: no persistent config is set up for widget '#{global_id}'"
+        {}
+      end
+    end
+    
+    # A string which will identify the persistent config records for this widget
+    def persistent_config_id #:nodoc:
+      initial_config[:persistent_config_id] || global_id
+    end
+    
+    def update_persistent_ext_config(hsh)
+      current_config = persistent_config[:ext_config] || {}
+      current_config.deep_merge!(hsh.convert_keys{ |k| k.to_s }) # first, recursively stringify the keys
+      persistent_config[:ext_config] = current_config
+    end
+    
+    # Resulting config that takes into account all possible ways to configure a widget. *Read only*.
+    # Translates into something like this:
+    #     default_config.
+    #     deep_merge(@passed_config).
+    #     deep_merge(persistent_config_hash).
+    #     deep_merge(strong_parent_config).
+    #     deep_merge(strong_session_config)
     def config
-      # Translates into something like this:
-      #     @config ||= default_config.
-      #                 deep_merge(@passed_config).
-      #                 deep_merge(persistent_config_hash).
-      #                 deep_merge(strong_parent_config).
-      #                 deep_merge(strong_session_config)
-      @config ||= independent_config.
-                    deep_merge(strong_parent_config).
-                    deep_merge(strong_session_config)
-                    
+      independent_config.deep_merge(strong_parent_config).deep_merge(strong_session_config)
     end
+    memoize :config
     
     def flat_config(key = nil)
-      fc = config.flatten
+      fc = config.flatten_with_type
       key.nil? ? fc : fc.select{ |c| c[:name] == key.to_sym }.first.try(:value)
     end
 
@@ -229,35 +249,33 @@ module Netzke
       @strong_parent_config ||= parent.nil? ? {} : parent.strong_children_config
     end
 
-    # Config that is not overwritten by parents and sessions
-    def independent_config
-      @independent_config ||= initial_config.deep_merge(persistent_config_hash)
-    end
-
     def flat_independent_config(key = nil)
-      fc = independent_config.flatten
+      fc = independent_config.flatten_with_type
       key.nil? ? fc : fc.select{ |c| c[:name] == key.to_sym }.first.try(:value)
     end
     
     def flat_default_config(key = nil)
-      fc = default_config.flatten
+      fc = default_config.flatten_with_type
       key.nil? ? fc : fc.select{ |c| c[:name] == key.to_sym }.first.try(:value)
     end
 
-    # Static, hardcoded config. Consists of default values merged with config that was passed during instantiation
-    def initial_config
-      @initial_config ||= default_config.deep_merge(@passed_config)
-    end
-    
     def flat_initial_config(key = nil)
-      fc = initial_config.flatten
+      fc = initial_config.flatten_with_type
       key.nil? ? fc : fc.select{ |c| c[:name] == key.to_sym }.first.try(:value)
     end
 
-    def build_persistent_config_hash
+    # Returns a hash built from all persistent config values for the current widget, following the double underscore
+    # naming convention. E.g., if we have the following persistent config pairs:
+    #     enabled  => true
+    #     layout__width => 100
+    #     layout__header__height => 20
+    # 
+    # this method will return the following hash:
+    #     {:enabled => true, :layout => {:width => 100, :header => {:height => 20}}}
+    def persistent_config_hash
       return {} if !initial_config[:persistent_config]
       
-      prefs = NetzkePreference.find_all_for_widget(id_name)
+      prefs = NetzkePreference.find_all_for_widget(persistent_config_id)
       res = {}
       prefs.each do |p|
         hsh_levels = p.name.split("__").map(&:to_sym)
@@ -273,13 +291,10 @@ module Netzke
         # So we need to recursively merge it into the final result
         res.deep_merge!(hsh_levels.first => anchor)
       end
-      res
-    end
-
-    def persistent_config_hash
-      @persistent_config_hash ||= build_persistent_config_hash
+      res.convert_keys{ |k| k.to_sym } # recursively symbolize the keys
     end
-
+    memoize :persistent_config_hash
+    
     def ext_config
       config[:ext_config] || {}
     end
@@ -313,7 +328,7 @@ module Netzke
     end
     
     def widget_session
-      session[id_name] ||= {}
+      session[global_id] ||= {}
     end
 
     # Rails' logger
@@ -330,22 +345,6 @@ module Netzke
       res.uniq
     end
     
-    # Store some setting in the database as if it was a hash, e.g.:
-    #     persistent_config["window.size"] = 100
-    #     persistent_config["window.size"] => 100
-    # This method is user-aware
-    def persistent_config
-      if config[:persistent_config]
-        config_class = self.class.persistent_config
-        config_class.widget_name = id_name # pass to the config class our unique name
-        config_class
-      else
-        # if we can't use presistent config, all the calls to it will always return nil, and the "="-operation will be ignored
-        logger.debug "==> NETZKE: no persistent config is set up for widget '#{id_name}'"
-        {}
-      end
-    end
-    
     # 'Netzke::Grid' => 'Grid'
     def short_widget_class_name
       self.class.short_widget_class_name
@@ -383,7 +382,7 @@ module Netzke
     
     def remove_aggregatee(aggr)
       if config[:persistent_config]
-        persistent_config_manager_class.delete_all_for_widget("#{id_name}__#{aggr}")
+        persistent_config_manager_class.delete_all_for_widget("#{global_id}__#{aggr}")
       end
       aggregatees[aggr] = nil
     end
@@ -403,9 +402,9 @@ module Netzke
       name.to_s.split('__').each do |aggr|
         aggr = aggr.to_sym
         aggregatee_config = aggregator.aggregatees[aggr]
-        raise ArgumentError, "No aggregatee '#{aggr}' defined for widget '#{aggregator.id_name}'" if aggregatee_config.nil?
+        raise ArgumentError, "No aggregatee '#{aggr}' defined for widget '#{aggregator.global_id}'" if aggregatee_config.nil?
         short_class_name = aggregatee_config[:widget_class_name]
-        raise ArgumentError, "No widget_class_name specified for aggregatee #{aggr} of #{aggregator.id_name}" if short_class_name.nil?
+        raise ArgumentError, "No widget_class_name specified for aggregatee #{aggr} of #{aggregator.global_id}" if short_class_name.nil?
         widget_class = "Netzke::#{short_class_name}".constantize
 
         conf = weak_children_config.
@@ -431,7 +430,7 @@ module Netzke
     end
 
     def widget_action(action_name)
-      "#{@id_name}__#{action_name}"
+      "#{@global_id}__#{action_name}"
     end
 
     # called when the method_missing tries to processes a non-existing aggregatee
@@ -458,29 +457,54 @@ module Netzke
       widget_session.clear
     end
 
-    # API: provides all that is necessary for the browser to render a widget.
-    # <tt>params</tt>
+    # Returns global id of a widget in the hierarchy, based on passed reference that follows
+    # the double-underscore notation. Referring to "parent" is allowed. If going to far up the hierarchy will 
+    # result in <tt>nil</tt>, while referring to a non-existent aggregatee will simply provide an erroneous ID.
+    # Example:
+    # <tt>parent__parent__child__subchild</tt> will traverse the hierarchy 2 levels up, then going down to "child",
+    # and further to "subchild". If such a widget exists in the hierarchy, its global id will be returned, otherwise
+    # <tt>nil</tt> will be returned.
+    def global_id_by_reference(ref)
+      ref = ref.to_s
+      return parent && parent.global_id if ref == "parent"
+      substr = ref.sub(/^parent__/, "")
+      if substr == ref # there's no "parent__" in the beginning
+        return global_id + "__" + ref
+      else
+        return parent.global_id_by_reference(substr)
+      end
+    end
+
+    # API: provides what is necessary for the browser to render a widget.
+    # <tt>params</tt> should contain: 
+    # * <tt>:cache</tt> - an array of widget classes cached at the browser
+    # * <tt>:id</tt> - reference to the aggregatee
+    # * <tt>:container</tt> - Ext id of the container where in which the aggregatee will be rendered
     def load_aggregatee_with_cache(params)
       cache = ActiveSupport::JSON.decode(params.delete(:cache))
-      relative_widget_id = params.delete(:id).underscore
-      widget = aggregatee_instance(relative_widget_id)
+      relative_widget_id = params.delete(:id).underscore.to_sym
+      widget = aggregatees[relative_widget_id] && aggregatee_instance(relative_widget_id)
       
-      # inform the widget that it's being loaded
-      widget.before_load
+      if widget
+        # inform the widget that it's being loaded
+        widget.before_load
       
-      [{
-        :js => widget.js_missing_code(cache), 
-        :css => widget.css_missing_code(cache)
-      }, {
-        :render_widget_in_container => {
-          :container => params[:container], 
-          :config => widget.js_config
-        }
-      }, {
-        :widget_loaded => {
-          :id => relative_widget_id
-        }
-      }]
+        [{
+          :js => widget.js_missing_code(cache), 
+          :css => widget.css_missing_code(cache)
+        }, {
+          :render_widget_in_container => { # TODO: rename it
+            :container => params[:container], 
+            :config => widget.js_config
+          }
+        }, {
+          :widget_loaded => {
+            :id => relative_widget_id
+          }
+        }]
+      else
+        {:feedback => "Couldn't load aggregatee '#{relative_widget_id}'"}
+      end
     end
 
     # Method dispatcher - instantiates an aggregatee and calls the method on it

data/lib/netzke/base_js.rb

@@ -30,7 +30,7 @@ module Netzke
       res = {}
       
       # Unique id of the widget
-      res.merge!(:id => id_name)
+      res.merge!(:id => global_id)
   
       # Recursively include configs of all non-late aggregatees, so that the widget can instantiate them
       # in javascript immediately.
@@ -42,10 +42,11 @@ module Netzke
   
       # Api (besides the default "load_aggregatee_with_cache" - JavaScript side already knows about it)
       api_points = self.class.api_points.reject{ |p| p == :load_aggregatee_with_cache }
-      res.merge!(:api => api_points) unless api_points.empty?
+      res.merge!(:netzke_api => api_points) unless api_points.empty?
   
       # Widget class name. Needed for dynamic instantiation in javascript.
-      res.merge!(:widget_class_name => short_widget_class_name)
+      # res.merge!(:widget_class_name => short_widget_class_name)
+      res.merge!(:scoped_class_name => self.class.js_scoped_class_name)
       
       # Actions, toolbars and menus
       # tools   && res.merge!(:tools   => tools)
@@ -56,8 +57,8 @@ module Netzke
       res[:persistent_config] = persistent_config_enabled?
 
       # Merge with all config options passed as hash to config[:ext_config]
+      logger.debug "!!! ext_config: #{ext_config.inspect}\n"
       res.merge!(ext_config)
-  
 
       res
     end
@@ -84,12 +85,18 @@ module Netzke
 
     # instantiating
     def js_widget_instance
-      %Q{var #{name.jsonify} = new Ext.netzke.cache.#{short_widget_class_name}(#{js_config.to_nifty_json});}
+      %Q{var #{name.jsonify} = new #{self.class.js_full_class_name}(#{js_config.to_nifty_json});}
     end
 
     # rendering
     def js_widget_render
-      %Q{#{name.jsonify}.render("#{name.to_s.split('_').join('-')}-div");}
+      %Q{
+        if (#{name.jsonify}.isXType("netzkewindow")) {
+          #{name.jsonify}.show();
+        } else {
+          #{name.jsonify}.render("#{name.to_s.split('_').join('-')}-div");
+        }
+      }
     end
 
     # container for rendering
@@ -121,17 +128,39 @@ module Netzke
         "Ext.Panel"
       end
 
-      # functions and properties that will be used to extend the functionality of (Ext) JS-class specified in js_base_class
+      # Properties (including methods) that will be used to extend the functionality of (Ext) JS-class specified in js_base_class
       def js_extend_properties 
         {}
       end
+    
+      # Returns the scope of this widget, 
+      # e.g. "Netzke.GridPanelLib"
+      def js_scope
+        js_full_class_name.split(".")[0..-2].join(".")
+      end
+  
+      # Returns the name of the JavaScript class for this widget, including the scopes, 
+      # e.g.: "Netzke.GridPanelLib.RecordFormWindow"
+      def js_scoped_class_name
+        name.gsub("::", ".")
+      end
+
+      # Returns the full name of the JavaScript class, including the scopes *and* the common scope, which is
+      # Netzke.classes.
+      # E.g.: "Netzke.classes.Netzke.GridPanelLib.RecordFormWindow"
+      def js_full_class_name
+        "Netzke.classes." + js_scoped_class_name
+      end
+
+      # Builds this widget's xtype
+      # E.g.: netzkewindow, netzkegridpanel
+      def js_xtype
+        name.gsub("::", "").downcase
+      end
   
       # widget's menus
       def js_menus; []; end
   
-      # items
-      # def js_items; null; end
-      
       # are we using JS inheritance? for now, if js_base_class is a Netzke class - yes
       def js_inheritance?
         superclass != Netzke::Base
@@ -143,30 +172,39 @@ module Netzke
         if js_inheritance?
           # In case of using javascript inheritance, little needs to be done
           <<-END_OF_JAVASCRIPT
+          // Define the scope
+          Ext.ns("#{js_scope}");
           // Create the class
-          Ext.netzke.cache.#{short_widget_class_name} = function(config){
-            Ext.netzke.cache.#{short_widget_class_name}.superclass.constructor.call(this, config);
+          #{js_full_class_name} = function(config){
+            #{js_full_class_name}.superclass.constructor.call(this, config);
           };
           // Extend it with the class that we inherit from, and mix in js_extend_properties
-          Ext.extend(Ext.netzke.cache.#{short_widget_class_name}, Ext.netzke.cache.#{superclass.short_widget_class_name}, Ext.applyIf(#{js_extend_properties.to_nifty_json}, Ext.widgetMixIn));
+          Ext.extend(#{js_full_class_name}, #{superclass.js_full_class_name}, Ext.applyIf(#{js_extend_properties.to_nifty_json}, Ext.widgetMixIn));
+          // Register xtype
+          Ext.reg("#{js_xtype}", #{js_full_class_name});
+          
           END_OF_JAVASCRIPT
+          
         else
           js_add_menus = "this.addMenus(#{js_menus.to_nifty_json});" unless js_menus.empty?
           <<-END_OF_JAVASCRIPT
+          // Define the scope
+          Ext.ns("#{js_scope}");
           // Constructor
-          Ext.netzke.cache.#{short_widget_class_name} = function(config){
+          #{js_full_class_name} = function(config){
             // Do all the initializations that every Netzke widget should do: create methods for API-points,
             // process actions, tools, toolbars
             this.commonBeforeConstructor(config);
-            
             // Call the constructor of the inherited class
-            Ext.netzke.cache.#{short_widget_class_name}.superclass.constructor.call(this, config);
-
+            #{js_full_class_name}.superclass.constructor.call(this, config);
             // What every widget should do after calling the constructor of the inherited class, like
             // setting extra events
             this.commonAfterConstructor(config);
           };
-          Ext.extend(Ext.netzke.cache.#{short_widget_class_name}, #{js_base_class}, Ext.applyIf(#{js_extend_properties.to_nifty_json}, Ext.widgetMixIn));
+          Ext.extend(#{js_full_class_name}, #{js_base_class}, Ext.applyIf(#{js_extend_properties.to_nifty_json}, Ext.widgetMixIn));
+          // Register xtype
+          Ext.reg("#{js_xtype}", #{js_full_class_name});
+          
           END_OF_JAVASCRIPT
         end
       end

data/lib/netzke/controller_extensions.rb

@@ -9,8 +9,6 @@ module Netzke
       Netzke::Base.session = session
       session[:netzke_user_id] = defined?(current_user) ? current_user.try(:id) : nil
 
-      Netzke::Base.user = defined?(current_user) ? current_user : nil # for backward compatibility (TODO: eliminate the need for this)
-      
       # set netzke_just_logged_in and netzke_just_logged_out states (may be used by Netzke widgets)
       if session[:_netzke_next_request_is_first_after_login]
         session[:netzke_just_logged_in] = true
@@ -44,10 +42,8 @@ module Netzke
 
           # instantiate the server part of the widget
           widget_instance = widget_class.new(self.class.widget_config_storage[widget])
-          # (OLD VERSION)
-          # widget_instance = widget_class.new(self.class.widget_config_storage[widget].merge(:controller => self)) # OPTIMIZE: top-level widgets have access to the controller - can we avoid that?
-          
-          render :text => widget_instance.send(api_action, params)
+
+          render :text => widget_instance.send(api_action, params), :layout => false
         end
       end
     end

data/lib/netzke/core_ext.rb

@@ -40,6 +40,24 @@ class Hash
       h
     end
   end
+  
+  # add flatten_with_type method to Hash
+  def flatten_with_type(preffix = "")
+    res = []
+    self.each_pair do |k,v|
+      name = ((preffix.to_s.empty? ? "" : preffix.to_s + "__") + k.to_s).to_sym
+      if v.is_a?(Hash)
+        res += v.flatten_with_type(name)
+      else
+        res << {
+          :name => name, 
+          :value => v,
+          :type => (["TrueClass", "FalseClass"].include?(v.class.name) ? 'Boolean' : v.class.name).to_sym
+        }
+      end
+    end
+    res
+  end
 
   # Javascrit-like access to Hash values
   def method_missing(method, *args)

data/test/unit/core_ext_test.rb

@@ -40,27 +40,31 @@ class CoreExtTest < ActiveSupport::TestCase
     assert_equal({:aB => 1, "cD" => [[1, {:eF => "stay_same"}], {"literal_symbol" => :should_not_change, "literal_string".l => "also_should_not"}]}, {:a_b => 1, "c_d" => [[1, {:e_f => "stay_same"}], {:literal_symbol.l => :should_not_change, "literal_string".l => "also_should_not"}]}.jsonify)
   end
   
-  # test "flatten" do
-  #   assert_equal([{
-  #     :name => :one, :value => 1 
-  #   },{
-  #     :name => :two, :value => 2 
-  #   },{
-  #     :name => :three__four, :value => 4 
-  #   },{
-  #     :name => :three__five__six, :value => 6
-  #   }], 
-  #   {
-  #     :one => 1,
-  #     :two => 2,
-  #     :three => {
-  #       :four => 4,
-  #       :five => {
-  #         :six => 6
-  #       }
-  #     }
-  #   }.flatten
-  #   )
-  # end
+  test "flatten_with_type" do
+    test_flatten_with_type = {
+      :one => 1,
+      :two => 2.5,
+      :three => {
+        :four => true,
+        :five => {
+          :six => "a string"
+        }
+      }
+    }.flatten_with_type
+    
+    assert_equal(4, test_flatten_with_type.size)
+    
+    test_flatten_with_type.each do |i|
+      assert([{
+        :name => :one, :value => 1, :type => :Fixnum
+      },{
+        :name => :two, :value => 2.5, :type => :Float
+      },{
+        :name => :three__four, :value => true, :type => :Boolean
+      },{
+        :name => :three__five__six, :value => "a string", :type => :String
+      }].include?(i))
+    end
+  end
   
 end

data/test/unit/netzke_core_test.rb

@@ -43,6 +43,14 @@ module Netzke
   end
 
   class DeepNestedWidget < Base
+    def initial_aggregatees
+      {
+        :nested => {:widget_class_name => "VeryDeepNestedWidget"}
+      }
+    end
+  end
+  
+  class VeryDeepNestedWidget < Base
   end
 
   class JsInheritanceWidget < Widget
@@ -90,31 +98,22 @@ class NetzkeCoreTest < ActiveSupport::TestCase
     assert_kind_of DeepNestedWidget, deep_nested_widget
     
     # check the internal names of aggregation instances
-    assert_equal 'my_widget', widget.id_name
-    assert_equal 'my_widget__nested_one', nested_widget_one.id_name
-    assert_equal 'my_widget__nested_two', nested_widget_two.id_name
-    assert_equal 'my_widget__nested_two__nested', deep_nested_widget.id_name
+    assert_equal 'my_widget', widget.global_id
+    assert_equal 'my_widget__nested_one', nested_widget_one.global_id
+    assert_equal 'my_widget__nested_two', nested_widget_two.global_id
+    assert_equal 'my_widget__nested_two__nested', deep_nested_widget.global_id
   end
   
-  # test "permissions" do
-  #   widget = Widget.new
-  #   assert_equal({:read => true, :update => true}, widget.permissions)
-  # 
-  #   widget = Widget.new(:prohibit => :all)
-  #   assert_equal({:read => false, :update => false}, widget.permissions)
-  # 
-  #   widget = Widget.new(:prohibit => :read)
-  #   assert_equal({:read => false, :update => true}, widget.permissions)
-  # 
-  #   widget = Widget.new(:prohibit => [:read, :update])
-  #   assert_equal({:read => false, :update => false}, widget.permissions)
-  # 
-  #   widget = Widget.new(:prohibit => :all, :allow => :read)
-  #   assert_equal({:read => true, :update => false}, widget.permissions)
-  # 
-  #   widget = Widget.new(:prohibit => :all, :allow => [:read, :update])
-  #   assert_equal({:read => true, :update => true}, widget.permissions)
-  # end
+  test "global_id_by_reference" do
+    w = Widget.new(:name => "a_widget")
+    deep_nested_widget = w.aggregatee_instance(:nested_two__nested)
+    assert_equal("a_widget__nested_two", deep_nested_widget.global_id_by_reference(:parent))
+    assert_equal("a_widget", deep_nested_widget.global_id_by_reference(:parent__parent))
+    assert_equal("a_widget__nested_one", deep_nested_widget.global_id_by_reference(:parent__parent__nested_one))
+    assert_equal("a_widget__nested_two__nested__nested", deep_nested_widget.global_id_by_reference(:nested))
+    assert_equal("a_widget__nested_two__nested__non_existing", deep_nested_widget.global_id_by_reference(:non_existing))
+    assert_nil(deep_nested_widget.global_id_by_reference(:parent__parent__parent)) # too far up
+  end
   
   test "default config" do
     widget = Widget.new
@@ -145,8 +144,8 @@ class NetzkeCoreTest < ActiveSupport::TestCase
 
   test "js inheritance" do
     widget = JsInheritanceWidget.new
-    assert(widget.js_missing_code.index("Ext.netzke.cache.JsInheritanceWidget"))
-    assert(widget.js_missing_code.index("Ext.netzke.cache.Widget"))
+    assert(widget.js_missing_code.index("Netzke.classes.Netzke.JsInheritanceWidget"))
+    assert(widget.js_missing_code.index("Netzke.classes.Netzke.Widget"))
   end
 
   test "class-level configuration" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: netzke-core
 version: !ruby/object:Gem::Version 
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors: 
 - Sergei Kozlov
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-12 00:00:00 -05:00
+date: 2009-11-08 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
-description: Build ExtJS/Rails widgets with minimum effort
+description: Allows building ExtJS/Rails reusable code in a DRY way
 email: sergei@playcode.nl
 executables: []
 
@@ -31,7 +31,6 @@ files:
 - README.rdoc
 - Rakefile
 - TODO
-- VERSION
 - autotest/discover.rb
 - generators/netzke_core/USAGE
 - generators/netzke_core/netzke_core_generator.rb

data/VERSION

@@ -1 +0,0 @@
-0.4.4