netzke-core 0.7.7 → 0.8.0

data/lib/netzke/core/client_class.rb

@@ -0,0 +1,252 @@
+module Netzke
+  module Core
+    # This class is responsible of creation of the client (JavaScript) class. It is passed as block parameter to the `js_configure` DSL method:
+    #
+    #     class MyComponent < Netzke::Base
+    #       js_configure do |c|
+    #         c.extend = "Ext.form.Panel"
+    #       end
+    #     end
+    class ClientClass
+      attr_accessor :required_files, :base_class, :properties, :mixins, :translated_properties
+
+      def initialize(klass)
+        @klass = klass
+        @required_files = []
+        @mixins = []
+        @properties = {
+          extend: extended_class,
+          alias: class_alias,
+        }
+        @properties[:mixins] = ['Netzke.classes.Core.Mixin'] if extending_extjs_component?
+        @translated_properties = []
+      end
+
+      # Allows assigning JavaScript prototype properties, including functions:
+      #
+      #     class MyComponent < Netzke::Base
+      #       js_configure do |c|
+      #         # this will result in the +title+ property defined on the client class prototype
+      #         c.title = "My cool component"
+      #
+      #         # this will result in the +onButtonPress+ function defined on the client class prototype
+      #         c.on_button_press = <<-JS
+      #           function(){
+      #             // ...
+      #           }
+      #         JS
+      #       end
+      #     end
+      #
+      # An alternative way to define prototype properties is by using "mixins", see {ClientClass#mixin}
+      #
+      # Class attributes are accessible from inside +js_configure+:
+      #
+      #     class MyComponent < Netzke::Base
+      #       class_attribute :title
+      #       self.title = "Some default title"
+      #       js_configure do |c|
+      #         c.title = self.title
+      #       end
+      #     end
+      #
+      # Now you can configure your component on a class level like this:
+      #
+      #     # e.g. in Rails initializers
+      #     MyComponent.title = "New title for all MyComponents"
+      #
+      # Or using a helper method provided by Netzke:
+      #
+      #     MyComponent.setup do |config|
+      #       config.title = "New title for all MyComponents"
+      #     end
+      def method_missing(name, *args)
+        if name =~ /(.+)=$/
+          value = args.first
+          @properties[$1.to_sym] = value.is_a?(String) && value =~ /^\s*function/ ? ActiveSupport::JSON::Variable.new(value) : value
+        else
+          @properties[name.to_sym]
+        end
+      end
+
+      # Use it to specify JavaScript files to be loaded *before* this component's JavaScript code. Useful when using external extensions required by this component.
+      #
+      # It may accept one or more symbols or strings.
+      #
+      # Symbols will be expanded following a convention, e.g.:
+      #
+      #     class MyComponent < Netzke::Base
+      #       js_configure do |c|
+      #         c.require :some_library
+      #       end
+      #     end
+      #
+      # This will "require" a JavaScript file +{component_location}/my_component/javascripts/some_library.js+
+      #
+      # Strings will be interpreted as full paths to the required JavaScript file:
+      #
+      #     js_configure do |c|
+      #       c.require "#{File.dirname(__FILE__)}/my_component/one.js", "#{File.dirname(__FILE__)}/my_component/two.js"
+      #     end
+      def require(*args)
+        callr = caller.first
+
+        @required_files |= args.map{ |a| a.is_a?(Symbol) ? expand_require_path(a, callr) : a }
+      end
+
+      # Use it to "mixin" JavaScript objects defined in a separate file. It may accept one or more symbols or strings.
+      #
+      # Symbols will be expanded following a convention, e.g.:
+      #
+      #     class MyComponent < Netzke::Base
+      #       js_configure do |c|
+      #         c.mixin :some_functionality
+      #         #...
+      #       end
+      #     end
+      #
+      # This will "mixin" a JavaScript object defined in a file named +{component_location}/my_component/javascripts/some_functionality.js+, which way contain something like this:
+      #
+      #     {
+      #       someProperty: 100,
+      #       someMethod: function(params){
+      #         // ...
+      #       }
+      #     }
+      #
+      # Also accepts a string, which will be interpreted as a full path to the file (useful for sharing mixins between classes).
+      # With no parameters, will assume :component_class_name_underscored.
+      #
+      # Also, see defining JavaScript prototype properties with {ClientClass#method_missing}.
+      def mixin(*args)
+        args << @klass.name.split("::").last.underscore.to_sym if args.empty?
+        callr = caller.first
+        args.each do |a|
+          @mixins << (a.is_a?(Symbol) ? expand_require_path(a, callr) : a)
+        end
+      end
+
+      # Defines the "i18n" config property, that is a translation object for this component, such as:
+      #   i18n: {
+      #     overwriteConfirm: "Are you sure you want to overwrite preset '{0}'?",
+      #     overwriteConfirmTitle: "Overwriting preset",
+      #     deleteConfirm: "Are you sure you want to delete preset '{0}'?",
+      #     deleteConfirmTitle: "Deleting preset"
+      #   }
+      #
+      # E.g.:
+      #
+      #   class MyComponent < Netzke::Base
+      #     js_configure do |c|
+      #       c.translate :overwrite_confirm, :overwrite_confirm_title, :delete_confirm, :delete_confirm_title
+      #     end
+      #   end
+      def translate(*args)
+        @translated_properties |= args
+      end
+
+      # The alias, required by Ext.Component, e.g.: widget.helloworld
+      def class_alias
+        [alias_prefix, xtype].join(".")
+      end
+
+      # Builds this component's xtype
+      # E.g.: netzkebasepackwindow, netzkebasepackgridpanel
+      def xtype
+        @klass.name.gsub("::", "").downcase
+      end
+
+      # Component's JavaScript class declaration.
+      # It gets stored in the JS class cache storage (Netzke.classes) at the client side to be reused at the moment of component instantiation.
+      def class_code
+        res = []
+        # Defining the scope if it isn't known yet
+        res << %{Ext.ns("#{scope}");} unless scope == default_scope
+
+        res << class_declaration
+
+        # Store created class xtype in the cache
+        res << %(
+Netzke.cache.push('#{xtype}');
+)
+
+        res.join("\n")
+      end
+
+      # Top level scope which will be used to scope out Netzke classes
+      def default_scope
+        "Netzke.classes"
+      end
+
+      # Returns the scope of this component
+      # e.g. "Netzke.classes.Netzke.Basepack"
+      def scope
+        [default_scope, *@klass.name.split("::")[0..-2]].join(".")
+      end
+
+      # Returns the full name of the JavaScript class, including the scopes *and* the common scope, which is 'Netzke.classes'.
+      # E.g.: "Netzke.classes.Netzke.Basepack.GridPanel"
+      def class_name
+        [scope, @klass.name.split("::").last].join(".")
+      end
+
+      # Whether we have to inherit from an Ext JS component, or a Netzke component
+      def extending_extjs_component?
+        @klass.superclass == Netzke::Base
+      end
+
+      # Returns all required JavaScript files as a string
+      def required
+        res = ""
+
+        # Prevent re-including code that was already required by the parent
+        # (thus, only require those JS files when require_js was defined in the current class, not in its ancestors)
+        # FIXME!
+        ((@klass.singleton_methods(false).map(&:to_sym).include?(:include_js) ? include_js : []) + required_files).each do |path|
+          f = File.new(path)
+          res << f.read << "\n"
+        end
+
+        res
+      end
+
+      # JavaScript code needed for this particulaer class. Includes external JS code and the JS class definition for self.
+      def code_with_dependencies
+        [required, class_code].join("\n")
+      end
+
+      # Generates declaration of the JS class as direct extension of a Ext component
+      def class_declaration
+%(Ext.define('#{class_name}', #{properties_as_string});)
+      end
+
+      # Alias prefix: 'widget' for components, 'plugin' for plugins
+      def alias_prefix
+        @klass < Netzke::Plugin ? "plugin" : "widget"
+      end
+
+      def mixins_as_string
+        mixins.presence && mixins.map do |f|
+          as_string = File.read(f)
+          as_string.sub!('{', ' ')
+          as_string[as_string.rindex('}')] = ' '
+          as_string.rstrip
+        end.join(",\n")
+      end
+
+      def properties_as_string
+        [properties.to_nifty_json.chop,  mixins_as_string].compact.join(",\n") + "}"
+      end
+
+      # Default extended class
+      def extended_class
+        extending_extjs_component? ? "Ext.panel.Panel" : @klass.superclass.js_config.class_name
+      end
+
+    private
+      def expand_require_path(sym, callr)
+        %Q(#{callr.split(".rb:").first}/javascripts/#{sym}.js)
+      end
+    end
+  end
+end

data/lib/netzke/core/component_config.rb

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

data/lib/netzke/core/composition.rb

@@ -0,0 +1,274 @@
+module Netzke::Core
+  # Any Netzke component can define child components, which can either be statically nested in the compound layout (e.g. as different regions of the 'border' layout), or dynamically loaded at a request (as is the advanced search panel in Basepack::GridPanel, for example).
+  #
+  # == Defining a component
+  #
+  # You can define a child component by calling the +component+ class method which normally requires a block:
+  #
+  #     component :users do |c|
+  #       c.klass = GridPanel
+  #       c.model = "User"
+  #       c.title = "Users"
+  #     end
+  #
+  # If no configuration is required, and the component's class name can be derived from its name, then the block can be omitted, e.g.:
+  #
+  #     component :user_grid
+  #
+  # which is equivalent to:
+  #
+  #     component :user_grid do |c|
+  #       c.klass = UserGrid
+  #     end
+  #
+  # == Overriding a component
+  #
+  # When overriding a component, the `super` method should be called, with the configuration object passed to it as parameter:
+  #
+  #     component :users do |c|
+  #       super(c)
+  #       c.title = "Modified Title"
+  #     end
+  #
+  # == Referring to components in layouts
+  #
+  # A child component can be referred in the layout by using symbols:
+  #
+  #     component :users do |c|
+  #       c.title = "A Netzke component"
+  #     end
+  #
+  #     def configure(c)
+  #       super
+  #       c.items = [
+  #         { xtype: :panel, title: "Simple Ext panel" },
+  #         :users # a Netzke component
+  #       ]
+  #     end
+  #
+  # If an extra (layout) configuration should be provided, a component can be referred to by using the +component+ key in the configuration hash (this can be useful when overriding a layout of a child component):
+  #
+  #     component :tab_one # ...
+  #     component :tab_two # ...
+  #
+  #     def configure(c)
+  #       super
+  #       c.items = [
+  #         {component: :tab_one, title: "One"},
+  #         {component: :tab_two, title: "Two"}
+  #       ]
+  #     end
+  #
+  # == Lazily vs eagerly loaded components
+  #
+  # By default, if a component is not used in the layout, it is lazily loaded, which means that the code for this component is not loaded in the browser until the moment the component gets dynamically loaded by the JavaScript method `netzkeLoadComponent` (see {Netzke::Core::Javascript}). Referring a component in the layout (the `items` property) automatically makes it eagerly loaded. Sometimes it's desired to eagerly load a component without using it directly in the layout (an example can be a window that we need to render instantly without requesting the server). In this case an option `eager_loading` can be set to true:
+  #
+  #     component :eagerly_loaded_window do |c|
+  #       c.klass = SomeWindowComponent
+  #       c.eager_loading = true
+  #     end
+  #
+  # == Dynamic component loading
+  #
+  # Child components can be dynamically loaded by using client class' +netzkeLoadComponent+ method (see {javascript/ext.js}[https://github.com/netzke/netzke-core/blob/master/javascripts/ext.js] for inline documentation):
+  #
+  # == Excluded components
+  #
+  # You can make a child component inavailable for dynamic loading by using the +excluded+ option. When an excluded component is used in the layout, it will be skipped.
+  # This can be used for authorization.
+  module Composition
+    extend ActiveSupport::Concern
+
+    COMPONENT_METHOD_NAME = "%s_component"
+
+
+    included do
+
+      # Returns registered components
+      class_attribute :registered_components
+      self.registered_components = []
+
+      # @!method Foobar
+      # 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
+      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)
+          this.netzke_eval_js(js) if js.present?
+          this.netzke_eval_css(css) if css.present?
+
+          this.netzke_component_delivered(component.js_config);
+        else
+          this.netzke_component_delivery_failed(component_name: component_name, msg: "Couldn't load component '#{component_name}'")
+        end
+      end
+
+    end # included
+
+    module ClassMethods
+
+      # Declares a child (nested) component.
+      # @param name [Symbol] component name
+      # @param block [Proc] config block
+      # @example
+      #   component :users do |c|
+      #     c.klass = Netzke::Basepack::Grid
+      #     c.modul = "User"
+      #   end
+      def component(name, &block)
+        self.registered_components |= [name]
+
+        method_name = COMPONENT_METHOD_NAME % name
+        if block_given?
+          define_method(method_name, &block)
+        else
+          define_method(method_name) do |component_config|
+            component_config
+          end
+        end
+      end
+    end
+
+    # @return [Hash] component configs by name
+    def components
+      @components ||= self.class.registered_components.inject({}) do |out, name|
+        component_config = Netzke::Core::ComponentConfig.new(name)
+        send(COMPONENT_METHOD_NAME % name, component_config)
+        component_config.set_defaults!
+        if component_config.excluded
+          out.merge(name.to_sym => {excluded: true})
+        else
+          out.merge(name.to_sym => component_config)
+        end
+      end
+    end
+
+    # @return [Hash] configs of eagerly loaded components by name
+    def eagerly_loaded_components
+      @eagerly_loaded_components ||= components.select{|k,v| components_in_config.include?(k) || v[:eager_loading]}
+    end
+
+    # @return [Array<Symbol>] components (by name) referred in config (and thus, required to be instantiated)
+    def components_in_config
+      @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}.to_nifty_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)
+      raise ArgumentError, "No component '#{name.inspect}' defined for '#{self.js_id}'" if !name.present?
+
+      @component_instance_cache ||= {}
+      @component_instance_cache[name] ||= begin
+        composite = self
+        name.to_s.split('__').each do |cmp|
+          cmp = cmp.to_sym
+
+          component_config = composite.components[cmp]
+          raise ArgumentError, "No component '#{cmp}' defined for '#{composite.js_id}'" if component_config.nil? || component_config[:excluded]
+
+          klass = component_config[:klass]
+
+          instance_config = component_config.merge(:name => cmp)
+
+          composite = klass.new(instance_config, composite) # params: config, parent
+        end
+        composite
+      end
+    end
+
+    # @return [Array<Class>] All component classes that we depend on (used to render all necessary javascripts and stylesheets)
+    def dependency_classes
+      res = []
+
+      eagerly_loaded_components.keys.each do |aggr|
+        res += component_instance(aggr).dependency_classes
+      end
+
+      res += self.class.netzke_ancestors
+      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
+
+  protected
+
+    # During normalization of the config object, this method is being called with each item found (recursively) in there.
+    # For example, symbols representing nested child components get replaced with a proper config hash. Same goes for actions.
+    # Override to do any additional checks/enhancements. See, for example, +Netzke::Basepack::WrapLazyLoaded+.
+    # @return [Object] extended item
+    def extend_item(item)
+      # in a situation of action and component being equally named, action will take precedence
+
+      if item.is_a?(Symbol) && item_config = actions[item]
+        item = {netzke_action: item}
+      elsif item.is_a?(Symbol) && item_config = components[item]
+        item = {netzke_component: item}
+      end
+
+      item[:excluded] = true if item_config && item_config[:excluded]
+
+      if item.is_a?(Hash)
+        return nil if item[:excluded] # it'll get compacted away by Array#deep_map
+
+        # replace the `component` and `action` keys with `netzke_component` and `netzke_action`, which will be looked for at the JS side
+        item[:netzke_action] = item.delete(:action) if item[:action]
+        item[:netzke_component] = item.delete(:component) if item[:component]
+
+        @components_in_config << item[:netzke_component] if item[:netzke_component] && item[:eager_loading] != false
+      end
+
+      item
+    end
+
+  private
+
+    # We'll build a couple of useful instance variables here:
+    #
+    # +components_in_config+ - an array of components (by name) referred in items
+    # +normalized_config+ - a config that has all the config extensions applied
+    def normalize_config
+      @components_in_config = []
+      @normalized_config = config.dup.tap do |c|
+        c.each_pair do |k,v|
+          c.delete(k) if self.class.server_side_config_options.include?(k.to_sym)
+          c[k] = v.deep_map{|el| extend_item(el)} if v.is_a?(Array)
+        end
+      end
+    end
+
+    # @return [Hash] config with all placeholders (like child components referred by symbols) expanded
+    def normalized_config
+      # make sure we call normalize_config first
+      @normalized_config || (normalize_config || true) && @normalized_config
+    end
+
+  end
+end