netzke-core 0.3.1 → 0.4.2

data/lib/app/controllers/netzke_controller.rb

@@ -1,5 +1,9 @@
 class NetzkeController < ActionController::Base
 
+  def index
+    redirect_to :action => :test_widgets
+  end
+
   # collect javascripts from all plugins that registered it in Netzke::Base.config[:javascripts]
   def netzke
     respond_to do |format|
@@ -23,15 +27,68 @@ class NetzkeController < ActionController::Base
     end
   end
   
-  def method_missing(action)
-    respond_to do |format|
-      format.js {
-        render :text => "#{action}.js"
-      }
-      format.css {
-        render :text => "#{action}.css"
-      }
+  #
+  # Primitive tests to quickly test the widgets
+  #
+  
+  # FormPanel
+  netzke :form_panel, :persistent_config => false, :label_align => "top", :columns => [
+    {:name => 'field_one', :xtype => 'textarea'},
+    {:name => 'field_two', :xtype => 'textarea'}
+  ]
+  
+  # BorderLayoutPanel
+  netzke :border_layout_panel, :regions => {
+    :west => {
+      :widget_class_name => "Panel",
+      :region_config => {:width => 300, :split => true}
+    },
+    :center => {
+      :widget_class_name => "Panel"
+    }
+  }
+  
+  # TabPanel
+  netzke :tab_panel, :items => [{
+    :widget_class_name => "Panel",
+    :ext_config => {
+      :html => "Panel 1",  
+    },
+    # :active => true
+  },{
+    :widget_class_name => "Panel",
+    :ext_config => {
+      :html => "Panel 2",  
+    }
+  }]
+  
+  # AccordionPanel
+  netzke :accordion_panel, :items => [{
+    :widget_class_name => "Panel",
+    :ext_config => {
+      :html => "Panel 1",
+    },
+    :active => true
+  },{
+    :widget_class_name => "Panel",
+    :ext_config => {
+      :html => "Panel 2",  
+    }
+  }]
+  
+  # BasicApp
+  netzke :basic_app
+
+  netzke :panel, :ext_config => {:html => "Panel", :title => "Test panel", :border => true}
+
+  def test_widgets
+    html = "<h3>Quick primitive widgets tests</h3>"
+    
+    self.class.widget_config_storage.each_key.map(&:to_s).sort.each do |w|
+      html << "<a href='#{w}_test'>#{w.to_s.humanize}</a><br/>\n"
     end
+    
+    render :text => html
   end
-  
+
 end

data/lib/app/models/netzke_preference.rb

@@ -11,10 +11,6 @@ class NetzkePreference < ActiveRecord::Base
   
   ELEMENTARY_CONVERTION_METHODS= {'Fixnum' => 'to_i', 'String' => 'to_s', 'Float' => 'to_f', 'Symbol' => 'to_sym'}
   
-  # def self.user_id
-  #   Netzke::Base.user && Netzke::Base.user.id
-  # end
-  
   def self.widget_name=(value)
     @@widget_name = value
   end
@@ -67,18 +63,6 @@ class NetzkePreference < ActiveRecord::Base
     end
   end
 
-  # execute set/get operation for a specified widget, e.g.:
-  # NetzkePreference.for_widget('my_widget') { |p| p[:key] = "value" }
-  def self.for_widget(widget, &block)
-    raise ArgumentError, "Block is required for #{self.name}\#for_widget" if !block_given?
-    backup_widget_name = self.widget_name
-    self.widget_name = widget
-    res = yield(self)
-    self.widget_name = backup_widget_name
-    res
-  end
-
-  #
   # Overwrite pref_to_read, pref_to_write methods, and find_all_for_widget if you want a different way of 
   # identifying the proper preference based on your own authorization strategy.
   #
@@ -97,14 +81,25 @@ class NetzkePreference < ActiveRecord::Base
     
     if session[:masq_user]
       # first, get the prefs for this user it they exist
-      res = self.find(:first, :conditions => cond.merge({:user_id => session[:masq_user].id}))
+      res = self.find(:first, :conditions => cond.merge({:user_id => session[:masq_user]}))
       # if it doesn't exist, get them for the user's role
-      res ||= self.find(:first, :conditions => cond.merge({:role_id => session[:masq_user].role.id}))
+      user = User.find(session[:masq_user])
+      res ||= self.find(:first, :conditions => cond.merge({:role_id => user.role.id}))
+      # if it doesn't exist either, get them for the World (role_id = 0)
+      res ||= self.find(:first, :conditions => cond.merge({:role_id => 0}))
     elsif session[:masq_role]
-      res = self.find(:first, :conditions => cond.merge({:role_id => session[:masq_role].id}))
-    elsif session[:user]
-      res = self.find(:first, :conditions => cond.merge({:user_id => session[:user].id}))
-      res ||= self.find(:first, :conditions => cond.merge({:role_id => session[:user].role.try(:id)}))
+      # first, get the prefs for this role
+      res = self.find(:first, :conditions => cond.merge({:role_id => session[:masq_role]}))
+      # if it doesn't exist, get them for the World (role_id = 0)
+      res ||= self.find(:first, :conditions => cond.merge({:role_id => 0}))
+    elsif session[:netzke_user_id]
+      user = User.find(session[:netzke_user_id])
+      # first, get the prefs for this user
+      res = self.find(:first, :conditions => cond.merge({:user_id => user.id}))
+      # if it doesn't exist, get them for the user's role
+      res ||= self.find(:first, :conditions => cond.merge({:role_id => user.role.id}))
+      # if it doesn't exist either, get them for the World (role_id = 0)
+      res ||= self.find(:first, :conditions => cond.merge({:role_id => 0}))
     else
       res = self.find(:first, :conditions => cond)
     end
@@ -118,20 +113,27 @@ class NetzkePreference < ActiveRecord::Base
     cond = {:name => name, :widget_name => self.widget_name}
     
     if session[:masq_user]
-      cond.merge!({:user_id => session[:masq_user].id})
+      cond.merge!({:user_id => session[:masq_user]})
+      # first, try to find the preference for masq_user
       res = self.find(:first, :conditions => cond)
+      # if it doesn't exist, create it
       res ||= self.new(cond)
     elsif session[:masq_role]
       # first, delete all the corresponding preferences for the users that have this role
-      Role.find(session[:masq_role].id).users.each do |u|
+      Role.find(session[:masq_role]).users.each do |u|
         self.delete_all(cond.merge({:user_id => u.id}))
       end
-      cond.merge!({:role_id => session[:masq_role].id})
+      cond.merge!({:role_id => session[:masq_role]})
       res = self.find(:first, :conditions => cond)
       res ||= self.new(cond)
-    elsif session[:user]
-      res = self.find(:first, :conditions => cond.merge({:user_id => session[:user].id}))
-      res ||= self.new(cond.merge({:user_id => session[:user].id}))
+    elsif session[:masq_world]
+      # first, delete all the corresponding preferences for all users and roles
+      self.delete_all(cond)
+      # then, create the new preference for the World (role_id = 0)
+      res = self.new(cond.merge(:role_id => 0))
+    elsif session[:netzke_user_id]
+      res = self.find(:first, :conditions => cond.merge({:user_id => session[:netzke_user_id]}))
+      res ||= self.new(cond.merge({:user_id => session[:netzke_user_id]}))
     else
       res = self.find(:first, :conditions => cond)
       res ||= self.new(cond)
@@ -144,11 +146,12 @@ class NetzkePreference < ActiveRecord::Base
     cond = {:widget_name => name}
     
     if session[:masq_user] || session[:masq_role]
-      cond.merge!({:user_id => session[:masq_user].try(:id), :role_id => session[:masq_role].try(:id)})
+      cond.merge!({:user_id => session[:masq_user], :role_id => session[:masq_role]})
       res = self.find(:all, :conditions => cond)
-    elsif session[:user]
-      res = self.find(:all, :conditions => cond.merge({:user_id => session[:user].id}))
-      res += self.find(:all, :conditions => cond.merge({:role_id => session[:user].role.try(:id)}))
+    elsif session[:netzke_user_id]
+      user = User.find(session[:netzke_user_id])
+      res = self.find(:all, :conditions => cond.merge({:user_id => session[:netzke_user_id]}))
+      res += self.find(:all, :conditions => cond.merge({:role_id => user.role.try(:id)}))
     else
       res = self.find(:all, :conditions => cond)
     end
@@ -156,6 +159,10 @@ class NetzkePreference < ActiveRecord::Base
     res      
   end
   
+  def self.delete_all_for_widget(name)
+    self.destroy(find_all_for_widget(name))
+  end
+  
   private
   def self.normalize_preference_name(name)
     name.to_s.gsub(".", "__").gsub("/", "__")

data/lib/netzke-core.rb

@@ -10,9 +10,6 @@ require 'netzke/routing'
 
 require 'netzke/feedback_ghost'
 
-# Vendor
-require 'vendor/facets/hash/recursive_merge'
-
 # Load models and controllers from lib/app
 %w{ models controllers }.each do |dir|
   path = File.join(File.dirname(__FILE__), 'app', dir)

data/lib/netzke/base.rb

@@ -1,26 +1,73 @@
-require 'netzke/base_extras/js_builder'
-require 'netzke/base_extras/interface'
+require 'netzke/base_js'
 
 module Netzke
+  # = Base
+  # Base class for every Netzke widget
+  #
+  # To instantiate a widget in the controller:
+  #
+  #     netzke :widget_name, configuration_hash
+  # 
+  # == Configuration
+  # * <tt>:widget_class_name</tt> - name of the widget class in the scope of the Netzke module, e.g. "FormPanel".
+  # When a widget is defined in the controller and this option is omitted, widget class is deferred from the widget's
+  # name. E.g.:
+  # 
+  #   netzke :grid_panel, :data_class_name => "User"
+  # 
+  # In this case <tt>:widget_class_name</tt> is assumed to be "GridPanel"
+  # 
+  # * <tt>:ext_config</tt> - a config hash that is used to create a javascript instance of the widget. Every
+  # configuration that comes here will be available inside the javascript instance of the widget. 
+  # * <tt>:persistent_config</tt> - if set to <tt>true</tt>, the widget will use persistent storage to store its state;
+  # for instance, Netzke::GridPanel stores there its columns state (width, visibility, order, headers, etc).
+  # A widget may or may not provide interface to its persistent settings. GridPanel and FormPanel from netzke-basepack
+  # are examples of widgets that by default do.
+  # 
+  # Examples of configuration:
+  #
+  #     netzke :books, 
+  #       :widget_class_name => "GridPanel", 
+  #       :data_class_name => "Book", # GridPanel specific option
+  #       :ext_config => {
+  #         :icon_cls => 'icon-grid', 
+  #         :title => "My books"
+  #       }
+  # 
+  #     netzke :form_panel, 
+  #       :data_class_name => "User" # FormPanel specific option
   class Base
-    
-    # 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"
-      })
-    end
-
-    include Netzke::BaseExtras::JsBuilder
-    include Netzke::BaseExtras::Interface
-    
+    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,
+            :ext_config => {}
+          }
+        })
+      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
+      end
+      
+      def enforce_config_consistency; end
 
       # "Netzke::SomeWidget" => "SomeWidget"
       def short_widget_class_name
@@ -55,30 +102,31 @@ module Netzke
         session[:_netzke_next_request_is_first_after_logout] = true
       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 Grid widget for an example
-      #
-      def interface(*interface_points)
-        interfacep = read_inheritable_attribute(:interface_points) || []
-        interface_points.each{|p| interfacep << p}
-        write_inheritable_attribute(:interface_points, interfacep)
+      # 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)
 
-        interface_points.each do |interfacep|
+        # It may be needed later for security
+        api_points.each do |apip|
           module_eval <<-END, __FILE__, __LINE__
-          def interface_#{interfacep}(*args)
-            #{interfacep}(*args).to_js
+          def api_#{apip}(*args)
+            #{apip}(*args).to_nifty_json
           end
           # FIXME: commented out because otherwise ColumnOperations stop working
-          # def #{interfacep}(*args)
-          #   flash :warning => "API point '#{interfacep}' is not implemented for widget '#{short_widget_class_name}'"
+          # def #{apip}(*args)
+          #   flash :warning => "API point '#{apip}' is not implemented for widget '#{short_widget_class_name}'"
           #   {:flash => @flash}
           # end
           END
         end
       end
 
-      def interface_points
-        read_inheritable_attribute(:interface_points)
+      def api_points
+        read_inheritable_attribute(:api_points)
       end
       
       # returns an instance of a widget defined in the config
@@ -98,78 +146,176 @@ module Netzke
       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?
-          fake_config = {}
-          class << fake_config
-            def for_widget(*params, &block)
-              yield({})
-            end
-            def widget_name=(*params)
-            end
-          end
-          fake_config
+          {}
         else
           persistent_config_manager_class
         end
       end
       
       private
-      def set_default_config(default_config)
+      def set_default_config(c)
         @@config ||= {}
-        @@config[self.name] ||= default_config
-        @@config[self.name]
+        @@config[self.name] ||= c
       end
       
     end
     extend ClassMethods
     
-    attr_accessor :config, :server_confg, :parent, :logger, :id_name, :permissions, :session
-    attr_reader :pref
+    attr_accessor :parent, :name, :id_name, :permissions, :session
+
+    api :load_aggregatee_with_cache # every widget gets this api
 
+    # 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 
+    # (the config hash is not yet available)
     def initialize(config = {}, parent = nil)
-      @session = Netzke::Base.session
+      @session       = Netzke::Base.session
+      @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}"
+      @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
 
-      # Uncomment for application-wide weak/strong default config for widgets
-      # @config  = (session[:weak_default_config] || {}).
-      #   recursive_merge(initial_config).
-      #   recursive_merge(config).
-      #   recursive_merge(session[:strong_default_config] || {})
+    def default_config
+      self.class.config[:default_config].nil? ? {} : {}.merge!(self.class.config[:default_config])
+    end
 
-      @config  = initial_config.recursive_merge(config)
-        
-      @parent  = parent
-      
-      @id_name = parent.nil? ? config[:name].to_s : "#{parent.id_name}__#{config[:name]}"
-      
-      @flash = []
-      
-      @config[:ext_config] ||= {} # configuration used to instantiate JS class
+    # Access to the config that takes into account all possible ways to configure a widget. *Read only*.
+    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)
+                    
+    end
+    
+    def flat_config(key = nil)
+      fc = config.flatten
+      key.nil? ? fc : fc.select{ |c| c[:name] == key.to_sym }.first.try(:value)
+    end
 
-      process_permissions_config
+    def strong_parent_config
+      @strong_parent_config ||= parent.nil? ? {} : parent.strong_children_config
     end
 
-    # Rails' logger
-    def logger
-      Rails.logger
+    # Config that is not overwritten by parents and sessions
+    def independent_config
+      @independent_config ||= initial_config.deep_merge(persistent_config_hash)
     end
 
-    # configuration of all children will get recursive_merge'd with strong_children_config
-    def strong_children_config= (c)
-      @strong_children_config = c
+    def flat_independent_config(key = nil)
+      fc = independent_config.flatten
+      key.nil? ? fc : fc.select{ |c| c[:name] == key.to_sym }.first.try(:value)
     end
     
-    def strong_children_config
-      @strong_children_config ||= {}
+    def flat_default_config(key = nil)
+      fc = default_config.flatten
+      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
+      key.nil? ? fc : fc.select{ |c| c[:name] == key.to_sym }.first.try(:value)
+    end
+
+    def build_persistent_config_hash
+      return {} if !initial_config[:persistent_config]
+      
+      prefs = NetzkePreference.find_all_for_widget(id_name)
+      res = {}
+      prefs.each do |p|
+        hsh_levels = p.name.split("__").map(&:to_sym)
+        tmp_res = {} # it decends into itself, building itself
+        anchor = {} # it will keep the tail of tmp_res
+        hsh_levels.each do |level_prefix|
+          tmp_res[level_prefix] ||= level_prefix == hsh_levels.last ? p.normalized_value : {}
+          anchor = tmp_res[level_prefix] if level_prefix == hsh_levels.first
+          tmp_res = tmp_res[level_prefix]
+        end
+        # Now 'anchor' is a hash that represents the path to the single value, 
+        # for example: {:ext_config => {:title => 100}} (which corresponds to ext_config__title)
+        # 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
+    end
+
+    def ext_config
+      config[:ext_config] || {}
     end
     
-    # configuration of all children will get reverse_recursive_merge'd with weak_children_config
-    def weak_children_config= (c)
-      @weak_children_config = c
+    # Like normal config, but stored in session
+    def weak_session_config
+      widget_session[:weak_session_config] ||= {}
+    end
+
+    def strong_session_config
+      widget_session[:strong_session_config] ||= {}
     end
+
+    # configuration of all children will get deep_merge'd with strong_children_config
+    # def strong_children_config= (c)
+    #   @strong_children_config = c
+    # end
+
+    # This config will be picked up by all the descendants
+    def strong_children_config
+      @strong_children_config ||= parent.nil? ? {} : parent.strong_children_config
+    end
+    
+    # configuration of all children will get reverse_deep_merge'd with weak_children_config
+    # def weak_children_config= (c)
+    #   @weak_children_config = c
+    # end
     
     def weak_children_config
       @weak_children_config ||= {}
     end
     
+    def widget_session
+      session[id_name] ||= {}
+    end
+
+    # Rails' logger
+    def logger
+      Rails.logger
+    end
+
     def dependency_classes
       res = []
       non_late_aggregatees.keys.each do |aggr|
@@ -190,21 +336,16 @@ module Netzke
         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
     
-    def initial_config
-      {}
-    end
-
     # 'Netzke::Grid' => 'Grid'
     def short_widget_class_name
       self.class.short_widget_class_name
     end
     
-    interface :get_widget # every widget gets this
-
     ## Dependencies
     def dependencies
       @dependencies ||= begin
@@ -235,6 +376,13 @@ module Netzke
       aggregatees.merge!(aggr)
     end
     
+    def remove_aggregatee(aggr)
+      if config[:persistent_config]
+        persistent_config_manager_class.delete_all_for_widget("#{id_name}__#{aggr}")
+      end
+      aggregatees[aggr] = nil
+    end
+    
     # The difference between aggregatees and late aggregatees is the following: the former gets instantiated together with its aggregator and is normally *instantly* visible as a part of it (for example, the widget in the initially expanded panel in an Accordion). A late aggregatee doesn't get instantiated along with its aggregator. Until it gets requested from the server, it doesn't take any part in its aggregator's life. An example of late aggregatee could be a widget that is loaded dynamically into a previously collapsed panel of an Accordion, or a preferences window (late aggregatee) for a widget (aggregator) that only gets shown when user wants to edit widget's preferences.
     def initial_late_aggregatees
       {}
@@ -245,22 +393,24 @@ module Netzke
     end
 
     # recursively instantiates an aggregatee based on its "path": e.g. if we have an aggregatee :aggr1 which in its turn has an aggregatee :aggr10, the path to the latter would be "aggr1__aggr10"
-    def aggregatee_instance(name)
+    def aggregatee_instance(name, strong_config = {})
       aggregator = self
       name.to_s.split('__').each do |aggr|
         aggr = aggr.to_sym
-        short_class_name = aggregator.aggregatees[aggr][:widget_class_name]
-        raise ArgumentError, "No widget_class_name specified for aggregatee #{aggr} of #{aggregator.config[:name]}" if short_class_name.nil?
+        aggregatee_config = aggregator.aggregatees[aggr]
+        raise ArgumentError, "No aggregatee '#{aggr}' defined for widget '#{aggregator.id_name}'" 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?
         widget_class = "Netzke::#{short_class_name}".constantize
 
         conf = weak_children_config.
-          recursive_merge(aggregator.aggregatees[aggr]).
-          recursive_merge(strong_children_config).
+          deep_merge(aggregatee_config).
+          deep_merge(strong_config). # we may want to reconfigure the aggregatee at the moment of instantiation
           merge(:name => aggr)
 
         aggregator = widget_class.new(conf, aggregator) # params: config, parent
-        aggregator.weak_children_config = weak_children_config
-        aggregator.strong_children_config = strong_children_config
+        # aggregator.weak_children_config = weak_children_config
+        # aggregator.strong_children_config = strong_children_config
       end
       aggregator
     end
@@ -280,35 +430,90 @@ module Netzke
     end
 
     # permissions
-    def available_permissions
-      []
-    end
+    # def available_permissions
+    #   []
+    # end
+
+    # def process_permissions_config
+    #   if !available_permissions.empty?
+    #     # First, process permissions from the config
+    #     @permissions = available_permissions.inject({}){|h,p| h.merge(p.to_sym => true)} # by default anything is allowed
+    # 
+    #     config[:prohibit] = available_permissions if config[:prohibit] == :all # short-cut for all permissions
+    #     config[:prohibit] = [config[:prohibit]] if config[:prohibit].is_a?(Symbol) # so that config[:prohibit] => :write works
+    #     config[:prohibit] && config[:prohibit].each{|p| @permissions.merge!(p.to_sym => false)} # prohibit
+    # 
+    #     config[:allow] = [config[:allow]] if config[:allow].is_a?(Symbol) # so that config[:allow] => :write works
+    #     config[:allow] && config[:allow].each{|p| @permissions.merge!(p.to_sym => true)} # allow
+    #     
+    #     # ... and then merge it with NetzkePreferences
+    #     available_permissions.each do |p|
+    #       # if nothing is stored in persistent_config, store the permission from the config; otherwise leave what's there
+    #       persistent_config["permissions/#{p}"].nil? && persistent_config["permissions/#{p}"] = @permissions[p.to_sym]
+    # 
+    #       # what's stored in persistent_config has higher priority, so, if there's something there, use that
+    #       persistent_permisson = persistent_config["permissions/#{p}"]
+    #       @permissions[p.to_sym] = persistent_permisson unless persistent_permisson.nil?
+    #     end
+    #   end
+    # end
 
-    def process_permissions_config
-      if !available_permissions.empty?
-        # First, process permissions from the config
-        @permissions = available_permissions.inject({}){|h,p| h.merge(p.to_sym => true)} # by default anything is allowed
+    # called when the method_missing tries to processes a non-existing aggregatee
+    def aggregatee_missing(aggr)
+      flash :error => "Unknown aggregatee #{aggr} for widget #{name}"
+      {:feedback => @flash}.to_nifty_json
+    end
 
-        config[:prohibit] = available_permissions if config[:prohibit] == :all # short-cut for all permissions
-        config[:prohibit] = [config[:prohibit]] if config[:prohibit].is_a?(Symbol) # so that config[:prohibit] => :write works
-        config[:prohibit] && config[:prohibit].each{|p| @permissions.merge!(p.to_sym => false)} # prohibit
+    def tools
+      persistent_config[:tools] ||= config[:tools] || []
+    end
 
-        config[:allow] = [config[:allow]] if config[:allow].is_a?(Symbol) # so that config[:allow] => :write works
-        config[:allow] && config[:allow].each{|p| @permissions.merge!(p.to_sym => true)} # allow
-        
-        # ... and then merge it with NetzkePreferences
-        available_permissions.each do |p|
-          # if nothing is stored in persistent_config, store the permission from the config; otherwise leave what's there
-          persistent_config["permissions/#{p}"].nil? && persistent_config["permissions/#{p}"] = @permissions[p.to_sym]
+    def menu
+      persistent_config[:menu] ||= config[:menu] == false ? nil : config[:menu]
+    end
+    
+    # some convenience for instances
+    def persistent_config_manager_class
+      self.class.persistent_config_manager_class
+    end
 
-          # what's stored in persistent_config has higher priority, so, if there's something there, use that
-          persistent_permisson = persistent_config["permissions/#{p}"]
-          @permissions[p.to_sym] = persistent_permisson unless persistent_permisson.nil?
-        end
-      end
+    # override this method to do stuff at the moment of loading by some parent
+    def before_load
+      widget_session.clear
     end
 
-    # method dispatcher - sends method to the proper aggregatee
+    # API
+    def load_aggregatee_with_cache(params)
+      cache = ActiveSupport::JSON.decode(params.delete(:cache))
+      relative_widget_id = params.delete(:id).underscore
+      passed_config = params[:config] && ActiveSupport::JSON.decode(params[:config]) || {}
+      passed_config = passed_config.symbolize_keys
+      widget = aggregatee_instance(relative_widget_id, passed_config)
+      
+      # 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
+        }
+      }]
+    end
+
+    # Method dispatcher - instantiates an aggregatee and calls the method on it
+    # E.g.: 
+    #   users__center__get_data
+    #     instantiates aggregatee "users", and calls "center__get_data" on it
+    #   books__move_column
+    #     instantiates aggregatee "books", and calls "api_move_column" on it
     def method_missing(method_name, params = {})
       widget, *action = method_name.to_s.split('__')
       widget = widget.to_sym
@@ -316,9 +521,9 @@ module Netzke
       
       if action
         if aggregatees[widget]
-          # only actions starting with "interface_" are accessible
-          interface_action = action.to_s.index('__') ? action : "interface_#{action}"
-          aggregatee_instance(widget).send(interface_action, params)
+          # only actions starting with "api_" are accessible
+          api_action = action.to_s.index('__') ? action : "api_#{action}"
+          aggregatee_instance(widget).send(api_action, params)
         else
           aggregatee_missing(widget)
         end
@@ -326,33 +531,6 @@ module Netzke
         super
       end
     end
-
-    # called when the method_missing tries to processes a non-existing aggregatee
-    def aggregatee_missing(aggr)
-      flash :error => "Unknown aggregatee #{aggr} for widget #{config[:name]}"
-      {:success => false, :flash => @flash}.to_json
-    end
-
-    def tools
-      persistent_config[:tools] ||= config[:tools] == false ? nil : config[:tools]
-    end
-
-    def bbar
-      persistent_config[:bottom_bar] ||= config[:bbar] == false ? nil : config[:bbar]
-    end
-
-    def tbar
-      persistent_config[:top_bar] ||= config[:tbar] == false ? nil : config[:tbar]
-    end
-
-    def menu
-      persistent_config[:menu] ||= config[:menu] == false ? nil : config[:menu]
-    end
     
-    # some convenience for instances
-    def persistent_config_manager_class
-      self.class.persistent_config_manager_class
-    end
-
   end
 end