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

winton-rails_widget 1.0.2 → 1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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