netzke-core 0.7.7 → 0.8.0

data/lib/netzke-core.rb

@@ -1,17 +1,20 @@
-$LOAD_PATH << File.dirname(__FILE__)
-
 require 'netzke/core'
 require 'netzke/base'
-require 'netzke/plugin'
 
 module Netzke
-  autoload :Core, 'netzke/core'
-  autoload :ExtComponent, 'netzke/ext_component'
+  autoload :Plugin, 'netzke/plugin'
+
+  module Core
+    autoload :ComponentConfig, 'netzke/core/component_config'
+    autoload :ActionConfig, 'netzke/core/action_config'
+    autoload :Panel, 'netzke/core/panel'
+    autoload :EndpointResponse, 'netzke/core/endpoint_response'
+  end
 end
 
 # Rails specific
 if defined? Rails
-  require 'netzke/railz'
+  require 'netzke/core/railz'
 
   ActiveSupport.on_load(:action_controller) do
     include Netzke::Railz::ControllerExtensions
@@ -20,4 +23,11 @@ if defined? Rails
   ActiveSupport.on_load(:action_view) do
     include Netzke::Railz::ActionViewExt
   end
+
+  ActiveSupport.on_load(:after_initialize) do
+    Netzke::Base.logger = Rails.logger
+  end
+else
+  require 'logger'
+  Netzke::Base.logger = Logger.new(STDOUT)
 end

data/lib/netzke/base.rb

@@ -1,77 +1,80 @@
 require 'active_support/core_ext'
-require 'netzke/core_ext'
-require 'netzke/javascript'
-require 'netzke/stylesheets'
-require 'netzke/inheritance'
-require 'netzke/services'
-require 'netzke/composition'
-require 'netzke/plugins'
-require 'netzke/configuration'
-require 'netzke/state'
-require 'netzke/embedding'
-require 'netzke/actions'
-require 'netzke/session'
-require 'netzke/config_to_dsl_delegator'
+require 'netzke/core/ruby_ext'
+require 'netzke/core/javascript'
+require 'netzke/core/stylesheets'
+require 'netzke/core/services'
+require 'netzke/core/composition'
+require 'netzke/core/plugins'
+require 'netzke/core/configuration'
+require 'netzke/core/state'
+require 'netzke/core/embedding'
+require 'netzke/core/actions'
+require 'netzke/core/session'
 
 module Netzke
-  # The base for every Netzke component
+  # The base class for every Netzke component. Its main responsibilities include:
+  # * JavaScript class generation and inheritance (using Ext JS class system) which reflects the Ruby class inheritance (see {Netzke::Core::Javascript})
+  # * Nesting and dynamic loading of child components (see {Netzke::Core::Composition})
+  # * Ruby-side action declaration (see {Netzke::Actions})
+  # * I18n
+  # * Client-server communication (see {Netzke::Core::Services})
+  # * Session-based persistence (see {Netzke::Core::State})
   #
-  # == Class-level configuration
-  # You can configure component classes in Rails Application, e.g.:
+  # == Referring to JavaScript configuration methods from Ruby
   #
-  #     config.netzke.basepack.grid_panel.column_filters_available = false
+  # Netzke allows use Ruby symbols for referring to pre-defined pieces of configuration. Let's say for example, that a toolbar needs to nest a control more complex than a button (say, a date field), and a component should still make it possible to make it's presence and position in the toolbar configurable. We can implement it like this:
   #
-  # Optionally, when used outside of Rails, you can also set the values directly on Netzke::Core.config (the Engine does it for you):
+  #     action :do_something
   #
-  #     Netzke::Core.config.netzke.basepack.grid_panel.column_filters_available = false
+  #     def configure(c)
+  #       super
+  #       c.tbar = [:do_something, :date_selector]
+  #     end
   #
-  # If both default and overriding values are hashes, the default value gets deep-merged with the overriding value.
+  # While :do_something here is referring to a usual Netzke action, :date_selector is not declared in actions. If our JavaScript mixin file contains a method called `dateSelectorConfig`, it will be executed at the moment of configuring `tbar` at client side, and it's result, a config object, will substitute `date_selector`:
   #
-  # Netzke::Base provides the following class-level configuration options:
-  # * default_instance_config - a hash that will be used as default configuration for ALL of this component's instances.
+  #     {
+  #       dateSelectorConfig: function(config){
+  #         return {
+  #           xtype: 'datefield'
+  #         }
+  #       }
+  #     }
+  #
+  # This doesn't necessarily have to be used in toolbars, but also in other places in config (i.e. layouts).
   class Base
-    include Session
-    include State
-    include Configuration
-    include Javascript
-    include Inheritance
-    include Services
-    include Composition
-    include Plugins
-    include Stylesheets
-    include Embedding
-    include Actions
-    include ConfigToDslDelegator
-
-    delegates_to_dsl :title, :items
-
-    class_config_option :default_instance_config, {}
+    include Core::Session
+    include Core::State
+    include Core::Configuration
+    include Core::Javascript
+    include Core::Services
+    include Core::Composition
+    include Core::Plugins
+    include Core::Stylesheets
+    include Core::Embedding
+    include Core::Actions
+
+    class_attribute :default_instance_config
+    self.default_instance_config = {}
+
+    # set during initializations
+    mattr_accessor :session
+    mattr_accessor :controller
+    mattr_accessor :logger
 
     # Parent component
     attr_reader :parent
 
-    # Name that the parent can reference us by. The last part of +global_id+
+    # Name that the parent can reference us by. The last part of +js_id+
     attr_reader :name
 
     # Global id in the components tree, following the double-underscore notation, e.g. +books__config_panel__form+
-    attr_reader :global_id
+    attr_reader :js_id
 
     class << self
-      # Component's short class name, e.g.:
-      # "Netzke::Module::SomeComponent" => "Module::SomeComponent"
-      def short_component_class_name
-        self.name.sub(/^Netzke::/, "")
-      end
-
-      # Component's class, given its name.
-      def constantize_class_name(class_name)
-        class_name.constantize # used to be more complex than this, but appeared to be difficult to debug
-      end
-
       # Instance of component by config
       def instance_by_config(config)
-        klass = config[:klass] || constantize_class_name(config[:class_name])
-        raise NameError, "Netzke: Unknown component #{config[:class_name]}" if klass.nil?
+        klass = config[:klass] || config[:class_name].constantize
         klass.new(config)
       end
 
@@ -80,6 +83,23 @@ module Netzke
         name.split("::").map{|c| c.underscore}.join(".")
       end
 
+      # Do class-level config of a component, e.g.:
+      #
+      #   Netzke::Basepack::GridPanel.setup do |c|
+      #     c.rows_reordering_available = false
+      #   end
+      def self.setup
+        yield self
+      end
+
+      # Ancestor classes in the Netzke class hierarchy up to (and excluding) +Netzke::Base+, including self; in comparison to Ruby's own Class.ancestors, the order is reversed.
+      def netzke_ancestors
+        if self == Netzke::Base
+          []
+        else
+          superclass.netzke_ancestors + [self]
+        end
+      end
     end
 
     # Instantiates a component instance. A parent can optionally be provided.
@@ -87,70 +107,27 @@ module Netzke
       @passed_config = conf # configuration passed at the moment of instantiation
       @passed_config.deep_freeze
       @parent        = parent
-      @name          = conf[:name].nil? ? short_component_class_name.underscore : conf[:name].to_s
-      @global_id     = parent.nil? ? @name : "#{parent.global_id}__#{@name}"
+      @name          = conf[:name] || self.class.name.underscore
+      @js_id         = parent.nil? ? @name : "#{parent.js_id}__#{@name}"
       @flash         = []
 
-      # initialize @components and @items
-      normalize_components_in_items
-      # auto_collect_actions_from_config_and_js_properties
-
-      self.class.increase_total_instances
-    end
-
-    # Proxy to the equally named class method
-    def constantize_class_name(class_name)
-      self.class.constantize_class_name(class_name)
-    end
-
-    # Proxy to the equally named class method
-    def short_component_class_name
-      self.class.short_component_class_name
-    end
-
-    # Override this method to do stuff at the moment of first-time loading
-    def before_load
-    end
-
-    def clean_up
-      component_session.clear
-      components.keys.each { |k| component_instance(k).clean_up }
+      # Build complete component configuration
+      configure(config)
     end
 
     def i18n_id
       self.class.i18n_id
     end
 
-    # Used for performance measurments
-    def self.total_instances
-      @@instances || 0
-    end
-
-    def self.reset_total_instances
-      @@instances = 0
-    end
+  private
 
-    def self.increase_total_instances
-      @@instances ||= 0
-      @@instances += 1
+    # TODO: needs rework
+    # TODO: rename to smth more appropriate
+    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
 
-    private
-
-      def logger #:nodoc:
-        if defined?(::Rails)
-          ::Rails.logger
-        else
-          require 'logger'
-          Logger.new(STDOUT)
-        end
-      end
-
-      def flash(flash_hash) #:nodoc:
-        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
-
   end
 end

data/lib/netzke/core.rb

@@ -1,9 +1,10 @@
 require 'active_support/core_ext'
 require 'netzke/core/options_hash'
 require 'netzke/core/version'
-require 'netzke/core/session'
-require 'netzke/core/masquerading'
 require 'netzke/core/dynamic_assets'
+require 'netzke/core/client_class'
+require 'netzke/core/css_config'
+require 'netzke/core/config_to_dsl_delegator'
 
 module Netzke
   # This module implements high-level configuration for Netzke Core.
@@ -11,36 +12,19 @@ module Netzke
   # You can configure Netzke::Core like this:
   #
   #     Netzke::Core.setup do |config|
-  #       config.ext_location = "/home/netzke/ext-3.3.0"
+  #       config.ext_location = "/home/netzke/ext-4.1.1"
   #       config.icons_uri = "/images/famfamfam/icons"
   #       # ...
   #     end
   #
   # The following configuration options are available:
-  # * ext_location - absolute path to your Ext code root
+  # * ext_path - absolute path to your Ext code root
   # * icons_uri - relative URI to the icons
   module Core
-    extend Session
-    extend Masquerading
-
-    # Use Ext 3 compatibility layer
-    mattr_accessor :ext3_compat_uri
-
-    # Configuration specified at the initialization times (set in the Engine in case of Rails)
-    mattr_accessor :config
-    @@config = {}
-
-    # :ext or :touch
+    # :ext (or :touch - when and if ever implemented)
     mattr_accessor :platform
     @@platform = :ext
 
-    # set in Netzke::ControllerExtensions
-    mattr_accessor :controller
-
-    # set in Netzke::ControllerExtensions
-    mattr_accessor :session
-    @@session = {}
-
     mattr_accessor :ext_javascripts
     @@ext_javascripts = []
 
@@ -59,36 +43,18 @@ module Netzke
 
     mattr_accessor :ext_path
 
-    mattr_accessor :current_user_method
-    @@current_user_method = :current_user
-
-    mattr_accessor :persistence_manager
-    @@persistence_manager = "NetzkeComponentState"
-
     # The amount of retries that the direct remoting provider will attempt in case of failure
     mattr_accessor :js_direct_max_retries
     @@js_direct_max_retries = 0
 
     mattr_accessor :with_icons
 
-    mattr_accessor :persistence_manager_class
-
-    # Sencha Touch specific
-    mattr_accessor :touch_javascripts
-    @@touch_javascripts = []
-
-    mattr_accessor :touch_stylesheets
-    @@touch_stylesheets = []
-
-    mattr_accessor :touch_uri
-    @@touch_uri = "/sencha-touch"
-
     def self.setup
       yield self
     end
 
     def self.reset_components_in_session
-      Netzke::Core.session[:netzke_components].try(:clear)
+      Netzke::Base.session[:netzke_components].try(:clear)
     end
   end
 end

data/lib/netzke/core/action_config.rb

@@ -0,0 +1,37 @@
+module Netzke::Core
+  # This class is responsible for configuring an action. It is passed as a block parameter to the +action+ DSL method:
+  #
+  #   class MyComponent < Netzke::Base
+  #     action :do_something do |c|
+  #       c.text = "Do it!"
+  #     end
+  #   end
+  class ActionConfig < ActiveSupport::OrderedOptions
+    def initialize(name, component)
+      @component = component
+      @name = name.to_s
+      @text = @tooltip = @icon = ""
+
+      build_localized_attributes
+
+      self.text = @text.presence || @name.humanize
+      self.tooltip = @tooltip.presence || @name.humanize
+      self.icon = @icon.to_sym if @icon.present?
+    end
+
+    def icon=(path)
+      self[:icon] = path.is_a?(Symbol) ? Netzke::Base.uri_to_icon(path) : path
+    end
+
+  private
+
+    def build_localized_attributes
+      @component.class.netzke_ancestors.each do |c|
+        i18n_id = c.i18n_id
+        @text = I18n.t("#{i18n_id}.actions.#{@name}.text", default: "").presence || @text
+        @tooltip = I18n.t("#{i18n_id}.actions.#{@name}.tooltip", default: "").presence || @tooltip
+        @icon = I18n.t("#{i18n_id}.actions.#{@name}.icon", default: "").presence || @icon
+      end
+    end
+  end
+end

data/lib/netzke/core/actions.rb

@@ -0,0 +1,123 @@
+module Netzke::Core
+  # Netzke components allow specifying Ext actions (see http://docs.sencha.com/ext-js/4-1/#!/api/Ext.Action) in Ruby code.
+  #
+  # == Defining actions
+  #
+  # An action is defined with the +action+ class method that accepts a block:
+  #
+  #     action :destroy do |c|
+  #       c.text = "Destroy!"
+  #       c.tooltip = "Destroying it all"
+  #       c.icon = :delete
+  #       c.handler = :destroy_something # destroySomething will be called on JavaScript side
+  #     end
+  #
+  # All config settings for an action are optional. When omitted, the locale files will be consulted first (see "I18n of actions"), falling back to the defaults.
+  #
+  # [+icon+]
+  #   Can be set to either a String (which will be interpreted as a full URI to the icon file), or as a Symbol, which will be expanded to +Netzke::Core.icons_uri+ + "/(icon).png". Defaults to nil (no icon)
+  # [+handler+]
+  #   A symbol that represents the JavaScript public method (snake-case), which will be called in the scope of the component instance. Defaults to +on_(action_name)+, which on JavaScript side will result in a call to +on(CamelCaseActionName)+
+  # +text+ and +tooltip+ default to "Humanized action name"
+  #
+  # When no block is given, the defaults will be used:
+  #
+  #     action :my_cool_action
+  #
+  # is equivalent (unless localization is found for this action) to:
+  #
+  #     action :my_cool_action do |c|
+  #       c.text = c.tooltip = "My cool action"
+  #       c.handler = :on_my_cool_action
+  #     end
+  #
+  # == Accessing component configuration from action block
+  #
+  # Because the action block get transformed into an instance method, it's possible to access the `config` method of the component itself:
+  #
+  #     action :show_report do |c|
+  #       c.text = "Show report"
+  #       c.icon = :report
+  #       c.disabled = !config[:can_see_report]
+  #     end
+  #
+  # == Overriding an action
+  #
+  # When extending a component, it's possible to override its actions. You'll need to call the +super+ method passing the configuration object to it in order to get the super-class' action configuration:
+  #
+  #     action :destroy do |c|
+  #       super(c) # original config
+  #       c.text = "Destroy (extended)" # overriding the text
+  #     end
+  #
+  # == I18n of actions
+  #
+  # +text+, +tooltip+ and +icon+ for an action will be picked up from a locale file (if located there) whenever they are not specified in the config.
+  # E.g., an action named "some_action" and defined in the component +MyComponents::CoolComponent+, will look for its text in:
+  #
+  #     I18n.t('my_components.cool_component.actions.some_action.text')
+  #
+  # for its tooltip in:
+  #
+  #     I18n.t('my_components.cool_component.actions.some_action.tooltip')
+  #
+  # and for its icon in:
+  #
+  #     I18n.t('my_components.cool_component.actions.some_action.icon')
+  module Actions
+    extend ActiveSupport::Concern
+
+    ACTION_METHOD_NAME = "%s_action"
+
+    included do
+      # Returns registered actions
+      class_attribute :registered_actions
+      self.registered_actions = []
+    end
+
+    module ClassMethods
+      def action(name, &block)
+        self.registered_actions |= [name]
+
+        method_name = ACTION_METHOD_NAME % name
+
+        if block_given?
+          define_method(method_name, &block)
+        else
+          define_method(method_name) do |action_config|
+            action_config
+          end
+        end
+      end
+
+      # Must stay public, used from ActionConfig
+      # @return [String|nil] full URI to an icon file by its name (provided we have a controller)
+      def uri_to_icon(icon)
+        Netzke::Core.with_icons ? [(controller && controller.config.relative_url_root), Netzke::Core.icons_uri, '/', icon.to_s, ".png"].join : nil
+      end
+    end
+
+    # All actions for this instance
+    def actions
+      @actions ||= self.class.registered_actions.inject({}) do |res, name|
+        action_config = Netzke::Core::ActionConfig.new(name, self)
+        send(ACTION_METHOD_NAME % name, action_config)
+        if action_config.excluded
+          res.merge(name.to_sym => {excluded: true})
+        else
+          res.merge(name.to_sym => action_config)
+        end
+      end
+    end
+
+    def js_configure(c)
+      super
+      c.actions = actions
+    end
+
+  private
+    def uri_to_icon(icon)
+      self.class.uri_to_icon(icon)
+    end
+  end
+end