netzke-core 0.1.1.1

data/lib/netzke-core.rb

@@ -0,0 +1,28 @@
+# NetzkeCore
+require 'netzke/js_class_builder'
+require 'netzke/base'
+require 'netzke/core_ext'
+require 'netzke/controller_extensions'
+
+# Vendor
+require 'vendor/facets/hash/recursive_merge'
+
+
+%w{ models controllers }.each do |dir|
+  path = File.join(File.dirname(__FILE__), 'app', dir)
+  $LOAD_PATH << path
+  ActiveSupport::Dependencies.load_paths << path
+  ActiveSupport::Dependencies.load_once_paths.delete(path)
+end
+
+# raise 'test'
+
+ActionController::Base.class_eval do
+  include Netzke::ControllerExtensions
+end
+
+# Make this plugin reloadable for easier development
+ActiveSupport::Dependencies.load_once_paths.delete(File.join(File.dirname(__FILE__)))
+
+# Include the javascript
+Netzke::Base.config[:javascripts] << "#{File.dirname(__FILE__)}/../javascripts/core.js"

data/lib/netzke/base.rb

@@ -0,0 +1,210 @@
+require 'json'
+module Netzke
+  class Base
+    # Global Netzke configuration
+    def self.config
+      @@config ||= {
+        :javascripts => ["#{File.dirname(__FILE__)}/../../javascripts/core.js"] # locations of javascript files (which automatically will be collected into one file and sent as netzke.js)
+      }
+    end
+    
+    def self.js_class_code(cached_dependencies = [])
+      self.new(:js_class => true).js_missing_code(cached_dependencies)
+    end
+    
+    # Helper class to read/write from/to widget's persistent preferences. TODO: rework it.
+    class Config
+      def initialize(widget_name)
+        @widget_name = widget_name
+      end
+      def []=(k,v)
+        NetzkePreference.custom_field = @widget_name
+        NetzkePreference[k] = v
+      end
+      def [](k)
+        NetzkePreference.custom_field = @widget_name
+        NetzkePreference[k]
+      end
+    end
+  
+    # client-side code (generates JS-classes of the widgets)
+    include Netzke::JsClassBuilder
+
+    attr_accessor :config, :server_confg, :parent, :logger, :id_name, :permissions
+    attr_reader :pref
+
+    def initialize(config = {}, parent = nil)
+      @logger = Logger.new("debug.log")
+      @config = initial_config.recursive_merge(config)
+      @parent = parent
+      @id_name = parent.nil? ? config[:name].to_s : "#{parent.id_name}__#{config[:name]}"
+      
+      @flash = []
+      @pref = Config.new(@id_name)
+      
+      @config[:ext_config] ||= {} # configuration used to instantiate JS class
+      
+      process_permissions_config
+    end
+    
+    def initial_config
+      {}
+    end
+
+    # 'Netzke::Grid' => 'Grid'
+    def short_widget_class_name
+      self.class.short_widget_class_name
+    end
+    
+    def self.short_widget_class_name
+      name.split("::").last
+    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 self.interface(*interface_points)
+      interfacep = read_inheritable_attribute(:interface_points) || []
+      interface_points.each{|p| interfacep << p}
+      write_inheritable_attribute(:interface_points, interfacep)
+      
+      interface_points.each do |interfacep|
+        module_eval <<-END, __FILE__, __LINE__
+        def interface_#{interfacep}(*args)
+          #{interfacep}(*args).to_js
+        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}'"
+        #   {:flash => @flash}
+        # end
+        END
+      end
+    end
+    
+    def self.interface_points
+      read_inheritable_attribute(:interface_points)
+    end
+    
+    def interface_points
+      self.class.interface_points
+    end
+
+    interface :get_widget # default
+
+    ## Dependencies
+    def dependencies
+      @dependencies ||= begin
+        non_late_aggregatees_widget_classes = aggregatees.values.map{|v| v[:widget_class_name]}
+        (initial_dependencies + non_late_aggregatees_widget_classes).uniq
+      end
+    end
+    
+    # override this method if you need some extra dependencies, which are not the aggregatees
+    def initial_dependencies
+      []
+    end
+    
+    ### Aggregation
+    def initial_aggregatees
+      {}
+    end
+    
+    def aggregatees
+      @aggregatees ||= initial_aggregatees.merge(initial_late_aggregatees.each_pair{|k,v| v.merge!(:late_aggregation => true)})
+    end
+    
+    def non_late_aggregatees
+      aggregatees.reject{|k,v| v[:late_aggregation]}
+    end
+    
+    def add_aggregatee(aggr)
+      aggregatees.merge!(aggr)
+    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. While a late aggregatee doesn't get instantiated along with its aggregator. Until it gets requested, it doesn't take any part in its aggregator's lifecycle. An example of late aggregatee could be a widget that is loaded by an application widget on user's request, or a preferences window that only gets instantiated when user wants to edit widget's preferences. An example of a normal aggregatee is any widget (like a grid) within a BorderLayout-based widget (i.e. aggregator) - it should get instantiated and shown along with its aggregator.
+    def initial_late_aggregatees
+      {}
+    end
+    
+    def add_late_aggregatee(aggr)
+      aggregatees.merge!(aggr.merge(:late_aggregation => true))
+    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)
+      aggregator = self
+      name.to_s.split('__').each do |aggr|
+        aggr = aggr.to_sym
+        # TODO: should we put all the classes under Netzke::-scope?
+        # widget_class = full_widget_class_name(aggregator.aggregatees[aggr][:widget_class_name]).constantize
+        widget_class = "Netzke::#{aggregator.aggregatees[aggr][:widget_class_name]}".constantize
+        aggregator = widget_class.new(aggregator.aggregatees[aggr].merge(:name => aggr), aggregator)
+      end
+      aggregator
+    end
+    
+    
+    def full_widget_class_name(short_name)
+      "Netzke::#{short_name}"
+    end
+
+    def flash(flash_hash)
+      level = flash_hash.keys.first
+      raise "Unknown message level for flash" unless %(notice warning error).include?(level.to_s)
+      @flash << {:level => level, :msg => flash_hash[level]}
+    end
+
+    def widget_action(action_name)
+      "#{@id_name}__#{action_name}"
+    end
+
+    # permissions
+    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 (if not instantiated to only generate JS-class code)
+        !config[:js_class] && available_permissions.each do |p|
+          @permissions[p.to_sym] = @pref["permissions.#{p}"] if !@pref["permissions.#{p}"].nil?
+        end
+      end
+    end
+
+    ## method dispatcher - sends method to the proper aggregatee
+    def method_missing(method_name, params = {})
+      widget, *action = method_name.to_s.split('__')
+      widget = widget.to_sym
+      action = !action.empty? && action.join("__").to_sym
+      
+      if action && 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)
+      else
+        super
+      end
+    end
+
+    #### API section
+    def get_widget(params = {})
+      # if browser does not have our component class cached (and all dependencies), send it to him
+      components_cache = (JSON.parse(params[:components_cache]) if params[:components_cache]) || []
+      
+      {:config => js_config, :class_definition => js_missing_code(components_cache)}
+    end
+   
+  end
+end

data/lib/netzke/controller_extensions.rb

@@ -0,0 +1,95 @@
+module Netzke
+  module ControllerExtensions
+    def self.included(base)
+      base.extend ControllerClassMethods
+    end
+    
+    def method_missing(method_name)
+      if self.class.widget_config_storage == {}
+        super
+      else
+        widget, *action = method_name.to_s.split('__')
+        widget = widget.to_sym
+        action = !action.empty? && action.join("__").to_sym
+      
+        # only widget's actions starting with "interface_" are accessible from outside (security)
+        if action
+          interface_action = action.to_s.index('__') ? action : "interface_#{action}"
+
+          # widget module
+          widget_class = "Netzke::#{self.class.widget_config_storage[widget][:widget_class_name]}".constantize
+
+          # instantiate the server part of the widget
+          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(interface_action, params)
+        end
+      end
+    end
+    
+    module ControllerClassMethods
+
+      # widget_config_storage for all widgets
+      def widget_config_storage
+        @@widget_config_storage ||= {}
+      end
+    
+      #
+      # Use this method to declare a widget in the controller
+      #
+      def netzke_widget(name, config={})
+        # which module is the widget?
+        config[:widget_class_name] ||= name.to_s.classify
+        config[:name] ||= name
+      
+        # register the widget config in the storage
+        widget_config_storage[name] = config
+
+        # provide widget helpers
+        ActionView::Base.module_eval <<-END_EVAL, __FILE__, __LINE__
+          def #{name}_widget_instance(config = {})
+            # get the global config from the controller's singleton class
+            global_config = controller.class.widget_config_storage[:#{name}]
+
+            # when instantiating a client side instance, the configuration may be overwritten 
+            # (but the server side will know nothing about it!)
+            local_config = global_config.merge(config)
+
+            # instantiate it
+            widget_instance = Netzke::#{config[:widget_class_name]}.new(local_config)
+          
+            # return javascript code for instantiating on the javascript level
+            widget_instance.js_widget_instance
+          end
+          
+          def #{name}_class_definition
+            result = ""
+            config = controller.class.widget_config_storage[:#{name}]
+            @@generated_widget_classes ||= []
+            # do not duplicate javascript code on the same page
+            unless @@generated_widget_classes.include?("#{config[:widget_class_name]}")
+              @@generated_widget_classes << "#{config[:widget_class_name]}"
+              result = Netzke::#{config[:widget_class_name]}.js_class_code
+            end
+            result
+          end
+        END_EVAL
+      
+        # add controller action which will render a simple HTML page containing the widget
+        define_method("#{name}_test") do
+          @widget_name = name
+          render :inline => %Q(
+          <script type="text/javascript" charset="utf-8">
+          <%= #{name}_class_definition %>
+          Ext.onReady(function(){
+          	<%= #{name}_widget_instance %>
+          	#{name.to_js}.render("#{name.to_s.split('_').join('-')}");
+          })
+        	</script>
+          <div id="#{name.to_s.split('_').join('-')}"></div>
+          ), :layout => "netzke"
+        end
+      end
+    end
+  end
+  
+end

data/lib/netzke/core_ext.rb

@@ -0,0 +1,77 @@
+class Hash
+
+  # Recursively convert the keys. Example:
+  # irb> {:bla_bla => 1, "wow_now" => {:look_ma => true}}.convert_keys{|k| k.camelize} 
+  # irb> => {:BlaBla => 1, "WowNow" => {:LookMa => true}}
+  def convert_keys(&block)
+    block_given? ? self.inject({}) do |h,(k,v)|
+      h[k.is_a?(Symbol) ? yield(k.to_s).to_sym : yield(k.to_s)] = v.respond_to?('convert_keys') ? v.convert_keys(&block) : v
+      h
+    end : self
+  end
+  
+  # First camelizes the keys, then convert the whole hash to JSON
+  def to_js
+    # self.delete_if{ |k,v| v.nil? } # we don't need to explicitely pass null values to javascript
+    self.recursive_delete_if_nil.convert_keys{|k| k.camelize(:lower)}.to_json
+  end
+
+  # Converts values to strings
+  def stringify_values!
+    self.each_pair{|k,v| self[k] = v.to_s if v.is_a?(Symbol)}
+  end
+  
+  def recursive_delete_if_nil
+    self.inject({}) do |h,(k,v)|
+      if !v.nil?
+        h[k] = v.respond_to?('recursive_delete_if_nil') ? v.recursive_delete_if_nil : v
+      end
+      h
+    end
+  end
+  
+end
+
+class Array
+  # Camelizes the keys of hashes and converts them to JSON
+  def to_js
+    self.recursive_delete_if_nil.map{|el| el.is_a?(Hash) ? el.convert_keys{|k| k.camelize(:lower)} : el}.to_json
+  end
+  
+  # Applies convert_keys to each element which responds to convert_keys
+  def convert_keys(&block)
+    block_given? ? self.map do |i|
+      i.respond_to?('convert_keys') ? i.convert_keys(&block) : i
+    end : self
+  end
+  
+  def recursive_delete_if_nil
+    self.map{|el| el.respond_to?('recursive_delete_if_nil') ? el.recursive_delete_if_nil : el}
+  end
+end
+
+class String
+  # Converts self to "literal JSON"-string - one that doesn't get quotes appended when being sent "to_json" method
+  def l
+    def self.to_json
+      self
+    end
+    self
+  end
+  
+  def to_js
+    self.camelize(:lower)
+  end
+  
+  # removes JS-comments (both single-line and multiple-line) from the string
+  def strip_js_comments
+    regexp = /\/\/.*$|(?m:\/\*.*?\*\/)/
+    self.gsub(regexp, '')
+  end
+end
+
+class Symbol
+  def to_js
+    self.to_s.camelize(:lower).to_sym
+  end
+end

data/lib/netzke/js_class_builder.rb

@@ -0,0 +1,114 @@
+module Netzke
+  # 
+  # Module which provides JS-class generation functionality for the widgets ("client-side"). This code is executed only once per widget class, and the results are cached at the server (unless widget specifies config[:no_caching] => true).
+  # Included into Netzke::Base class
+  # Most of the methods below are meant to be overwritten by a concrete widget class.
+  # 
+  module JsClassBuilder
+    # the JS (Ext) class that we inherit from
+    def js_base_class; "Ext.Panel"; end
+
+    # widget's actions that are loaded at the moment of instantiating a widget
+    def actions; null; end
+
+    # widget's tools that are loaded at the moment of instantiating a widget see (js_config method)
+    def tools; []; end
+    
+    def tbar; null; end
+
+    def bbar; null; end
+
+    # functions and properties that will be used to extend the functionality of (Ext) JS-class specified in js_base_class
+    def js_extend_properties; {}; end
+    
+    # code executed before and after the constructor
+    def js_before_constructor; ""; end
+    def js_after_constructor; ""; end
+
+    # widget's listeners
+    def js_listeners; {}; end
+    
+    # widget's menus
+    def js_menus; []; end
+    
+    # items
+    def js_items; null; end
+
+    # default config that is passed into the constructor
+    def js_default_config
+      {
+        :title => short_widget_class_name,
+        :listeners => js_listeners,
+        :tools => "config.tools".l,
+        :actions => "config.actions".l,
+        :tbar => "config.tbar".l,
+        :bbar => "config.bbar".l,
+        :items => js_items,
+        :height => 400,
+        :width => 800,
+        :border => false
+      }
+    end
+
+    # declaration of widget's class (stored directly in the cache storage at the client side to be reused at the moment of widget instantiation)
+    def js_class
+      <<-JS
+      Ext.componentCache['#{short_widget_class_name}'] = Ext.extend(#{js_base_class}, Ext.chainApply([Ext.widgetMixIn, {
+        constructor: function(config){
+          this.widgetInit(config);
+          #{js_before_constructor}
+          Ext.componentCache['#{short_widget_class_name}'].superclass.constructor.call(this, Ext.apply(#{js_default_config.to_js}, config));
+          #{js_after_constructor}
+          this.setEvents();
+          this.addMenus(#{js_menus.to_js});
+        }
+      }, #{js_extend_properties.to_js}]))
+      JS
+    end
+
+    # generate instantiating - used when a widget is generated stand-alone (as a part of a HTML page)
+    def js_widget_instance
+      %Q(var #{config[:name].to_js} = new Ext.componentCache['#{short_widget_class_name}'](#{js_config.to_js});)
+    end
+
+    # the config that is send from the server and is used for instantiating a widget
+    def js_config
+      res = {}
+      
+      # recursively include configs of all (non-late) aggregatees, so that the widget can instantiate them, too
+      aggregatees.each_pair do |aggr_name, aggr_config|
+        next if aggr_config[:late_aggregation]
+        res["#{aggr_name}_config".to_sym] = aggregatee_instance(aggr_name.to_sym).js_config
+      end
+      
+      # interface
+      interface = interface_points.inject({}){|h,interfacep| h.merge(interfacep => widget_action(interfacep))}
+      res.merge!(:interface => interface)
+      
+      res.merge!(:widget_class_name => short_widget_class_name)
+
+      res.merge!(config[:ext_config])
+      res.merge!(:id => @id_name)
+      
+      # include tools and actions
+      res.merge!(:tools => tools)
+      res.merge!(:actions => actions)
+      res
+    end
+
+    # class definition of the widget plus that of all the dependencies, minus those that are specified as dependencies_to_exclude
+    def js_missing_code(cached_dependencies = [])
+      result = ""
+      dependencies.each do |dep_name|
+        dependency_class = "Netzke::#{dep_name}".constantize
+        result << dependency_class.js_class_code(cached_dependencies)
+      end
+      result << js_class.strip_js_comments unless cached_dependencies.include?(short_widget_class_name) && !config[:no_caching]
+      result
+    end
+   
+    # little helpers
+    def this; "this".l; end
+    def null; "null".l; end
+  end
+end