netzke-core 0.7.7 → 0.8.0

data/lib/netzke/core/config_to_dsl_delegator.rb

@@ -0,0 +1,69 @@
+module Netzke::Core
+  # This module can be included in a component class to allows delegating the configuration options for a component into the level of the component's class.
+  # For example:
+  #
+  #     class SomeComponentBase < Netzke::Base
+  #       delegates_to_dsl :title, :html
+  #     end
+  #
+  # This will provide its children with class (DSL) methods +title+ and +html+:
+  #
+  #     class SomeComponent < SomeComponentBase
+  #       title "Some component"
+  #       html "HTML set in DSL"
+  #     end
+  #
+  # ... which would be equivalent to:
+  #
+  #     class SomeComponent < SomeComponentBase
+  #       def configure(c)
+  #         c.title = "Some component"
+  #         c.html = "HTML set in DSL"
+  #         super
+  #       end
+  #     end
+  #
+  # This may be handy when a frequently-inherited class implements some common options.
+  module ConfigToDslDelegator
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :delegated_options
+      self.delegated_options = []
+
+      class_attribute :delegated_defaults
+      self.delegated_defaults = {}
+
+      delegated_options.each do |property|
+        inherited_class.class.send(:define_method, property, lambda { |value|
+          self.delegated_defaults = self.delegated_defaults.dup if self.superclass.respond_to?(:delegated_defaults) && self.delegated_defaults == self.superclass.delegated_defaults
+          self.delegated_defaults[property.to_sym] = value
+        })
+      end
+    end
+
+    def configure(c)
+      c.merge! delegated_defaults
+      super
+    end
+
+    module ClassMethods
+      # Delegates specified configuration options to the class level
+      def delegates_to_dsl(*option_names)
+        self.delegated_options |= option_names
+      end
+
+      def inherited(inherited_class)
+        super
+
+        properties = self.delegated_options
+        properties.each do |property|
+          inherited_class.class.send(:define_method, property, lambda { |value|
+            self.delegated_defaults = self.delegated_defaults.dup if self.superclass.respond_to?(:delegated_defaults) && self.delegated_defaults == self.superclass.delegated_defaults
+            self.delegated_defaults[property.to_sym] = value
+          })
+        end
+      end
+    end
+  end
+end

data/lib/netzke/core/configuration.rb

@@ -0,0 +1,63 @@
+module Netzke::Core
+  # Components can implement class-level config options by using `class_attribute`, e.g.:
+  #
+  #   class MyComponent < Netzke::Base
+  #     class_attribute :title
+  #     self.title = "Title for all descendants of MyComponent"
+  #
+  #     js_configure do |c|
+  #       c.title = title
+  #     end
+  #   end
+  #
+  # Then before using MyComponent (e.g. in Rails' initializers), you can configure it like this:
+  #
+  #   MyComponent.title = "Better title"
+  #
+  # Alternatively, you can use the `Base.setup` method:
+  #
+  #   MyComponent.setup do |config|
+  #     config.title = "Better title"
+  #   end
+  module Configuration
+    extend ActiveSupport::Concern
+
+    # Use to configure a component on the class level, for example:
+    #
+    #   MyComponent.setup do |config|
+    #     config.enable_awesome_feature = true
+    #   end
+    module ClassMethods
+      def setup
+        yield self
+      end
+
+      # An array of server class config options that should not be passed to the client class. Can be overridden.
+      def server_side_config_options
+        [:eager_loading, :klass]
+      end
+    end
+
+    # Override to auto-configure components. Example:
+    #
+    #   class BookGrid < Netzke::Basepack::Grid
+    #     def configure(c)
+    #       super
+    #       c.model = "Book"
+    #     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:
+    #
+    #   action :do_something do |c|
+    #     c.title = "Do it for #{config.title}"
+    #   end
+    def config
+      @config ||= ActiveSupport::OrderedOptions.new
+    end
+  end
+end

data/lib/netzke/core/css_config.rb

@@ -0,0 +1,51 @@
+module Netzke
+  module Core
+    # This class is responsible of assemblage of stylesheet dependencies. It is passed as block parameter to the +css_configure+ DSL method:
+    #
+    #     class MyComponent < Netzke::Base
+    #       css_configure do |c|
+    #         c.require :extra_styles
+    #       end
+    #     end
+    class CssConfig
+
+      attr_accessor :required_files
+
+      def initialize(klass)
+        @klass = klass
+        @required_files = []
+      end
+
+      # Use it to specify extra stylesheet files to be loaded for the component.
+      #
+      # It may accept one or more symbols or strings.
+      #
+      # Symbols will be expanded following a convention, e.g.:
+      #
+      #     class MyComponent < Netzke::Base
+      #       css_configure do |c|
+      #         c.require :some_styles
+      #       end
+      #     end
+      #
+      # This will "require" a stylesheet file +{component_location}/my_component/stylesheets/some_styles.js+
+      #
+      # Strings will be interpreted as full paths to the required JavaScript file:
+      #
+      #     css_configure do |c|
+      #       c.require "#{File.dirname(__FILE__)}/my_component/one.css", "#{File.dirname(__FILE__)}/my_component/two.css"
+      #     end
+      def require(*args)
+        callr = caller.first
+        @required_files |= args.map{ |a| a.is_a?(Symbol) ? expand_css_require_path(a, callr) : a }
+      end
+
+    private
+
+      def expand_css_require_path(sym, callr)
+        %Q(#{callr.split(".rb:").first}/stylesheets/#{sym}.css)
+      end
+
+    end
+  end
+end

data/lib/netzke/core/dynamic_assets.rb

@@ -2,34 +2,6 @@ module Netzke
   module Core
     module DynamicAssets
       class << self
-        def touch_js
-          res = initial_dynamic_javascript << "\n"
-
-          include_base_js(res)
-          # Touch-specific JavaScript
-          res << File.new(File.expand_path("../../../../javascripts/touch.js", __FILE__)).read
-
-          # Pluggable JavaScript (may be used by other Netzke-powered gems like netzke-basepack)
-          Netzke::Core.touch_javascripts.each do |path|
-            f = File.new(path)
-            res << f.read
-          end
-
-          defined?(::Rails) && ::Rails.env.production? ? res.strip_js_comments : res
-        end
-
-        def touch_css
-          res = File.new(File.expand_path("../../../../stylesheets/core.css", __FILE__)).read
-
-          # Pluggable stylesheets (may be used by other Netzke-powered gems like netzke-basepack)
-          Netzke::Core.touch_stylesheets.each do |path|
-            f = File.new(path)
-            res << f.read
-          end
-
-          res
-        end
-
         def ext_js(form_authenticity_token)
           res = initial_dynamic_javascript(form_authenticity_token) << "\n"
 
@@ -59,34 +31,32 @@ module Netzke
           res
         end
 
-        protected
+      private
 
-          # Generates initial javascript code that is dependent on Rails settings
-          def initial_dynamic_javascript(form_authenticity_token)
-            res = []
-            res << %(Ext.Ajax.extraParams = {authenticity_token: '#{form_authenticity_token}'}; // Rails' forgery protection)
-            res << %{Ext.ns('Netzke');}
-            res << %{Ext.ns('Netzke.core');}
-            res << %{Netzke.RelativeUrlRoot = '#{ActionController::Base.config.relative_url_root}';}
-            res << %{Netzke.RelativeExtUrl = '#{ActionController::Base.config.relative_url_root}#{Netzke::Core.ext_uri}';}
+        # Generates initial javascript code that is dependent on Rails settings
+        def initial_dynamic_javascript(form_authenticity_token)
+          res = []
+          res << %(Ext.Ajax.extraParams = {authenticity_token: '#{form_authenticity_token}'}; // Rails' forgery protection)
+          res << %{Ext.ns('Netzke');}
+          res << %{Ext.ns('Netzke.core');}
+          res << %{Netzke.RelativeUrlRoot = '#{ActionController::Base.config.relative_url_root}';}
+          res << %{Netzke.ControllerUrl = '#{ActionController::Base.config.relative_url_root}#{Rails.application.routes.url_helpers.netzke_path('')}';}
+          res << %{Netzke.RelativeExtUrl = '#{ActionController::Base.config.relative_url_root}#{Netzke::Core.ext_uri}';}
 
-            res << %{Netzke.core.directMaxRetries = #{Netzke::Core.js_direct_max_retries};}
+          res << %{Netzke.core.directMaxRetries = #{Netzke::Core.js_direct_max_retries};}
 
-            res.join("\n")
-          end
-
-          def include_base_js(arry)
-            # JavaScript extensions
-            arry << File.new(File.expand_path("../../../../javascripts/core_extensions.js", __FILE__)).read
+          res.join("\n")
+        end
 
-            # Base Netzke component JavaScript
-            arry << File.new(File.expand_path("../../../../javascripts/base.js", __FILE__)).read
-          end
+        def include_base_js(arry)
+          # JavaScript extensions
+          arry << File.new(File.expand_path("../../../../javascripts/js_extensions.js", __FILE__)).read
 
-        # end protected
+          # Base Netzke component JavaScript
+          arry << File.new(File.expand_path("../../../../javascripts/base.js", __FILE__)).read
+        end
 
       end
-
     end
   end
 end

data/lib/netzke/{embedding.rb → core/embedding.rb}

@@ -1,21 +1,19 @@
-module Netzke
+module Netzke::Core
   # The following methods are used when a component is generated stand-alone (as a part of a HTML page)
   module Embedding
-
     # Instantiating
     def js_component_instance
-      %Q{Netzke.page.#{name.jsonify} = Ext.create("#{self.class.js_alias}", #{js_config.to_nifty_json});}
+      %Q{Netzke.page.#{name.jsonify} = Ext.create("#{self.class.js_config.class_alias}", #{js_config.to_nifty_json});}
     end
 
     # Rendering
     def js_component_render
-      %Q{Netzke.page.#{name.jsonify}.render("#{name.to_s.split('_').join('-')}-netzke");} unless self.class.js_xtype == "netzkewindow"
+      %Q{Netzke.page.#{name.jsonify}.render("#{name.to_s.split('_').join('-')}-netzke");} unless self.class.js_config.xtype == "netzkewindow"
     end
 
     # Container for rendering
     def js_component_html
       %Q{<div id="#{name.to_s.split('_').join('-')}-netzke" class="netzke-component"></div>}
     end
-
   end
-end
+end

data/lib/netzke/core/endpoint_response.rb

@@ -0,0 +1,15 @@
+module Netzke::Core
+  # Represents the endpoint response at the server side.
+  # An instance of it is passed as the second parameter to the +endpoint+ block.
+  class EndpointResponse < ::Hash
+    def method_missing(name, *params)
+      if name.to_s =~ /(.+)=$/
+        self[$1.to_sym] = params.first
+      else
+        self[name] = self.class.new if self[name].nil?
+        self[name] = params if params.present?
+        self[name]
+      end
+    end
+  end
+end

data/lib/netzke/core/javascript.rb

@@ -0,0 +1,111 @@
+module Netzke::Core
+  # Client class definition and instantiation.
+  #
+  # == JavaScript instance methods
+  #
+  # The following public JavaScript methods are defined on (mixed-in into) all Netzke components (for detailed documentation on them see the inline documentation in javascript/base.js and javascript/ext.js files):
+  # * netzkeLoadComponent - dynamically loads a child Netzke component
+  # * netzkeInstantiateComponent - instantiates and returns a Netzke component by its item_id
+  # * netzkeFeedback - shows a feedback message
+  # * componentNotInSession - gets called when the session that the component is defined in gets expired. Override it to do whatever is appropriate.
+  module Javascript
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Configures JS class
+      # Example:
+      #
+      #   js_configure do |c|
+      #     # c is an instance of ClientClass
+      #     c.title = "My title"
+      #     c.mixin
+      #     c.require :extra_js
+      #     # ...etc
+      #   end
+      #
+      # For more details see {Netzke::Core::ClientClass}
+      def js_configure &block
+        @js_configure_blocks ||= []
+        @js_configure_blocks << block
+      end
+
+      # Class-level client class config
+      def js_config
+        return @js_config if @js_config.present?
+        @js_config = Netzke::Core::ClientClass.new(self)
+        @js_config.tap do |c|
+          (@js_configure_blocks || []).each{|block| block.call(c)}
+        end
+      end
+    end
+
+    # Builds {#js_config} used for instantiating a client class. Override it when you need to extend/modify the config for the JS component intance. It's *not* being called when the *server* class is being instantiated (e.g. to process an endpoint call). With other words, it's only being called before a component is first being loaded in the browser. so, it's ok to do heavy stuf fhere, like building a tree panel nodes from the database.
+    def js_configure(c)
+      c.merge!(normalized_config)
+
+      # Unique id of the component
+      c.id = js_id
+
+      # Configuration for all of our non-lazy-loaded children specified here. We can refer to them in +items+ so they get instantiated by Ext.
+      c.netzke_components = js_components unless js_components.empty?
+
+      # Endpoints (besides the default "deliver_component" - JavaScript side already knows about it)
+      endpoints = self.class.endpoints.keys - [:deliver_component]
+
+      # pass them as strings, not as symbols
+      c.endpoints = endpoints.map(&:to_s) unless endpoints.empty?
+
+      # Include our xtype
+      c.xtype = self.class.js_config.xtype
+
+      # Include our alias: Ext.createByAlias may be used to instantiate the component.
+      c.alias = self.class.js_config.class_alias
+
+      # So we can use getComponent(<component_name>) to retrieve a child component
+      c.item_id ||= name
+
+      c.i18n = js_translate_properties if js_translate_properties.present?
+
+      c.netzke_plugins = plugins.map{ |p| p.to_s.camelcase(:lower) } if plugins.present?
+
+      # we need to pass them as strigs, not as symbols
+      c.tools = c.tools.map(&:to_s) if c.tools.present?
+
+      c.flash = session[:flash] if session && session[:flash].present?
+    end
+
+    # Instance-level client class config. The result of this method (a hash) is converted to a JSON object and passed as options to the constructor of our JavaScript class.
+    # Not to be overridden, override {#js_configure} instead.
+    def js_config
+      @js_config ||= ActiveSupport::OrderedOptions.new.tap{|c| js_configure(c)}
+    end
+
+    # Hash containing configuration for all child components to be instantiated at the JS side
+    def js_components
+      @js_components ||= eagerly_loaded_components.inject({}) do |out, (name, config)|
+        instance = component_instance(name.to_sym)
+        out.merge(name => instance.js_config)
+      end
+    end
+
+    # All the JS-code required by this instance of the component to be instantiated in the browser.
+    # It includes JS-classes for the parents, eagerly loaded child components, and itself.
+    def js_missing_code(cached = [])
+      code = dependency_classes.inject("") do |r,k|
+        cached.include?(k.js_config.xtype) ? r : r + k.js_config.code_with_dependencies#.strip_js_comments
+      end
+      code.blank? ? nil : code
+    end
+
+  private
+
+    # Merges all the translations in the class hierarchy
+    # Note: this method can't be moved out to ClientClass, because I18n is loaded only once, when other Ruby classes are evaluated; so, this must remain at instance level.
+    def js_translate_properties
+      @js_translate_properties ||= self.class.netzke_ancestors.inject({}) do |r,klass|
+        hsh = klass.js_config.translated_properties.inject({}) { |h,t| h.merge(t => I18n.t("#{klass.i18n_id}.#{t}")) }
+        r.merge(hsh)
+      end
+    end
+  end
+end

data/lib/netzke/core/panel.rb

@@ -0,0 +1,11 @@
+module Netzke
+  module Core
+    # A very simple panel with an automatically set title. Can be used as a child component +klass+.
+    class Panel < Netzke::Base
+      def configure(c)
+        c.title ||= name.to_s.humanize
+        super
+      end
+    end
+  end
+end

data/lib/netzke/{plugins.rb → core/plugins.rb}

@@ -1,4 +1,4 @@
-module Netzke
+module Netzke::Core
   module Plugins
     extend ActiveSupport::Concern
 
@@ -10,20 +10,25 @@ module Netzke
 
     module ClassMethods
       # Defines a plugin
-      def plugin(name, config = {}, &block)
-        component(name, config, &block)
+      def plugin(name, &block)
         register_plugin(name)
+        component name do |c|
+          block.call(c) if block_given?
+
+          # plugins are *always* eagerly loaded
+          c.eager_loading = true
+        end
       end
 
+    private
       # Register a plugin
       def register_plugin(name)
         self.registered_plugins |= [name]
       end
-
     end
 
     def plugins
       self.class.registered_plugins
     end
   end
-end
+end