helperful 0.5.2

data/lib/helperful/affiliations_helper.rb

@@ -0,0 +1,44 @@
+#
+# = Helperful
+#
+# A collection of useful Rails helpers.
+#
+#
+# Category::    Rails
+# Package::     Helperful
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2008-2009 The Authors
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+module Helperful
+  
+  #
+  # = Affiliations Helper
+  # 
+  # Provides a set of helpers for working with online affiliations.
+  #
+  module AffiliationsHelper
+  
+    # 
+    # Returns the tradedoubler site verification tag for +publisher_id+.
+    # 
+    #   tradedoubler_verification_tag('123456')
+    #   # => "<! -- TradeDoubler site verification 123456 -->"
+    #   
+    #   tradedoubler_verification_tag(123456)
+    #   # => "<! -- TradeDoubler site verification 123456 -->"
+    #   
+    #   tradedoubler_verification_tag(nil)
+    #   # => "<! -- TradeDoubler site verification  -->"
+    #
+    def tradedoubler_verification_tag(publisher_id)
+      "<!-- TradeDoubler site verification #{publisher_id.to_s} -->"
+    end
+  
+  end
+end

data/lib/helperful/asset_tag_helper.rb

@@ -0,0 +1,105 @@
+#
+# = Helperful
+#
+# A collection of useful Rails helpers.
+#
+#
+# Category::    Rails
+# Package::     Helperful
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2008-2009 The Authors
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+module Helperful
+
+  #
+  # = Asset Tag Helper
+  #
+  # Provides a set of helpers for generating HTML that links views to assets such
+  # as images, javascripts, stylesheets, and feeds.
+  #
+  # ==== Requirements
+  #
+  # The following requirements are mandatory for this module.
+  # Including this helper will automatically include them unless already included.
+  #
+  # * ActionView::Helpers::AssetTagHelper
+  #
+  module AssetTagHelper
+
+    def self.included(base)
+      base.class_eval do
+        base.included_modules.include?(ActionView::Helpers::AssetTagHelper) || include(ActionView::Helpers::AssetTagHelper)
+      end
+    end
+    
+    # Returns a link tag that search engine crawlers may use to determine
+    # the preferred version of a page with multiple URLs.
+    #
+    # More details about the canonical link tag are available
+    # at the following sources:
+    # * http://www.mattcutts.com/blog/canonical-link-tag/
+    # * http://googlewebmastercentral.blogspot.com/2009/02/specify-your-canonical.html
+    #
+    # Control the link options in url_for format using the +url_options+.
+    #
+    # ==== Examples
+    # 
+    #   canonical_link_tag
+    #   # => <link rel="canonical" href=http://www.currenthost.com/controller/action" />
+    #   canonical_link_tag(:action => "show")
+    #   # => <link rel="canonical" href=http://www.currenthost.com/controller/show" />
+    #   canonical_link_tag("http://www.example.com/product.php?item=swedish-fish")
+    #   # => <link rel="canonical" href="http://www.example.com/product.php?item=swedish-fish" />
+    #
+    def canonical_link_tag(url_options = {})
+      tag(
+        "link",
+        "rel"   => "canonical",
+        "href"  => url_options.is_a?(Hash) ? url_for(url_options.merge(:only_path => false)) : url_options
+      )
+    end
+
+    # Converts given +files+ in javascript include statements
+    # and appends them in the head section of the page.
+    # 
+    # ==== Examples
+    # 
+    #   # in your index.html.erb view
+    #   <% javascript :foo, :bar, :cache => "foobar" %>
+    # 
+    #   # this is equivalent to
+    #   <% content_for :head, javascript_include_tag(:foo, :bar, :cache => "foobar") %>
+    # 
+    #   # in your application
+    #   <% yield :head %>
+    # 
+    def javascript(*files)
+      content_for(:head, javascript_include_tag(*files))
+    end
+
+    # Converts given +files+ in stylesheet link statements
+    # and appends them in the head section of the page.
+    # 
+    # ==== Examples
+    # 
+    #   # in your index.html.erb view
+    #   <% stylesheet :foo, :bar, :cache => "foobar" %>
+    # 
+    #   # this is equivalent to
+    #   <% content_for :head, stylesheet_link_tag(:foo, :bar, :cache => "foobar") %>
+    # 
+    #   # in your application
+    #   <% yield :head %>
+    # 
+    def stylesheet(*files)
+      content_for(:head, stylesheet_link_tag(*files))
+    end
+
+  end
+end

data/lib/helperful/content_helper.rb

@@ -0,0 +1,105 @@
+#
+# = Helperful
+#
+# A collection of useful Rails helpers.
+#
+#
+# Category::    Rails
+# Package::     Helperful
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2008-2009 The Authors
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+module Helperful
+  
+  # 
+  # = Content Helper
+  # 
+  # Provides a set of helpers for capturing and working with your page content
+  # in a more effective way.
+  # 
+  # ==== Requires
+  # 
+  # The following requirements are mandatory for this module.
+  # Including this helper will automatically include them unless already included.
+  # 
+  # * ActionView::Helpers::CaptureHelper
+  #
+  module ContentHelper
+    
+    def self.included(base)
+      base.class_eval do
+        base.included_modules.include?(ActionView::Helpers::CaptureHelper) || include(ActionView::Helpers::CaptureHelper)
+        alias_method_chain :content_for, :has
+      end
+    end
+    
+    #
+    # Returns <tt>true</tt> if <tt>name</tt> has any content,
+    # in other workds if content_for(name) has ever been called.
+    # 
+    # ==== Important
+    # 
+    # Some important details to keep in mind.
+    # 
+    # Due to the way <tt>content_for</tt> stores data, it doesn't matter
+    # whether name is a Symbol or a String.
+    # They are treated in the same way. The following calls are equivalent.
+    # 
+    #   has_content? :foo   # => true
+    #   has_content? "foo"  # => true
+    # 
+    # This method doesn't make any difference between an empty, 
+    # blank or nil content. It always returns <tt>true</tt> if
+    # <tt>content_for</tt> has been called with <tt>name</tt>,
+    # it doesn't matter which content is stored.
+    # A call to <tt>has_content?</tt> will always return true
+    # in any of the following cases:
+    # 
+    #   content_for :name, nil
+    #   content_for :name, ''
+    #   content_for :name, []
+    #   content_for :name, 'A real content'
+    #   content_for :name do
+    #     "nothing here"
+    #   end
+    #
+    def has_content?(name)
+      @has_content ||= {}
+      @has_content.key?(name.to_s)
+    end
+    
+    # Flags +name+ to ensure <tt>has_content?</tt> will work as expected.
+    # You would probably never call this method directly.
+    # In fact, you are encouraged to not do so.
+    def has_content!(name) # :nodoc:
+      @has_content ||= {}
+      @has_content[name.to_s] = true
+    end
+    
+    #
+    # Despite its name, this method is a transparent replacement for
+    # the original <tt>content_for</tt> Rails helper.
+    # 
+    # It forwards any request to the original Rails helper,
+    # but before it keep tracks of every request to ensure <tt>has_content?</tt>
+    # will work as expected.
+    # 
+    # == Behind this original name
+    # 
+    # For those of you interested in, this name arises from the need 
+    # to chain it with <tt>alias_method_chain</tt>, following
+    # Rails best practice for extending original core methods.
+    #
+    def content_for_with_has(*args, &block) # :nodoc:
+      has_content!(args.first)
+      content_for_without_has(*args, &block)
+    end
+  
+  end
+end

data/lib/helperful/deprecations.rb

@@ -0,0 +1,26 @@
+#
+# = Helperful
+#
+# A collection of useful Rails helpers.
+#
+#
+# Category::    Rails
+# Package::     Helperful
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2008-2009 The Authors
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+unless defined?(TitleHelper)
+  module TitleHelper
+    def self.included(base)
+      ActiveSupport::Deprecation.warn("TitleHelper is deprecated and will be removed in a future version. " +
+                                      "Please include Helperful::TitleHelper instead.", caller)
+      base.send :include, Helperful::TitleHelper
+    end
+  end
+end

data/lib/helperful/javascript_helper.rb

@@ -0,0 +1,84 @@
+#
+# = Helperful
+#
+# A collection of useful Rails helpers.
+#
+#
+# Category::    Rails
+# Package::     Helperful
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2008-2009 The Authors
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+module Helperful
+  
+  # 
+  # = Javascript Helper
+  # 
+  # Provides a set of helpers for working with JavaScript in your views.
+  # 
+  # ==== Requires
+  # 
+  # The following requirements are mandatory for this module.
+  # Including this helper will automatically include them unless already included.
+  # 
+  # * ActionView::Helpers::CaptureHelper
+  # * ActionView::Helpers::JavaScriptHelper
+  #
+  module JavascriptHelper
+    
+    def self.included(base)
+      base.class_eval do
+#        base.included_modules.include?(ActionView::Helpers::CaptureHelper) || include(ActionView::Helpers::CaptureHelper)
+#        base.included_modules.include?(ActionView::Helpers::JavaScriptHelper) || include(ActionView::Helpers::JavaScriptHelper)
+      end
+    end
+
+    #
+    # Mixes the features of <tt>content_for</tt> and <tt>javascript_tag</tt> into a single helper.
+    #
+    # Supports all original method options and features, including the ability to use write the content
+    # in a block and javascript tag options.
+    #
+    # ==== Examples
+    #
+    #   <% javascript_content_for :head do %>
+    #     $("#id").hide();
+    #   <% end %>
+    #
+    # The block is passed as it is to <tt>javascript_tag</tt>,
+    # then the result is stored as <tt>content_for</tt> :head.
+    # Now you can call <tt>yield</tt> and output your javascript content.
+    #
+    #   <%= yield :head %>
+    #
+    #   <script>$("#id").hide();</script>
+    #
+    # This example is equal to the following statements.
+    #
+    #   <% javascript_content_for :head do; javascript_tag do %>
+    #     $("#id").hide();
+    #   <% end; end %>
+    #
+    #   <% javascript_content_for :head do %>
+    #     <script>$("#id").hide();</script>
+    #   <% end %>
+    #
+    # You can make subsequent calls to <tt>javascript_content_for</tt> and <tt>content_for</tt>,
+    # the result for each call will be appended to the value currently stored for <tt>name</tt>. 
+    #
+    def javascript_content_for(name, content_or_options_with_block = nil, html_options = {}, &block)
+      if block_given?
+        content_for(name, javascript_tag(capture(&block), content_or_options_with_block || {}))
+      else
+        content_for(name, javascript_tag(content_or_options_with_block, html_options))
+      end
+    end  
+  
+  end
+end

data/lib/helperful/title_helper.rb

@@ -0,0 +1,79 @@
+#
+# = Helperful
+#
+# A collection of useful Rails helpers.
+#
+#
+# Category::    Rails
+# Package::     Helperful
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2008-2009 The Authors
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+module Helperful
+  
+  #
+  # = Title Helper
+  #
+  # This module provides an helper for managing page title in Rails views and layouts.
+  #
+  module TitleHelper
+
+    #
+    # = Title Helper
+    #
+    # This helper provides both input and output capabilities
+    # for managing page title in Rails views and layouts.
+    #
+    # When called with +args+, it stores all args for later retrieval.
+    # Additionally, it always return a formatted title so that 
+    # it can be easily called without arguments to display the full page title.
+    #
+    # You can pass some additional options to customize the behavior of the returned string.
+    # The following options are supported:
+    #
+    # :separator::
+    #   the separator used to join all title elements, by default a dash.
+    #
+    # :site::
+    #   the name of the site to be appended to page title.
+    #
+    # :headline::
+    #   website headline to be appended to page title, after any element.
+    #
+    # ==== Examples
+    #
+    #   # in a template set the title of the page
+    #   <h1><%= title "Latest news" %></h1>
+    #   # => <h1>Latest news</h1>
+    #
+    #   # in the layout print the title of the page
+    #   # with the name of the site
+    #   <title><%= title :site => 'My Site' %></title>
+    #   # => <title>Latest news | My Site</title>
+    #
+    def title(*args)
+      @helperful_title ||= []
+      @helperful_title_options ||= {
+        :separator => ' - ',
+        :headline  => nil,
+        :site      => nil,
+      }
+      options = args.extract_options!
+
+      @helperful_title += args
+      @helperful_title_options.merge!(options)
+
+      t =  @helperful_title.clone
+      t << @helperful_title_options[:site]
+      t << @helperful_title_options[:headline]
+      t.compact.join(@helperful_title_options[:separator])
+    end
+
+  end
+end