netzke-core 0.8.3 → 0.8.4

data/lib/netzke/base.rb

@@ -58,7 +58,7 @@ module Netzke
     include Core::Actions
     include Core::Html if const_defined? :Haml
 
-    # DELETE ME
+    # TODO: get rid of it
     class_attribute :default_instance_config
     self.default_instance_config = {}
 
@@ -70,12 +70,18 @@ module Netzke
     # Parent component
     attr_reader :parent
 
-    # Name that the parent can reference us by. The last part of +js_id+
+    # Name that the parent can reference us by
     attr_reader :name
 
-    # Global id in the components tree, following the double-underscore notation, e.g. +books__config_panel__form+
+    # Global id in the component tree, following the double-underscore notation, e.g. +books__config_panel__form+
     attr_reader :js_id
 
+    # JS id in the context of the parent
+    attr_reader :item_id
+
+    # Component's path in the component tree
+    attr_reader :path
+
     class << self
       # Instance of component by config
       def instance_by_config(config)
@@ -109,11 +115,29 @@ module Netzke
 
     # Instantiates a component instance. A parent can optionally be provided.
     def initialize(conf = {}, parent = nil)
-      @passed_config = conf.deep_dup # configuration passed at the moment of instantiation
-      @parent        = parent
-      @name          = conf[:name] || self.class.name.underscore
-      @js_id         = parent.nil? ? @name : "#{parent.js_id}__#{@name}"
-      @flash         = []
+      @passed_config = conf
+
+      # parent component
+      @parent = parent
+
+      # name fo the component used in the +component+ DSL block, and is a part of component's +@path+
+      @name = conf[:name] || self.class.name.underscore
+
+      # path down the composition hierarchy (composed of names)
+      @path = parent.nil? ? @name : "#{parent.path}__#{@name}"
+
+      # JS id in the scope of the parent component. Auto-generated when using multiple instance loading.
+      # Full JS id will be built using these along the +@path+
+      @item_id = conf[:item_id] || @name
+
+      # JS full ID. Similar to +path+, but composed of item_id's. Differs from @path when multiple instances are being loaded.
+      @js_id = parent.nil? ? @item_id : [parent.js_id, @item_id].join("__")
+
+      # TODO: get rid of this in 0.9
+      @flash = []
+
+      # Make +client_config+ accessible in +configure+ before calling +super+
+      config.client_config = conf.delete(:client_config) || {}
 
       # Build complete component configuration
       configure(config)
@@ -125,8 +149,7 @@ module Netzke
 
   private
 
-    # TODO: needs rework
-    # TODO: rename to smth more appropriate
+    # TODO: get rid of this in 0.9
     def flash(flash_hash)
       level = flash_hash.keys.first
       raise "Unknown message level for flash" unless %(notice warning error).include?(level.to_s)

data/lib/netzke/core.rb

@@ -15,6 +15,7 @@ module Netzke
   # * ext_path - absolute path to your Ext code root
   # * icons_uri - relative URI to the icons
   module Core
+    autoload :DslConfigBase, 'netzke/core/dsl_config_base'
     autoload :ComponentConfig, 'netzke/core/component_config'
     autoload :ActionConfig, 'netzke/core/action_config'
     autoload :Panel, 'netzke/core/panel'

data/lib/netzke/core/action_config.rb

@@ -8,10 +8,10 @@ module Netzke::Core
   #       c.icon = :tick
   #     end
   #   end
-  class ActionConfig < ActiveSupport::OrderedOptions
+  class ActionConfig < DslConfigBase
     def initialize(name, component)
-      @component = component
-      @name = name.to_s
+      super
+
       @text = @tooltip = @icon = ""
 
       build_localized_attributes

data/lib/netzke/core/actions.rb

@@ -14,11 +14,18 @@ module Netzke::Core
   #
   # 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.
   #
+  # [+text+]
+  #   The text of the action (defaults to humanized action name)
   # [+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)
+  # [+tooltip+]
+  #   The tooltip of the action (defaults to humanized action name)
+  # [+disabled+]
+  #   When set to +true+, renders this action as disabled
   # [+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"
+  # [+excluded+]
+  #   When set to true, gets the action excluded from menus and toolbars
   #
   # When no block is given, the defaults will be used:
   #
@@ -64,12 +71,37 @@ module Netzke::Core
   # and for its icon in:
   #
   #     I18n.t('my_components.cool_component.actions.some_action.icon')
+  #
+  # == Using actions
+  #
+  # Actions can be refferred to in the component configuration as symbols. The most common use cases are configuring toolbars.
+  # For example, to configure a bottom toolbar to show a button reflecting the +:do_something+ action:
+  #
+  #     def configure(c)
+  #       super
+  #       c.bbar = [:do_something]
+  #     end
+  #
+  # Using the +docked_items+ property is also possible:
+  #
+  #     def configure(c)
+  #       super
+  #       c.docked_items = [{
+  #         xtype: :toolbar,
+  #         dock: :left,
+  #         items: [:do_something]
+  #       }]
+  #     end
+  #
+  # == Interfering with action events in client class
+  #
+  # For each action Netzke creates an event on the level of the parent component following the convention '<action_name>click'. The handler receives the component itself as a parameter. If the handler returns +false+, the action event is not further propagated.
   module Actions
     extend ActiveSupport::Concern
 
     included do
       # Declares Base.action, for declaring actions, and Base#actions, which returns a [Hash] of all action configs by name
-      declare_dsl_for :actions
+      declare_dsl_for :actions, config_class: Netzke::Core::ActionConfig
     end
 
     module ClassMethods

data/lib/netzke/core/component_config.rb

@@ -1,11 +1,12 @@
 module Netzke::Core
-  class ComponentConfig < ActiveSupport::OrderedOptions
-    def initialize(name, parent)
+  class ComponentConfig < DslConfigBase
+    def initialize(name, component)
       self.name = name.to_s
     end
 
     def set_defaults!
       self.item_id ||= name # default item_id
+      self.client_config ||= {}
       self.klass ||= name.camelize.constantize # default klass
     end
   end

data/lib/netzke/core/composition.rb

@@ -81,26 +81,31 @@ module Netzke::Core
 
     included do
       # Declares Base.component, for declaring child componets, and Base#components, which returns a [Hash] of all component configs by name
-      declare_dsl_for :components
+      declare_dsl_for :components, config_class: Netzke::Core::ComponentConfig
 
       # Loads a component on browser's request. Every Netzke component gets this endpoint.
-      # <tt>params</tt> should contain:
-      # * <tt>:cache</tt> - an array of component classes cached at the browser
-      # * <tt>:id</tt> - reference to the component
-      # * <tt>:container</tt> - Ext id of the container where in which the component will be rendered
+      # +params+ should contain:
+      #   [cache] an array of component classes cached at the browser
+      #   [name] name of the child component to be loaded
+      #   [index] clone index of the loaded component
       endpoint :deliver_component do |params, this|
         cache = params[:cache].split(",") # array of cached xtypes
         component_name = params[:name].underscore.to_sym
-        component = components[component_name] && !components[component_name][:excluded] && component_instance(component_name)
 
-        if component
-          js, css = component.js_missing_code(cache), component.css_missing_code(cache)
+        item_id = "#{component_name}#{params[:index]}"
+
+        cmp_instance = components[component_name] &&
+          !components[component_name][:excluded] &&
+          component_instance(component_name, {item_id: item_id, client_config: params[:client_config]})
+
+        if cmp_instance
+          js, css = cmp_instance.js_missing_code(cache), cmp_instance.css_missing_code(cache)
           this.netzke_eval_js(js) if js.present?
           this.netzke_eval_css(css) if css.present?
 
-          this.netzke_component_delivered(component.js_config);
+          this.netzke_component_delivered(cmp_instance.js_config);
         else
-          this.netzke_component_delivery_failed(component_name: component_name, msg: "Couldn't load component '#{component_name}'")
+          this.netzke_component_delivery_failed(item_id: item_id, msg: "Couldn't load component '#{item_id}'")
         end
       end
 
@@ -116,20 +121,14 @@ module Netzke::Core
       @components_in_config || (normalize_config || true) && @components_in_config
     end
 
-    # Called when the method_missing tries to processes a non-existing component. Override when needed.
-    def component_missing(aggr)
-      flash :error => "Unknown component #{aggr} for #{name}"
-      {:feedback => @flash}.netzke_jsonify.to_json
-    end
-
     # Recursively instantiates a child component based on its "path": e.g. if we have component :component1 which in its turn has component :component2, the path to the latter would be "component1__component2"
     # @param name [Symbol] component name
-    def component_instance(name)
-      @_component_instance ||= {} # memoization
-      @_component_instance[name] ||= name.to_s.split('__').inject(self) do |out, cmp_name|
+    def component_instance(name, strong_config = {})
+      name.to_s.split('__').inject(self) do |out, cmp_name|
         cmp_config = out.components[cmp_name.to_sym]
-        raise ArgumentError, "No component '#{cmp_name}' defined for '#{out.js_id}'" if cmp_config.nil? || cmp_config[:excluded]
+        raise ArgumentError, "No component '#{cmp_name}' defined for '#{out.path}'" if cmp_config.nil? || cmp_config[:excluded]
         cmp_config[:name] = cmp_name
+        cmp_config.merge!(strong_config)
         cmp_config[:klass].new(cmp_config, out)
       end
     end
@@ -146,22 +145,6 @@ module Netzke::Core
       res.uniq
     end
 
-    # JS id of a component 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 component will simply provide an erroneous ID.
-    # For 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 component exists in the hierarchy, its global id will be returned, otherwise <tt>nil</tt> will be returned.
-    # @param ref [Symbol] reference to a child component
-    # @return [String] JS id
-    def js_id_by_reference(ref)
-      ref = ref.to_s
-      return parent && parent.js_id if ref == "parent"
-      substr = ref.sub(/^parent__/, "")
-      if substr == ref # there's no "parent__" in the beginning
-        return js_id + "__" + ref
-      else
-        return parent.js_id_by_reference(substr)
-      end
-    end
-
     def extend_item(item)
       item = detect_and_normalize(:component, item)
       @components_in_config << item[:netzke_component] if include_component?(item)

data/lib/netzke/core/configuration.rb

@@ -47,11 +47,10 @@ module Netzke::Core
     #     end
     #   end
     def configure(c)
-      # passed config
       c.merge!(@passed_config)
     end
 
-    # Complete server class configuration. Can be accessed from within endpoint, component, and action blocks, as well as any other instance method, for example:
+    # Complete configuration for server class instance. Can be accessed from within endpoint, component, and action blocks, as well as any other instance method, for example:
     #
     #   action :do_something do |c|
     #     c.title = "Do it for #{config.title}"
@@ -60,7 +59,6 @@ module Netzke::Core
       @config ||= ActiveSupport::OrderedOptions.new
     end
 
-
   protected
 
     # During the normalization of config object, +extend_item+ is being called with each item found (recursively) in there.

data/lib/netzke/core/dsl_config_base.rb

@@ -0,0 +1,9 @@
+module Netzke::Core
+  # Base for ActionConfig, ComponentConfig, etc
+  class DslConfigBase < ActiveSupport::OrderedOptions
+    def initialize(name, component)
+      @component = component
+      @name = name.to_s
+    end
+  end
+end

data/lib/netzke/core/dsl_support.rb

@@ -25,19 +25,19 @@ module Netzke
         # 2) Instance method `components` that returns a hash of all components configs. This hash is built by passing a new instance of `Netzke::Core::ComponentConfig` to each of the methods described in 1). Presence of `Netzke::Core::ComponentConfig` is assumed.
         #
         # Besides components, this method is being used in Core for DSL for actions.
-        def declare_dsl_for(things)
+        def declare_dsl_for(things, options = {})
           things = things.to_s
           storage_attribute = :"_declared_#{things}"
 
           class_attribute storage_attribute
           send("#{storage_attribute}=", [])
 
-          define_dsl_method(things, storage_attribute)
-          define_collector_method(things, storage_attribute)
+          define_dsl_method(things, storage_attribute, options)
+          define_collector_method(things, storage_attribute, options)
         end
 
 
-        def define_dsl_method(things, storage_attribute)
+        def define_dsl_method(things, storage_attribute, options)
           thing = things.singularize
 
           define_singleton_method thing do |name, &block|
@@ -47,9 +47,9 @@ module Netzke
           end
         end
 
-        def define_collector_method(things, storage_attribute)
+        def define_collector_method(things, storage_attribute, options)
           thing = things.singularize
-          config_class = "Netzke::Core::#{thing.camelcase}Config".constantize
+          config_class = options[:config_class] || Netzke::Core::DslConfigBase
 
           define_method things do
             # memoization

data/lib/netzke/core/javascript.rb

@@ -43,11 +43,8 @@ module Netzke::Core
     def js_configure(c)
       c.merge!(normalized_config)
 
-      # So we can use getComponent(<component_name>) to retrieve a child component
-      c.item_id ||= name
-
-      %w[id netzke_components endpoints xtype alias i18n netzke_plugins flash].each do |thing|
-        js_thing = send "js_#{thing}"
+      %w[id item_id path netzke_components endpoints xtype alias i18n netzke_plugins flash].each do |thing|
+        js_thing = send(:"js_#{thing}")
         c[thing] = js_thing if js_thing.present?
       end
 
@@ -56,10 +53,18 @@ module Netzke::Core
       component_session.clear
     end
 
+    def js_path
+      @path
+    end
+
     def js_xtype
       self.class.js_config.xtype
     end
 
+    def js_item_id
+      @item_id
+    end
+
     # Ext.createByAlias may be used to instantiate the component.
     def js_alias
       self.class.js_config.class_alias
@@ -74,6 +79,7 @@ module Netzke::Core
       plugins.map{ |p| p.to_s.camelcase(:lower) }
     end
 
+    # TODO: get rid of this in 0.9
     def js_flash
       session && session[:flash]
     end

data/lib/netzke/core/railz/controller_extensions.rb

@@ -2,6 +2,42 @@ module Netzke
   module Railz
     # Before each request, Netzke::Base.controller and Netzke::Base.session are set, to be accessible from components.
     module ControllerExtensions
+      class DirectRequest
+        def initialize(params)
+          @params = params
+        end
+
+        def cmp_path
+          @params[:path]
+        end
+
+        def endpoint
+          @params[:endpoint].underscore
+        end
+
+        def args
+          # for backward compatibility, fall back to old data structure (with the endpoint params being in the root of
+          # 'data')
+          remoting_args["configs"] ? remoting_args["args"] : remoting_args
+        end
+
+        def client_configs
+          # if no configs are provided, the behavior is the old one, and thus all instances the same child component
+          # will be treated as one
+          remoting_args["configs"] || []
+        end
+
+        def tid
+          @params[:tid]
+        end
+
+      private
+
+        def remoting_args
+          @_remoting_args ||= @params[:data].first
+        end
+      end
+
       extend ActiveSupport::Concern
 
       included do
@@ -20,11 +56,12 @@ module Netzke
         if params['_json'] # this is a batched request
           response = []
           params['_json'].each do |batch|
-            # response << invoke_endpoint(batch)
-            response << direct_response(batch, invoke_endpoint(batch))
+            direct_request = DirectRequest.new(batch)
+            response << direct_response(direct_request, invoke_endpoint(direct_request))
           end
         else # this is a single request
-          response = direct_response(params, invoke_endpoint(params))
+          direct_request = DirectRequest.new(params)
+          response = direct_response(direct_request, invoke_endpoint(direct_request))
         end
 
         render text: response.to_json, layout: false
@@ -50,44 +87,34 @@ module Netzke
 
     protected
 
-      def direct_response(request_params, endpoint_response)
-        path, action, params, tid = parse_request_params(request_params)
-        component_name, *sub_components = path.split('__')
+      def direct_response(request, endpoint_response)
+        component_name, *sub_components = request.cmp_path.split('__')
 
         # We render text/plain, so that the browser never modifies our response
         response.headers["Content-Type"] = "text/plain; charset=utf-8"
 
-        { :type => "rpc",
-          :tid => tid,
-          :action => component_name,
-          :method => action,
-          :result => ActiveSupport::JSON::Variable.new(endpoint_response.netzke_jsonify.to_json)
+        { type: :rpc,
+          tid: request.tid,
+          action: component_name,
+          method: request.endpoint,
+          result: ActiveSupport::JSON::Variable.new(endpoint_response.netzke_jsonify.to_json)
         }
       end
 
-      def invoke_endpoint(request_params)
-        path, action, params, tid = parse_request_params(request_params)
-
-        component_name, *sub_components = path.split('__')
+      def invoke_endpoint(request)
+        component_name, *sub_components = request.cmp_path.split('__')
         components_in_session = session[:netzke_components]
 
         if components_in_session
-          component_instance = Netzke::Base.instance_by_config(components_in_session[component_name.to_sym])
-          component_instance.invoke_endpoint((sub_components + [action]).join("__"), params)
+          cmp_config = components_in_session[component_name.to_sym]
+          cmp_config[:client_config] = request.client_configs.shift || {}
+          component_instance = Netzke::Base.instance_by_config(cmp_config)
+          component_instance.invoke_endpoint((sub_components + [request.endpoint]).join("__"), request.args, request.client_configs)
         else
-          {:netzke_component_not_in_session => true}
+          {netzke_session_expired: []}
         end
       end
 
-      def parse_request_params(params)
-        path = params[:act]
-        action = params[:method].underscore
-        ep_params = params[:data].try(:first) # Rails >= 3.2.11 returns nil in request_params[:data]
-        tid = params[:tid]
-
-        [path, action, ep_params, tid]
-      end
-
       # The dispatcher for the old-style requests (used for multi-part form submission). The URL contains the name of the component,
       # as well as the method of this component to be called, according to the double underscore notation.
       # E.g.: some_grid__post_grid_data.
@@ -95,7 +122,8 @@ module Netzke
         component_name, *sub_components = endpoint_path.split('__')
         component_instance = Netzke::Base.instance_by_config(session[:netzke_components][component_name.to_sym])
 
-        # We can't do this here; this method is only used for classic form submission, and the response from the server should be the (default) "text/html"
+        # We can't do this here; this method is only used for classic form submission, and the response from the server
+        # should be the (default) "text/html"
         # response.headers["Content-Type"] = "text/plain; charset=utf-8"
 
         render :text => component_instance.invoke_endpoint(sub_components.join("__"), params).netzke_jsonify.to_json, :layout => false