rsence-pre 2.1.0.1.pre

data/lib/plugins/gui_plugin.rb

@@ -0,0 +1,160 @@
+##   RSence
+ #   Copyright 2009 Riassence Inc.
+ #   http://riassence.com/
+ #
+ #   You should have received a copy of the GNU General Public License along
+ #   with this software package. If not, contact licensing@riassence.com
+ ##
+
+
+module RSence
+  module Plugins
+    
+    # The CUIPlugin__ is actually available as +GUIPlugin+ from plugin bundle code using the {RSence::Plugins::GUIPlugin} class mimic method.
+    #
+    # GUIPlugin extends {Plugin__ Plugin} by automatically initializing an {GUIParser} instance as +@gui+.
+    #
+    # Read {Plugin__ Plugin} for usage of the API, {file:ExampleGuiPlugin Example GUIPlugin} for an example of use and {file:PluginBundles Plugin Bundles} for overall information about plugin bundle usage.
+    #
+    # * It implements automatic dependency loading based on the dependencies item in the YAML gui declaration.
+    # * It inits the gui automatically.
+    #
+    # = User Interface -related hooks:
+    # * {#init_ui +#init_ui+} -- Extend to implement logic when the {MainPlugin} plugin has started the client. The {GUIPlugin__ +GUIPlugin+} class extends this method to automatically load and initialize the user interface from a +GUITree+ data structure defined in the +gui/main.yaml+ document in the bundle directory.
+    # * {#gui_params +#gui_params+} -- Extend to define your own params for the gui data.
+    #
+    class GUIPlugin__ < Plugin__
+      
+      # @private Class type identifier for the PluginManager.
+      # @return [:GUIPlugin]
+      def self.bundle_type; :GUIPlugin; end
+      
+      
+      # @private Placeholder for actual gui yaml file.
+      @@default_yaml_src = <<-END
+type: GUITree
+version: 0.6
+
+class: RSence.GUIApp
+options:
+  label: "Dummy Application"
+
+      END
+      
+      # In addition to {Plugin__#init Plugin#init}, also automatically initializes a {GUIParser} instance as +@gui+
+      #
+      # @return [nil]
+      def init
+        super
+        yaml_src = file_read( "gui/#{@name}.yaml" )
+        yaml_src = file_read( "gui/main.yaml" ) unless yaml_src
+        yaml_src = @@default_yaml_src unless yaml_src
+        @gui = GUIParser.new( self, yaml_src )
+        @client_pkgs = false
+      end
+  
+      # Extend this method to return custom params to {GUIParser#init}.
+      #
+      # Called from {#init_ui}.
+      #
+      # By default assigns the session values as :values to use for +bind: :values.my_value_name+ in the YAML GUI file for client-side value bindings.
+      #
+      # @param [Message] msg The message is supplied by the system.
+      # 
+      # @return [Hash] Parameters for {GUIParser#init @gui#init}
+      #
+      # @example To provide extra parameters, do this:
+      #   def gui_params( msg )
+      #     params = super
+      #     params[:extra] = {
+      #       :foo => "Foo",       # use in the GUITree as :extra.foo
+      #       :num => 124334,      # use in the GUITree as :extra.num
+      #       :bar => {
+      #         :barbar => "Bar"   # use in the GUITree as :extra.bar.barbar
+      #       }
+      #       :arr => [1,2,4,8]    # use in the GUITree as :extra.arr
+      #     }
+      #     params[:more] = "More" # use in the GUITree as :more
+      #     return params
+      #   end
+      #
+      def gui_params( msg )
+        { :values => @gui.values( get_ses( msg ) ) }
+      end
+      
+      # @private Method that implements +client_pkgs.yaml+ loading
+      def install_client_pkgs
+        if @client_pkgs
+          warn "install_client_pkgs: called with @client_pkgs defined; returning"
+          return
+        end
+        @client_pkgs = yaml_read( 'client_pkgs.yaml' )
+        if @client_pkgs
+          if @client_pkgs.has_key?(:src_dirs)
+            @client_pkgs[:src_dirs].each do |src_dir|
+              src_dir = bundle_path( src_dir[2..-1] ) if src_dir.start_with?('./')
+              @plugins.client_pkg.add_src_dir( src_dir )
+            end
+          end
+          @plugins.client_pkg.add_packages(       @client_pkgs[:packages      ] ) if @client_pkgs.has_key?(:packages      )
+          @plugins.client_pkg.add_themes(         @client_pkgs[:theme_names   ] ) if @client_pkgs.has_key?(:theme_names   )
+          @plugins.client_pkg.add_gfx_formats(    @client_pkgs[:gfx_formats   ] ) if @client_pkgs.has_key?(:gfx_formats   )
+          @plugins.client_pkg.add_reserved_names( @client_pkgs[:reserved_names] ) if @client_pkgs.has_key?(:reserved_names)
+          @plugins.client_pkg.rebuild_client
+        end
+      end
+      
+      # @private Method that implements +client_pkgs.yaml+ unloading
+      def uninstall_client_pkgs
+        if not @client_pkgs
+          warn "uninstall_client_pkgs: called without @client_pkgs defined"
+        else
+          if @client_pkgs.has_key?(:src_dirs)
+            @client_pkgs[:src_dirs].each do |src_dir|
+              src_dir = bundle_path( src_dir[2..-1] ) if src_dir.start_with?('./')
+              @plugins.client_pkg.del_src_dir( src_dir )
+            end
+          end
+          @plugins.client_pkg.del_reserved_names( @client_pkgs[:reserved_names] ) if @client_pkgs.has_key?(:reserved_names)
+          @plugins.client_pkg.del_gfx_formats(    @client_pkgs[:gfx_formats   ] ) if @client_pkgs.has_key?(:gfx_formats   )
+          @plugins.client_pkg.del_themes(         @client_pkgs[:theme_names   ] ) if @client_pkgs.has_key?(:theme_names   )
+          @plugins.client_pkg.del_packages(       @client_pkgs[:packages].keys  ) if @client_pkgs.has_key?(:packages      )
+          @plugins.client_pkg.rebuild_client
+        end
+        @client_pkgs = false
+      end
+      
+      # @private calls install_client_pkgs, if a 'client_pkgs.yaml' file is found
+      def open
+        super
+        install_client_pkgs if File.exist? bundle_path( 'client_pkgs.yaml' )
+      end
+      
+      # @private calls uninstall_client_pkgs, if a 'client_pkgs.yaml' file was loaded
+      def close
+        super
+        uninstall_client_pkgs if @client_pkgs
+      end
+      
+      # @private Sends gui specification to the main plugin
+      def spec_ui( msg )
+        # TODO
+      end
+      
+      # Automatically inits the UI using {GUIParser#init}
+      #
+      # @param [Message] msg The message is supplied by the system.
+      #
+      # @return [nil]
+      def init_ui( msg )
+        @gui.init( msg, gui_params( msg ) )
+      end
+      
+      # @private Automatically kills the UI using {GUIParser#kill}
+      def kill_ui( msg )
+        @gui.kill( msg )
+      end
+      
+    end
+  end
+end

data/lib/plugins/guiparser.rb

@@ -0,0 +1,123 @@
+##   RSence
+ #   Copyright 2009 Riassence Inc.
+ #   http://riassence.com/
+ #
+ #   You should have received a copy of the GNU General Public License along
+ #   with this software package. If not, contact licensing@riassence.com
+ ##
+
+
+module RSence
+  
+  
+  module Plugins
+    
+    
+    # This class automatically loads a YAML file from "gui" subdirectory of a plugin.
+    #
+    # Extend your plugin from the {GUIPlugin__ GUIPlugin} class instead of the Plugin class to make this work automatically.
+    #
+    # @example Initialize like this from inside a plugin method. This will load the "gui/my_gui.yaml" file.
+    #   gui = GUIParser.new( self, 'my_gui' )
+    #
+    # @example To make the client render the contents of the yaml do this:
+    #   ses = get_ses( msg )
+    #   params = { :values => @gui.values( ses ) }
+    #   gui.init( msg, params )
+    class GUIParser
+      
+      # include ::RSence
+      
+      # Use this method to send the client all commands required to construct the GUI Tree using JSONRenderer.
+      # @param [Message] msg The +Message+ instance +msg+ used all over the place.
+      # @param [Hash] params Containing all parameters referred from the YAML file, see: {GUIPlugin__#gui_params GUIPlugin#gui_params}
+      def init( msg, params )
+        gui_data = YAML.load( @yaml_src )
+        parse_gui( gui_data, params )
+        if gui_data.has_key?('dependencies')
+          @parent.include_js( msg, gui_data['dependencies'] )
+          gui_data.delete('dependencies')
+        end
+        if gui_data.has_key?('include')
+          gui_data['include'].each do | js_file |
+            js_src = @parent.read_js_once( msg, js_file )
+            msg.reply( js_src )
+          end
+        end
+        gui_name = @parent.name
+        json_data = JSON.dump( gui_data )
+        msg.reply( "JSONRenderer.nu(#{json_data});", true )
+      end
+      
+      # Use this method to extract all the value id's of the +ses+ hash.
+      def values( ses )
+        ids = {}
+        ses.each do | key, value |
+          if value.class == HValue
+            ids[ key ] = value.value_id
+          end
+        end
+        return ids
+      end
+      
+    private
+      
+      def json_fun( value )
+        JSON.parse( "[#{value}]" ).first
+      end
+      
+      # Parses the gui data using params. Called from +init+.
+      def parse_gui( gui_data, params )
+        data_class = gui_data.class
+        if data_class == Array
+          gui_data.each_with_index do | item, i |
+            gui_data[i] = parse_gui( item, params )
+          end
+        elsif data_class == Hash
+          gui_data.each do | key, value |
+            gui_data[key] = parse_gui( value, params )
+          end
+        elsif data_class == Symbol
+          sym_str = gui_data.to_s
+          if sym_str.include? '.'
+            sym_arr = sym_str.split('.')
+          else
+            sym_arr = [ sym_str ]
+          end
+          return get_params( sym_arr, params )
+        elsif data_class == String and gui_data.strip.start_with?('function(')
+          return @parent.plugins[:client_pkg].squeeze( "a="+json_fun( gui_data.to_json ) )[2..-1]
+        end
+        return gui_data
+      end
+      
+      # Searches the params hash for parameters whenever encountered a Symbol in the YAML.
+      def get_params( params_path, params )
+        item = params_path.shift
+        if params.class == Hash
+          has_str = params.has_key?( item )
+          has_sym = params.has_key?( item.to_sym )
+          item = item.to_sym if has_sym
+          if has_str or has_sym
+            if params_path.size == 0
+              return params[item]
+            else
+              return get_params( params_path, params[ item ] )
+            end
+          end
+        end
+        return ''
+      end
+      
+      # Loads the YAML file.
+      # = Parameters
+      # +parent+::    The Plugin instance called from, use +self+ when constructing in a Plugin method.
+      # +yaml_src+::  The YAML source template for the GUI
+      def initialize( parent, yaml_src )
+        @parent = parent
+        @yaml_src = yaml_src
+      end
+      
+    end
+  end
+end