RubyGems - winton-rails_widget - Versions diffs - 1.0.2 → 1.1 - Mend

winton-rails_widget 1.0.2 → 1.1

Files changed (7) hide show

data/README.markdown +20 -5
data/lib/rails_widget.rb +99 -3
data/lib/rails_widget/assets.rb +196 -86
data/lib/rails_widget/widget.rb +148 -227
data/lib/rails_widget/widgets.rb +188 -0
metadata +6 -6
data/tasks/rails_widget.rake +0 -31

data/README.markdown CHANGED Viewed

@@ -1,8 +1,23 @@
-Rails Widget
-============
+RailsWidget
+===========
-A mini-framework for your client side Rails assets.
+Allows you to group your client-side assets into distributable "widgets"
-**This plugin is very beta. More details coming soon.**
+* Attach assets and render partials with a single <tt>widget</tt> call
+* Configure widgets via an <tt>options.rb</tt> file
+* Supported assets: flash, images, partials, javascripts, stylesheets, and textarea templates
-##### Copyright (c) 2008 [Winton Welsh](mailto:mail@wintoni.us), released under the MIT license
+Install
+-------
+	script/plugin install git://github.com/winton/rails_widget.git
+Documentation
+--------------
+[RDoc](http://wintoni.us/rails_widget) for more details.
+##### Copyright &copy; 2008 [Winton Welsh](mailto:mail@wintoni.us), released under the MIT license

data/lib/rails_widget.rb CHANGED Viewed

@@ -1,7 +1,103 @@
+# RailsWidget allows you to group your client-side assets into distributable "widgets"
+#
+# * Attach assets and render partials with a single <tt>widget</tt> call
+# * Configure widgets via an <tt>options.rb</tt> file
+# * Supports flash, images, javascripts, partials, stylesheets, and textarea templates
+#
+# == Example
+# === What is a widget?
+# Each directory in <tt>app/widgets</tt> is considered a widget. Let's make a widget called <tt>alert</tt>.
+#
+#   app/
+#     widgets/
+#       alert/
+#         options.rb
+#         flash/
+#         images/
+#         javascripts/
+#           alert.js
+#           init.js
+#         partials/
+#           _init.html.erb
+#         stylesheets/
+#           init.css
+#           style.css
+#         templates/
+#
+# <b>Init</b> files are rendered directly into the layout (inline, dynamically generated).
+#
+# ==== options.rb
+#   { :id => 'alert', :message => 'Hello world!', :color => 'red' }
+#
+# ==== javascripts/alert.js
+#   function alertWidget(options) {
+#     alert(options.message);
+#   }
+#
+# ==== javascripts/init.js
+#   alertWidget(<%= options.to_json %>);
+#
+#
+# ==== partials/_init.html.erb
+#   <div id="<%= id %>" class="alert">
+#     You just got alerted.
+#   </div>
+#
+# ==== stylesheets/init.css
+#   #<%= id %> { color:<%= color %>; }
+#
+# ==== stylesheets/style.css
+#   .alert { font-size:18px; }
+#
+# === Layout view
+#   <html>
+#     <head>
+#       <%= javascripts %>
+#       <%= stylesheets %>
+#     </head>
+#     <body>
+#       <%= yield %>
+#     </body>
+#   </html>
+#
+# === Action view
+#   <%= widget :alert, :id => 'alert1', :color => 'blue' %>
+#   <%= widget :alert, :id => 'alert2' %>
+#
+# === Resulting HTML
+#   <html>
+#     <head>
+#       <script src="/javascripts/widgets/alert/alert.js?1220593492" type="text/javascript"></script>
+#       <script type='text/javascript'>
+#         alertWidget({ id: 'alert', message: 'Hello world!', color: 'red' });
+#       </script>
+#       <link href="/stylesheets/widgets/alert/style.css?1220593492" media="screen" rel="stylesheet" type="text/css" />
+#       <style type="text/css">
+#         #alert1 { color:blue; }
+#         #alert2 { color:red; }
+#       </style>
+#     </head>
+#     <body>
+#       <div id="alert1" class="alert">
+#         You just got alerted.
+#       </div>
+#       <div id="alert2" class="alert">
+#         You just got alerted.
+#       </div>
+#     </body>
+#   </html>
+#
+# == Inheritance
+#
+module RailsWidget
+end
 Dir[File.expand_path('*/*.rb', File.dirname(__FILE__))].each do |f|
   require [ File.dirname(f), File.basename(f, '.rb') ].join('/')
 end
-ActionView::Base.send :include, WidgetHelpers
-ActionController::Base.send :include, WidgetHelpers
-ActionController::Base.view_paths += [ RAILS_ROOT + '/app/widgets' ]
+ActionView::Base.send :include, RailsWidget
+ActionController::Base.send :include, RailsWidget
+ActionController::Base.view_paths += [ RAILS_ROOT + '/app/widgets' ]
+# :main:RailsWidget

data/lib/rails_widget/assets.rb CHANGED Viewed

@@ -1,114 +1,224 @@
-module WidgetHelpers
-  def default_javascript
-    "#{params[:controller]}/#{params[:action]}"
-  end
-  def default_stylesheet
-    "#{params[:controller]}/#{params[:action]}"
-  end
+module RailsWidget
+  # Adds or renders javascript assets based on whether parameters are given or not.
+  #
+  # ==== Layout view
+  #   <html>
+  #     <head>
+  #       <%= javascripts %>
+  #     </head>
+  #     <%= yield %>
+  #   </html>
+  #
+  # ==== Action view
+  #   <% javascripts 'script1', 'script2' do -%>
+  #     alert('Hello world!');
+  #   <% end -%>
+  #   Content goes here.
+  #
+  # ==== Resulting HTML
+  #   <html>
+  #     <head>
+  #       <script src="/javascripts/script1.js?1220593492" type="text/javascript"></script>
+  #       <script src="/javascripts/script2.js?1220593492" type="text/javascript"></script>
+  #       <script type='text/javascript'>
+  #         alert('Hello world!');
+  #       </script>
+  #     </head>
+  #     Content goes here.
+  #   </html>
+  #
+  # Calling <tt>javascripts</tt> with path parameters or a script block will store the asset for later rendering.
+  #
+  # Calling <tt>javascripts</tt> without parameters renders the assets in the order they were added.
+  #
+  # The method accepts all options supported by <tt>javascript_include_tag</tt>.
+  #
   def javascripts(*paths, &block)
-    add_assets :javascripts, paths, &block
+    @assets ||= Assets.new binding, controller, logger
+    @assets.javascripts *paths, &block
   end
+  # Adds or renders stylesheet assets based on whether parameters are given or not.
+  #
+  # ==== Layout example
+  #   <html>
+  #     <head>
+  #       <%= stylesheets %>
+  #     </head>
+  #     <%= yield %>
+  #   </html>
+  #
+  # ==== Action example
+  #   <% stylesheets 'style1', 'style2' -%>
+  #   Content goes here.
+  #
+  # ==== Result
+  #   <html>
+  #     <head>
+  #       <link href="/stylesheets/style1.css?1224923418" media="screen" rel="stylesheet" type="text/css" />
+  #       <link href="/stylesheets/style2.css?1224923418" media="screen" rel="stylesheet" type="text/css" />
+  #     </head>
+  #     Content goes here.
+  #   </html>
+  #
+  # Calling <tt>stylesheets</tt> with path parameters will store the asset for later rendering.
+  #
+  # Calling <tt>stylesheets</tt> without parameters renders the assets in the order they were added.
+  #
+  # The method accepts all options supported by <tt>stylesheet_link_tag</tt>.
+  #
   def stylesheets(*paths, &block)
-    add_assets :stylesheets, paths, &block
+    @assets ||= Assets.new binding, controller, logger
+    @assets.stylesheets *paths, &block
   end
-  def templates(*paths, &block)
-    paths.each do |path|
-      add_assets :templates, path, &block
-    end
-    add_assets(:templates, paths, &block) if paths.empty?
-  end
-  def textarea_template(id, path=nil, locals={})
-    controller.render_to_string(:partial => 'app_helpers/template/textarea', :locals => {
-      :id => id,
-      :body => controller.render_to_string(:partial => path, :locals => locals)
-    })
+  # Adds or renders textarea-based templates based on whether parameters are given or not.
+  #
+  # Use this with something like PURE <http://beebole.com/pure> or TrimPath's JST <http://trimpath.com>.
+  #
+  # ==== Layout example
+  #   <html>
+  #     <%= yield %>
+  #     <%= templates %>
+  #   </html>
+  #
+  # ==== Action example
+  #   <% templates :id => 'myid', :partial => 'some_action/partial', :locals => { :x => 'Hello world' } -%>
+  #   <% templates do -%>
+  #     Template goes here.
+  #   <% end -%>
+  #   Content goes here.
+  #
+  # ==== Partial example (<tt>some_action/partial</tt>)
+  #   <%= x %>!
+  #
+  # ==== Result
+  #   <html>
+  #     Content goes here.
+  #     <textarea id='template_myid' style='display:none'>
+  #       Hello world!
+  #     </textarea>
+  #     <textarea id='template' style='display:none'>
+  #       Template goes here.
+  #     </textarea>
+  #   </html>
+  #
+  # Calling <tt>templates</tt> with path parameters or a block will store the asset for later rendering.
+  #
+  # Calling <tt>templates</tt> without parameters renders the assets in the order they were added.
+  #
+  def templates(*options, &block)
+    @assets ||= Assets.new binding, controller, logger
+    @assets.templates *options, &block
   end
-private
-  def add_assets(type, paths, &block)
-    options = paths.extract_options!
-    paths.flatten! unless type == :templates
+  class Assets
+    attr :assets, true
-    @assets ||= {}
-    @assets[type] ||= []
-    @layout_assets ||= {}
-    @layout_assets[type] ||= []
+    # Used for eval access
+    attr :block,   true
+    attr :params,  true
+    attr :options, true
-    paths = nil if paths.empty?
+    def initialize(bind, controller, logger)
+      @assets = {}
+      @bind = bind
+      @controller = controller
+      @logger = logger
+    end
-    if options[:layout]
-      options.delete :layout
-      paths.push(options) if paths
-      @layout_assets[type].push(paths          ) if paths
-      @layout_assets[type].push(capture(&block)) if block
-    else
-      paths.push(options) if paths
-      @assets[type].push(paths          ) if paths
-      @assets[type].push(capture(&block)) if block
+    def javascripts(*params, &block)
+      add_assets :javascripts, params, &block
+    end
+    def stylesheets(*params, &block)
+      add_assets :stylesheets, params, &block
+    end
+    def templates(*params, &block)
+      add_assets :templates, params, &block
     end
-    if !paths && !block
-      #logger.info type.inspect
-      #logger.info 'LAYOUT ' + @layout_assets[type].inspect
-      #logger.info @assets[type].inspect
-      @assets[type] = @layout_assets[type] + @assets[type]
-      @assets[type].uniq!
-      remove_dups @assets[type]
-      @assets[type].collect! { |a| a[0].respond_to?(:keys) ? nil : a }
-      @assets[type].compact!
-      js = []
-      assets = @assets[type].collect do |item|
-        if item.respond_to?(:pop)
+    private
+    def add_assets(type, params, &block)
+      options = params.extract_options! unless type == :templates
+      capture = block_to_string &block
+      asset   = delete_if_empty(:options => options, :params => params, :capture => capture)
+      if asset.empty?
+        remove_dups :javascripts, :params
+        remove_dups :stylesheets, :params, :capture
+        remove_dups :templates,   :params, :capture
+        captures = []
+        tags     = []
+        @assets[type].each do |item|
+          @capture = item[:capture]
+          @params  = item[:params]
           case type
           when :javascripts
-            javascript_include_tag *item
+            captures.push(@capture) if @capture
+            tags.push(eval("javascript_include_tag *[ @assets.params, @assets.options ].flatten.compact", @bind)) if @params
           when :stylesheets
-            stylesheet_link_tag *item
+            captures.push(@capture) if @capture
+            tags.push(eval("stylesheet_link_tag    *[ @assets.params, @assets.options ].flatten.compact", @bind)) if @params
           when :templates
-            textarea_template item[0], item[1], item[2]
-          end + "\n"
-        else
-          case type
-          when :javascripts
-            js.push(item) unless item.blank?
-            nil
-          else
-            item
+            captures.push(textarea_template(@params.pop.merge(:body => @capture))) if @capture
+            @params.each do |options|
+              captures << textarea_template(options)
+            end
           end
         end
-      end.compact
-      if type == :javascripts
-        assets.join + "<script type='text/javascript'>\n#{js.join "\n"}\n</script>"
+        case type
+        when :javascripts
+          tags.join("\n") + "\n<script type='text/javascript'>\n#{captures.join "\n"}\n</script>"
+        when :stylesheets
+          tags.join("\n") + "\n<style type='text/css'>\n#{captures.join "\n"}\n</style>"
+        when :templates
+          captures.uniq.join "\n"
+        end
       else
-        assets.join
+        @assets[type] ||= []
+        @assets[type].push asset
       end
     end
-  end
-  def remove_dups(arr, list=[])
-    arr.dup.each do |a|
-      if a.respond_to?(:keys)
-        next
-      elsif a.respond_to?(:pop)
-        remove_dups a, list
-      else
-        if list.include?(a) || a.blank?
-          arr.delete_at arr.rindex(a)
-        else
-          list << a
+    def block_to_string(&block)
+      return nil unless block
+      @block = block
+      eval "capture(&@assets.block)", @bind
+    end
+    def delete_if_empty(hash)
+      list = []
+      hash.each { |key, value| list.push(key) if !value || value.empty? || value.blank? }
+      list.each { |key|        hash.delete key }
+      hash
+    end
+    def remove_dups(asset_type, *types)
+      asset = @assets[asset_type]
+      types.each do |type|
+        list = []
+        asset.each do |a|
+          if list.include?(a[type])
+            a.delete type
+          else
+            list << a[type]
+          end
         end
+      end if asset
+    end
+    def textarea_template(options)
+      id = 'template' + (options[:id] ? "_#{options[:id]}" : '')
+      if options[:body]
+        body = options[:body]
+      elsif options[:partial]
+        body = @controller.render_to_string :partial => options[:partial], :locals => options[:locals]
       end
+      return nil unless body
+      "<textarea id='#{id}' style='display:none'>\n#{body}\n</textarea>"
     end
   end
 end

data/lib/rails_widget/widget.rb CHANGED Viewed

@@ -1,248 +1,169 @@
-module WidgetHelpers
+module RailsWidget
-  def widget_base
-    @layout_happened = true
-    require_widget ''
-    render_widget ''
-  end
-  def render_widget(*path)
-    widgets, options = widget_instances path
-    widgets.collect do |w|
-      # we want widgets rendered from the partial to include first
-      partial = w.render_init :partials, options
-      js = w.render_init :js, options
-      if options[:include_js] && js && !js.empty?
-        partial + "\n<script type='text/javascript'>\n#{js}\n</script>"
-      else
-        javascripts *(@layout_happened ? [ :layout => true ] : []) do
-          js
-        end
-        partial
-      end
-    end
-  end
-  def require_widget(*path)
-    widgets, options = widget_instances path
-    widgets.each do |w|
-      w.copy_assets
-      js  = w.helper_targets :javascripts
-      css = w.helper_targets :stylesheets
-      javascripts *(js  + [ :cache => w.cache, :layout => @layout_happened ]) unless js.empty?
-      stylesheets *(css + [ :cache => w.cache, :layout => @layout_happened ]) unless css.empty?
-      templates   *(w.assets[:templates].collect do |t|
-        [ File.basename(t), t, options.merge(:options => options) ]
-      end) unless w.assets[:templates].empty?
-    end
-  end
-  def widget_flash_path(*path)
-    flash = path.pop
-    "/flash/widgets/#{path.join('/')}/#{flash}"
-  end
-  def widget_image(*path)
-    options = path.extract_options!
-    image = path.pop
-    image_tag "widgets/#{path.join('/')}/#{image}", options
-  end
-  def widget_image_path(*path)
-    image = path.pop
-    "/images/widgets/#{path.join('/')}/#{image}"
-  end
-  def widget_partial(*path)
-    options = path.extract_options!
-    partial = path.pop
-    path << options
-    widgets, options = widget_instances path
-    options = {
-      :locals  => options.merge(:options => options),
-      :partial => "#{path.join('/')}/partials/#{partial}"
-    }
-    render options
-  end
-  def widget_instances(path)
-    @widgets ||= Widgets.new binding, controller, logger
-    options = path.extract_options!
-    @widgets.build path, options
-  end
-  class Widgets
-    attr :widgets, true
-    def initialize(bind, controller, logger)
-      @bind       = bind
+  # Stores information about a widget and renders assets to <tt>public/</tt> when necessary.
+  #
+  class Widget
+    attr :assets,  true # Paths for each ASSET_TYPE
+    attr :cache,   true # Cache path for Rails asset helpers
+    attr :options, true # Options hash from options.rb
+    attr :path,    true # Path to widget
+    ASSET_TYPES = [ :flash, :images, :javascripts, :stylesheets, :templates, :init_css, :init_js, :init_partials ]
+    # Calls <tt>update_options</tt> and <tt>update_asset</tt> for each <tt>ASSET_TYPE</tt>.
+    #
+    def initialize(path, bind, controller, logger)
+      @path = path
+      @bind = bind
       @controller = controller
-      @logger     = logger
-      @widgets    = {}
-    end
-    def build(path, options)
-      opts = {}
-      #@logger.info 'RELATED_PATHS ' + related_paths(path).inspect
-      widgets = related_paths(path).collect do |r|
-        @widgets[r] ||= Assets.new r, @bind, @controller, @logger
-        opts.merge! @widgets[r].options
-        @widgets[r]
+      @logger = logger
+      @assets = {}
+      @options  = {}
+      @rendered = {}
+      @targeted = {}
+      update_options
+      ASSET_TYPES.each do |type|
+        update_asset type
       end
-      [ widgets, opts.merge(options) ]
     end
-    private
-    def related_paths(paths)
-      ordered = []
-      last = paths.length - 1
-      paths.each_index do |x|
-        if x != 0 && File.exists?("app/widgets/#{paths[x]}")
-          ordered << related_paths(paths[x..last])
-        end
-        path = paths[0..x].join '/'
-        if File.exists?("app/widgets/#{path}")
-          ordered << path
-        end
-      end
-      ordered.flatten
+    # Returns a cache path suitable for Rails asset helpers.
+    #
+    def cache
+      'cache/' + (@path.empty? ? 'base' : @path.gsub('/', '_'))
     end
-    class Assets
-      attr :assets,  true
-      attr :cache,   true
-      attr :options, true
-      attr :path,    true
-      ASSET_TYPES = [ :flash, :images, :javascripts, :stylesheets, :templates, :init_js, :init_partials ]
-      def initialize(path, bind, controller, logger)
-        @bind     = bind
-        @controller = controller
-        @logger   = logger
-        @assets   = {}
-        @options  = {}
-        @rendered = {}
-        @targeted = {}
-        @path     = path
-        @cache    = cache_name
-        update_options
-        ASSET_TYPES.each do |type|
-          update_asset type
-        end
-      end
-      def copy_assets
-        @assets.each do |key, value|
-          from, to = to_path key
-          value.each do |asset|
-            base = File.basename asset
-            f = [ from, base ].join '/'
-            t = [ to,   base ].join '/'
-            t.gsub!('/stylesheets/', '/stylesheets/sass/') if t.include?('.sass')
-            next unless needs_update?(f, t)
-            case key
-            when :flash, :images
-              FileUtils.mkdir_p to
-              FileUtils.copy f, t
-            when :javascripts, :stylesheets
-              FileUtils.mkdir_p File.dirname(t)
-              File.open t, 'w' do |file|
-                file.write @controller.render_to_string(:file => f, :locals => @options.merge(:options => @options))
-              end
+    # Copies widget images to <tt>public/images/widgets</tt>.
+    #
+    # Copies widget flash files to <tt>public/flash/widgets</tt>.
+    #
+    # Renders javascripts to <tt>public/javascripts/widgets</tt>.
+    #
+    # Renders stylesheets to <tt>public/stylesheets/widgets</tt>.
+    #
+    def copy_assets
+      @assets.each do |key, value|
+        from, to = to_path key
+        value.each do |asset|
+          base = File.basename asset
+          f = [ from, base ].join '/'
+          t = [ to,   base ].join '/'
+          t.gsub!('/stylesheets/', '/stylesheets/sass/') if t.include?('.sass')
+          next unless needs_update?(f, t)
+          case key
+          when :flash, :images
+            FileUtils.mkdir_p to
+            FileUtils.cp_r f, t
+          when :javascripts, :stylesheets
+            FileUtils.mkdir_p File.dirname(t)
+            File.open t, 'w' do |file|
+              file.write @controller.render_to_string(:file => f, :locals => @options.merge(:options => @options))
             end
           end
         end
       end
-      def helper_targets(type)
-        return [] if @targeted[type]
-        @targeted[type] = true
-        from, to = to_path type
-        case type
-        when :javascripts
-          @assets[type].collect do |asset|
-            [ to.split('javascripts/')[1], File.basename(asset, '.js') ].join '/'
-          end
-        when :stylesheets
-          @assets[type].collect do |asset|
-            sass = asset.include? '.sass'
-            [ to.split('stylesheets/')[1], File.basename(asset, sass ? '.sass' : '.css') ].join '/'
-          end
-        else @assets[type]
+    end
+    # Returns asset paths to be included via the Assets helpers for a particular <tt>ASSET_TYPE</tt>.
+    #
+    # See <tt>add_static_assets (Widgets)</tt>.
+    #
+    def asset_paths(type)
+      return [] if @targeted[type]
+      @targeted[type] = true
+      from, to = to_path type
+      case type
+      when :javascripts
+        @assets[type].collect do |asset|
+          [ to.split('javascripts/')[1], File.basename(asset, '.js') ].join '/'
         end
-      end
-      def render_init(type, options=@options)
-        @rendered[type] ||= {}
-        return nil if @rendered[type][options[:id]]
-        @rendered[type][options[:id]] = true
-        @assets["init_#{type}".intern].collect do |f|
-          @controller.render_to_string :file => f, :locals => options.merge(:options => options)
-        end.join("\n")
-      end
-      private
-      def cache_name
-        'cache/' + (@path.empty? ? 'base' : @path.gsub('/', '_'))
-      end
-      def filename_to_partial(file, remove=nil)
-        base = File.basename file
-        dir  = File.dirname file
-        file = [ dir, (base[0..0] == '_' ? base[1..-1] : base ).split('.')[0..-2].join('.') ].join '/'
-        if remove
-          if remove.respond_to?(:pop)
-            remove.each { |r| file.gsub! r, '' }
-          else
-            file.gsub! remove, ''
-          end
+      when :stylesheets
+        @assets[type].collect do |asset|
+          sass = asset.include? '.sass'
+          [ to.split('stylesheets/')[1], File.basename(asset, sass ? '.sass' : '.css') ].join '/'
         end
-        file
+      else @assets[type]
       end
+    end
+    # Renders and returns the init file for a particular <tt>ASSET_TYPE</tt>.
+    #
+    # The render will not occur if it has already happened with the same <tt>:id</tt> option.
+    #
+    def render_init(type, options=@options)
+      @rendered[type] ||= {}
+      #return nil if @rendered[type][options[:id]]
+      @rendered[type][options[:id]] = true
-      def needs_update?(from, to)
-        File.exists?(to) ? File.mtime(from) > File.mtime(to) : true
-      end
-      def to_path(type, path=@path)
-        slash = path.empty? ? '' : '/'
-        base  = "app/widgets#{slash}#{path}"
-        case type
-        when :base:          base
-        when :init_js:       base + '/javascripts/init'
-        when :init_partials: base + '/partials/_init'
-        when :options:       base + '/options.rb'
-        when :templates:     base + '/templates'
-        when :flash:       [ base + '/flash',       "public/flash/widgets"       + slash + path ]
-        when :images:      [ base + '/images',      "public/images/widgets"      + slash + path ]
-        when :javascripts: [ base + '/javascripts', "public/javascripts/widgets" + slash + path ]
-        when :stylesheets: [ base + '/stylesheets', "public/stylesheets/widgets" + slash + path ]
+      @assets["init_#{type}".intern].collect do |f|
+        @controller.render_to_string :file => f, :locals => options.merge(:options => options)
+      end.join("\n")
+    end
+    private
+    # Converts a full file name to a path that can be used by <tt>render :partial</tt>.
+    #
+    def filename_to_partial(file, remove=nil) #:doc:
+      base = File.basename file
+      dir  = File.dirname file
+      file = [ dir, (base[0..0] == '_' ? base[1..-1] : base ).split('.')[0..-2].join('.') ].join '/'
+      if remove
+        if remove.respond_to?(:pop)
+          remove.each { |r| file.gsub! r, '' }
+        else
+          file.gsub! remove, ''
         end
       end
-      def update_asset(type)
-        @assets[type] ||= []
-        from = to_path type
-        from = from[0] if from.respond_to?(:pop)
-        from = File.directory?(from) ? "#{from}/*" : "#{from}.*"
-        Dir[from].sort.each do |f|
-          next if type == :javascripts && File.basename(f) == 'init.js'
-          @assets[type] << (type == :templates ? filename_to_partial(f, 'app/widgets/') : f)
-        end
+      file
+    end
+    # Returns true if <tt>from</tt> is newer than <tt>to</tt> or <tt>to</tt> does not exist.
+    #
+    def needs_update?(from, to) #:doc:
+      File.exists?(to) ? File.mtime(from) > File.mtime(to) : true
+    end
+    # Returns a full path for the specified <tt>ASSET_TYPE</tt>.
+    #
+    def to_path(type, path=@path) #:doc:
+      slash = path.empty? ? '' : '/'
+      base  = "app/widgets#{slash}#{path}"
+      case type
+      when :base:          base
+      when :init_css:      base + '/stylesheets/init'
+      when :init_js:       base + '/javascripts/init'
+      when :init_partials: base + '/partials/_init'
+      when :options:       base + '/options.rb'
+      when :templates:     base + '/templates'
+      when :flash:       [ base + '/flash',       "public/flash/widgets"       + slash + path ]
+      when :images:      [ base + '/images',      "public/images/widgets"      + slash + path ]
+      when :javascripts: [ base + '/javascripts', "public/javascripts/widgets" + slash + path ]
+      when :stylesheets: [ base + '/stylesheets', "public/stylesheets/widgets" + slash + path ]
       end
-      def update_options(path=@path, empty=false)
-        options  = to_path :options, path
-        @options = (File.exists?(options) ? eval(File.read(options), @bind) : {}).merge(@options)
-        path = path.split('/')[0..-2]
-        # empty allows us to retrieve base directory's options
-        update_options(path.join('/'), path.empty?) unless empty
+    end
+    # Updates <tt>@assets[type]</tt> with an array of paths for the specified <tt>ASSET_TYPE</tt>.
+    #
+    def update_asset(type) #:doc:
+      @assets[type] ||= []
+      from = to_path type
+      from = from[0] if from.respond_to?(:pop)
+      from = File.directory?(from) ? "#{from}/*" : "#{from}.*"
+      Dir[from].sort.each do |f|
+        next if (type == :javascripts || type == :stylesheets) && File.basename(f)[0..3] == 'init'
+        @assets[type] << (type == :templates ? filename_to_partial(f, 'app/widgets/') : f)
       end
     end
+    # Assigns <tt>@options</tt> to the hash in <tt>options.rb</tt> (if it exists).
+    #
+    def update_options(path=@path, empty=false) #:doc:
+      path = to_path :options, path
+      @options = File.exists?(path) ? eval(File.read(path), @bind) : {}
+    end
   end
 end

data/lib/rails_widget/widgets.rb ADDED Viewed

@@ -0,0 +1,188 @@
+module RailsWidget
+  # See <tt>RailsWidget</tt>.
+  #
+  def widget(*path)
+    @assets  ||= Assets.new  binding, controller, logger
+    @widgets ||= Widgets.new @assets, binding, controller, logger
+    options = path.extract_options!
+    @widgets.build path, options
+  end
+  # Returns a path for a flash asset.
+  #
+  # ==== Example
+  #   <%= flash_path :some, :widget, 'flash.swf' %>
+  #   # => 'app/widgets/some/widget/flash/flash.swf'
+  #
+  def flash_path(*path)
+    flash = path.pop
+    "/flash/widgets/#{path.join('/')}/#{flash}"
+  end
+  # Returns an image tag for a image asset.
+  #
+  # ==== Example
+  #   <%= image :some, :widget, 'image.png', :border => 0 %>
+  #   # => '<img src="app/widgets/some/widget/images/image.png" border=0 />'
+  #
+  def image(*path)
+    options = path.extract_options!
+    image = path.pop
+    image_tag "widgets/#{path.join('/')}/#{image}", options
+  end
+  # Returns an image path for a image asset.
+  #
+  # ==== Example
+  #   <%= image_path :some, :widget, 'image.png' %>
+  #   # => 'app/widgets/some/widget/images/image.png'
+  #
+  def image_path(*path)
+    image = path.pop
+    "/images/widgets/#{path.join('/')}/#{image}"
+  end
+  # Renders a partial asset.
+  #
+  # ==== Example
+  #   <%= partial :some, :widget, 'partial', :locals => { :x => true } %>
+  #   # => render :partial => 'app/widgets/some/widget/partials/partial', :locals => { :x => true }
+  #
+  def partial(*path)
+    options = path.extract_options!
+    partial = path.pop
+    path << options
+    widgets, options = widget_instances path
+    options = {
+      :locals  => options.merge(:options => options),
+      :partial => "#{path.join('/')}/partials/#{partial}"
+    }
+    render options
+  end
+  # Creates and recycles instances of the Widget class.
+  #
+  class Widgets
+    attr :widgets, true
+    # Should be called from a helper. See <tt>widget (RailsWidget)</tt>.
+    #
+    # ==== Example
+    #   w = Widgets.new Assets.new(binding, controller), binding, controller, logger
+    #
+    def initialize(assets, bind, controller, logger)
+      @assets     = assets
+      @bind       = bind
+      @controller = controller
+      @logger     = logger
+      @widgets    = {}
+      build
+    end
+    # See <tt>widget (RailsWidget)</tt>.
+    #
+    def build(path=[''], options={})
+      widgets, opts = instanciate path
+      options = opts.merge options        # Merge the options parameter (highest precedence)
+      add_static_assets  widgets, options
+      return_init_assets widgets, options # Returns the init partial to <tt>widget (RailsWidget)</tt>
+    end
+    # Creates Widget instances for the widget path and its <tt>related_paths</tt> if they do not already exist.
+    #
+    # Returns an array of widget instances and merged <tt>options.rb</tt> hashes.
+    #
+    # ==== Example
+    #   w.build([ :some, :widget ], { :option1 => true })
+    #   # => [ #<Widget>, #<Widget>, #<Widget> ], { :option1 => true, :option2 => true }
+    #
+    # (See the <tt>related_paths</tt> example for context.)
+    #
+    def instanciate(path)
+      opts = {}
+      widgets = related_paths(path).collect do |r|
+        @widgets[r] ||= Widget.new r, @bind, @controller, @logger
+        opts.merge! @widgets[r].options
+        @widgets[r]
+      end
+      [ widgets, opts ]
+    end
+    # Calls <tt>copy_assets (Widget)</tt> for a number of <tt>Widget</tt> instances.
+    #
+    # Also adds static (non-init) assets to the layout via the Assets helpers.
+    #
+    def add_static_assets(widgets, options)
+      widgets.each do |w|
+        w.copy_assets
+        js  = w.asset_paths :javascripts
+        css = w.asset_paths :stylesheets
+        @assets.javascripts *(js  + [ :cache => w.cache ]) unless js.empty?
+        @assets.stylesheets *(css + [ :cache => w.cache ]) unless css.empty?
+        @assets.templates   *(w.assets[:templates].collect do |t|
+          { :id => File.basename(t), :partial => t, :locals => options.merge(:options => options) }
+        end) unless w.assets[:templates].empty?
+      end
+    end
+    # Renders and returns the init partial (<tt>partials/_init.*</tt>) for a number of <tt>Widget</tt> instances.
+    #
+    # The <tt>:include_js => true</tt> option appends <tt>javascripts/init.js</tt> in <script> tags.
+    # Use this option when rendering a widget in an Ajax response.
+    #
+    def return_init_assets(widgets, options)
+      # Render partials/_init.* (options[:include_js] will render javascripts/init.js in <script> tags)
+      widgets.collect do |w|
+        # We want widgets rendered from the partial to include first
+        partial = w.render_init :partials, options
+        css = w.render_init :css, options
+        js  = w.render_init :js,  options
+        if options[:include_js] && js && !js.empty?
+          partial + "\n<script type='text/javascript'>\n#{js}\n</script>"
+        else
+          @assets.stylesheets do
+            css
+          end unless css.empty?
+          @assets.javascripts do
+            js
+          end unless js.empty?
+          partial
+        end
+      end
+    end
+    private
+    # Returns an array of related paths based on a single widget path.
+    #
+    # ==== Example
+    #   related_paths([ :some, :widget ])
+    #   # => [ 'some', 'widget', 'some/widget' ]
+    #
+    # Options are merged based on the order of the array that <tt>related_paths</tt> returns:
+    #   app/widgets/some/options.rb         # { :option1 => true, :option2 => false }
+    #   app/widgets/widget/options.rb       # { :option1 => false }
+    #   app/widgets/some/widget/options.rb  # { :option2 => true }
+    #
+    # Sequentially merging the options in this example produces <tt>{ :option1 => false, :option2 => true }</tt>.
+    #
+    # Assets are also included and rendered (init files) in the order of the <tt>related_paths</tt> array.
+    #
+    def related_paths(paths)
+      ordered = []
+      last = paths.length - 1
+      paths.each_index do |x|
+        if x != 0 && File.exists?("app/widgets/#{paths[x]}")
+          ordered << related_paths(paths[x..last])
+        end
+        path = paths[0..x].join '/'
+        if File.exists?("app/widgets/#{path}")
+          ordered << path
+        end
+      end
+      ordered.flatten
+    end
+  end
+end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: winton-rails_widget
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: "1.1"
 platform: ruby
 authors:
 - Winton Welsh
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2008-08-16 00:00:00 -07:00
+date: 2008-11-08 00:00:00 -08:00
 default_executable:
 dependencies: []
-description: A mini-framework for your client side Rails assets
+description: Allows you to group your client-side assets into distributable widgets
 email: mail@wintoni.us
 executables: []
@@ -25,12 +25,12 @@ files:
 - init.rb
 - lib/rails_widget.rb
 - lib/rails_widget
+- lib/rails_widget/widgets.rb
 - lib/rails_widget/assets.rb
 - lib/rails_widget/widget.rb
 - MIT-LICENSE
 - README.markdown
-- tasks/rails_widget.rake
-has_rdoc: false
+has_rdoc: true
 homepage: http://github.com/winton/rails_widget
 post_install_message:
 rdoc_options: []
@@ -55,6 +55,6 @@ rubyforge_project:
 rubygems_version: 1.2.0
 signing_key:
 specification_version: 2
-summary: A mini-framework for your client side Rails assets
+summary: Allows you to group your client-side assets into distributable widgets
 test_files: []

data/tasks/rails_widget.rake DELETED Viewed

@@ -1,31 +0,0 @@
-desc 'Updates app/widgets assets'
-task :widgets => [ 'widgets:javascripts', 'widgets:stylesheets' ]
-namespace :widgets do
-  desc 'Updates app/widgets/javascripts'
-  task :javascripts do
-    rails_widget_resource 'widgets/javascripts', 'app/widgets/javascripts'
-  end
-  desc 'Updates app/widgets/stylesheets'
-  task :stylesheets do
-    rails_widget_resource 'widgets/stylesheets', 'app/widgets/stylesheets'
-  end
-  def rails_widget_resource(type, to, reverse=false)
-    from = "#{File.dirname(__FILE__)}/../resources/#{type}"
-    from, to = to, from if reverse
-    puts "=> Removing old #{type}..."
-    FileUtils.remove_dir to, true
-    FileUtils.mkdir_p to
-    puts "=> Copying #{type}..."
-    Dir["#{from}/*"].each do |f|
-      if File.directory? f
-        FileUtils.mkdir_p "#{to}/#{File.basename(f)}"
-        FileUtils.cp_r f, to
-      else
-        FileUtils.cp f, to
-      end
-    end
-  end
-end