RubyGems - hierarchical_page_titles - Versions diffs - 0.1.0.pre - Mend

hierarchical_page_titles 0.1.0.pre

Files changed (14) hide show

data/.gitignore +2 -0
data/.rvmrc +1 -0
data/Gemfile +3 -0
data/README.md +126 -0
data/README.textile +69 -0
data/Rakefile +2 -0
data/hierarchical_page_titles.gemspec +21 -0
data/lib/hierarchical_page_titles/controller_helpers.rb +46 -0
data/lib/hierarchical_page_titles/railtie.rb +14 -0
data/lib/hierarchical_page_titles/shared_methods.rb +40 -0
data/lib/hierarchical_page_titles/version.rb +3 -0
data/lib/hierarchical_page_titles/view_helpers.rb +53 -0
data/lib/hierarchical_page_titles.rb +1 -0
metadata +83 -0

data/.gitignore ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ .DS_Store
2	+ *.tmproj

data/.rvmrc ADDED Viewed

	@@ -0,0 +1 @@
1	+ rvm 1.8.7@hierarchical_page_titles

data/Gemfile ADDED Viewed

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+gemspec

data/README.md ADDED Viewed

@@ -0,0 +1,126 @@
+## hierarchical_page_titles
+### What is this?
+This is a little gem that provides controller and view methods to make displaying of window/page titles DRYer.
+### Why did you make it?
+I made it because I found that I was doing the same thing over and over in my Rails apps. Setting the window or page title is a very common thing, and usually you'd handle this by simply setting a `@title` variable in your view and using it in your layout. However, I kept running into the case where I wanted to set the window title separate from the page title, or I wanted to set part of the window title globally for a controller, or I wanted to set the window title but hide the page title, and so on. So I decided to come up with a way to satisfy these requirements and yet keep things simple.
+### How do I use it?
+I'm going to walk through a few use cases and hopefully you'll get the idea.
+#### Window and page title are the same
+Here's what your layout might look like:
+      <html>
+        <head><title><%= window_title %></title></head>
+        <body>
+          <h1><%= page_title %></h1>
+          <%= yield %>
+        </body>
+      </html>
+So in your view, you'd do this:
+      <% title "Some Page" %>
+      <p>Some content</p>
+And now when your layout is rendered, it will be this:
+      <html>
+        <head><title>Some Page</title></head>
+        <body>
+          <h1>Some Page</h1>
+          <p>Some content</p>
+        </body>
+      </html>
+#### Window title with prefix
+Nothing special required here, just put it in your layout:
+      <html>
+        <head><title>My Site - <%= window_title %></title></head>
+        <body>
+          <h1><%= page_title %></h1>
+          <%= yield %>
+        </body>
+      </html>
+And when the page is rendered:
+      <html>
+        <head><title>My Site - Some Page</title></head>
+        <body>
+          <h1>Some Page</h1>
+          <p>Some content</p>
+        </body>
+      </html>
+#### Hiding page title for certain pages
+#### A page hierarchy
+Controllers:
+<pre>
+<code>
+  class ApplicationController < ActionController::Base
+    window_title "My Site Name"
+  end
+  class SupportController < ApplicationController
+    window_title "Support"
+    def billing; end
+  end
+</code>
+</pre>
+Views:
+<pre>
+<code>
+  #==== app/views/layouts/application.html.erb ====
+  <html>
+    <head><title><%= window_title %></title></head>
+    <body>
+      <h2><%= page_title %></h2>
+    </body>
+  </html>
+  #==== app/views/support/billing.html.erb ====
+  # this adds to the window title and the page title at the same time
+  <% title "Billing FAQs" %>
+</code>
+</pre>
+When the billing view is rendered:
+* The window title will be "My Site Name - Support - Billing FAQs"
+* The page title (in the &lt;h2&gt; tag) will be "Billing FAQs"
+### How is it different from XYZ?
+There are several related gems/plugins:
+* **dynamic-page-title**: Provides options to `title` which are unnecessary. No support for hierarchical (controller-level) titles. Isn't compatible with Rails 3.
+* **entitled**: Interesting, but has totally different requirements.
+* **happy-titles**: The idea here is that you specify a template which I think is inflexible. No support for hierarchical titles, only supports two levels.
+* **headliner**: A good design for simple requirements, and compatible with Rails 3. Again, no support for hierarchy, though. Plus, the `t` shortcut conflicts with i18n, which is bad. Not a gem.
+* **page_title_helper**: Good if you need i18n, otherwise is a bit overkill. Again, no support for hierarchy, though.
+* **smart_titles**: Stupid simple, and provides i18n. Again, no support for hierarchy, though.
+* **title_helper**: Not sure, Github project seems to be missing.
+* [**title_helpers**](https://github.com/henrik/title_helpers): Supports a page prefix, but doesn't support full hierarchy. Plus, I don't really like the API, and it isn't a gem.
+### How do I install it?
+    gem install hierarchical_page_titles
+### How do I contribute?
+### Who wrote this?
+(c) 2009 Elliot Winkler (elliot dot winkler at gmail dot com).
+Released under the MIT license.

data/README.textile ADDED Viewed

@@ -0,0 +1,69 @@
+h2. title_helpers
+h3. Summary
+Rails plugin that provides controller and view methods to make displaying of
+window/page titles DRYer.
+h3. Rationale
+Most web sites you'll build have some sort of hierarchy. And most times this
+hierarchy will correspond to your controllers. For instance, let's say you have a
+support section on your website (@SupportController@), and under that you have FAQs
+about billing (the @billing@ action). Now, I think it's important for the window
+title to be informative -- in fact, it should come directly from the page hierarchy.
+So, going back to our billing FAQs page, you might want the window title to be
+"Foo.com - Support - Billing FAQs". But that's going to be a pattern, isn't it?
+"Foo.com - #{some controller} - #{some action}". You're not really going to define
+the full window title for every action in your code, are you? I'm certainly not going
+to. Wouldn't it be better if you could set the window title on a controller basis,
+and then, in your view, set the window title for just the action?
+h3. Example
+Controllers:
+<pre>
+<code>
+  class ApplicationController < ActionController::Base
+    window_title "My Site Name"
+  end
+  class SupportController < ApplicationController
+    window_title "Support"
+    def billing; end
+  end
+</code>
+</pre>
+Views:
+<pre>
+<code>
+  #==== app/views/layouts/application.html.erb ====
+  <html>
+    <head><title><%= window_title %></title></head>
+    <body>
+      <h2><%= page_title %></h2>
+    </body>
+  </html>
+  #==== app/views/support/billing.html.erb ====
+  # this adds to the window title and the page title at the same time
+  <% title "Billing FAQs" %>
+</code>
+</pre>
+When the billing view is rendered:
+* The window title will be "My Site Name - Support - Billing FAQs"
+* The page title (in the &lt;h2&gt; tag) will be "Billing FAQs"
+h3. Installation
+<pre>
+  script/plugin install git://github.com/mcmire/title_helpers.git
+</pre>
+h3. Author
+(c) 2009 Elliot Winkler (elliot dot winkler at gmail dot com).
+Released under the MIT license.

data/Rakefile ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ require 'bundler'
2	+ Bundler::GemHelper.install_tasks

data/hierarchical_page_titles.gemspec ADDED Viewed

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "hierarchical_page_titles/version"
+Gem::Specification.new do |s|
+  s.name        = "hierarchical_page_titles"
+  s.version     = HierarchicalPageTitles::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Elliot Winkler"]
+  s.email       = ["elliot.winkler@gmail.com"]
+  s.homepage    = "http://github.com/mcmire/hierarchical_page_titles"
+  s.summary     = %q{A gem that provides controller and view methods to make displaying of window/page titles DRYer.}
+  s.description = %q{A gem that provides controller and view methods to make displaying of window/page titles DRYer.}
+  #s.rubyforge_project = "title_helpers"
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/hierarchical_page_titles/controller_helpers.rb ADDED Viewed

@@ -0,0 +1,46 @@
+require 'hierarchical_page_titles/shared_methods'
+module HierarchicalPageTitles
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+    include SharedMethods
+    module ClassMethods
+      # Call this in the body of your controller with a string to add the string to
+      # the window title before each action in your controller. This will work
+      # for subcontrollers too -- so if you call window_title in a supercontroller
+      # and also in a subcontroller, there will be two strings when you go to output
+      # the window title. You can pass :only and :except to limit this to certain actions.
+      def window_title(*args, &block)
+        options = Hash === args.last ? args.last : {}
+        before_filter(options) {|c| c.window_title(*args, &block) }
+      end
+      # Call this in the body of your controller with a string to set the page title
+      # globally for each action in your controller. Unlike window_title, this will not
+      # work for subcontrollers -- so if you call page_title in a supercontroller and
+      # also in a subcontroller, the subcontroller's title will override the supercontroller's.
+      # You can pass :only and :except to limit this to certain actions.
+      def page_title(*args, &block)
+        options = Hash === args.last ? args.last : {}
+        before_filter(options) {|c| c.page_title(*args, &block) }
+      end
+      # Call this in the body of your controller with a string to add it to the
+      # window title AND set the page title at the same time.
+      # See +window_title+ and +page_title+ for more.
+      # You can pass :only and :except to limit this to certain actions.
+      def title(*args, &block)
+        options = Hash === args.last ? args.last : {}
+        before_filter(options) {|c| c.title(*args, &block) }
+      end
+      # Call this in the body of your controller to tell page_title to not show anything.
+      # You can pass :only and :except to limit this to certain actions.
+      def hide_page_title(options={})
+        before_filter(options) {|c| c.page_title(nil) }
+      end
+    end
+  end
+end

data/lib/hierarchical_page_titles/railtie.rb ADDED Viewed

@@ -0,0 +1,14 @@
+require 'rails'
+require 'hierarchical_page_titles/controller_helpers'
+require 'hierarchical_page_titles/view_helpers'
+module HierarchicalPageTitles
+  class Railtie < Rails::Railtie
+    # copied from formtastic
+    initializer "title-helpers.initialize", :after => :after_initialize do
+      ActionController::Base.class_eval { include HierarchicalPageTitles::ControllerHelpers }
+      ActionView::Base.class_eval { include HierarchicalPageTitles::ViewHelpers }
+    end
+  end
+end

data/lib/hierarchical_page_titles/shared_methods.rb ADDED Viewed

@@ -0,0 +1,40 @@
+module HierarchicalPageTitles
+  module SharedMethods
+    # Call this in your view with a string to add the string to the array of window titles.
+    # Call this in your layout to output the window title. You can specify a separator
+    # that should be put between the titles by passing <tt>:separator => " - "</tt>.
+    def window_title(*args, &block)
+      options = args.extract_options!
+      titles = args.flatten
+      @_window_titles ||= []
+      if block_given?
+        @_window_titles << block.call
+      else
+        @_window_titles += titles
+      end
+      @_window_title_set = true
+    end
+    # Call this in your view with a string to set the page title to that string.
+    # Call this in your layout with no arguments to output the page title.
+    def page_title(*args, &block)
+      options = args.extract_options!
+      title = args.first
+      @_page_title = (block_given? ? block.call : title)
+      @_page_title_set = true
+    end
+    # Call this in your view to set the window title and the page title at the same time.
+    # See +window_title+ and +page_title+ for more.
+    def title(*args, &block)
+      options = args.extract_options!
+      window_title(*args, &block)
+      page_title(args.last, &block)
+      @_title_set = true
+    end
+    def titles
+      @_window_titles
+    end
+  end
+end

data/lib/hierarchical_page_titles/version.rb ADDED Viewed

@@ -0,0 +1,3 @@
+module HierarchicalPageTitles
+  VERSION = "0.1.0.pre"
+end

data/lib/hierarchical_page_titles/view_helpers.rb ADDED Viewed

@@ -0,0 +1,53 @@
+require 'hierarchical_page_titles/shared_methods'
+module HierarchicalPageTitles
+  module ViewHelpers
+    include SharedMethods
+    # Call this in your view with a string to add the string to the array of window titles.
+    # Call this in your layout to output the window title. You can specify a separator
+    # that should be put between the titles by passing <tt>:separator => " - "</tt>.
+    def window_title(*args, &block)
+      options = args.extract_options!
+      if args.empty?
+        options[:separator] ||= " - "
+        @_window_titles ||= []
+        prefix = Array(options[:prefix]) || []
+        (prefix + @_window_titles).join(options[:separator])
+      else
+        super
+      end
+    end
+    # Call this in your view with a string to set the page title to that string.
+    # Call this in your layout with no arguments to output the page title.
+    def page_title(*args)
+      options = args.extract_options!
+      if args.empty?
+        @_page_title
+      else
+        super
+      end
+    end
+    # TODO: Document
+    def page_title?
+      @_page_title.present?
+    end
+    # TODO: Document
+    def window_title_set?
+      @_window_title_set
+    end
+    # TODO: Document
+    def page_title_set?
+      @_window_title_set
+    end
+    # TODO: Document
+    def title_set?
+      @_title_set
+    end
+  end
+end

data/lib/hierarchical_page_titles.rb ADDED Viewed

	@@ -0,0 +1 @@
1	+ require 'hierarchical_page_titles/railtie'

metadata ADDED Viewed

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: hierarchical_page_titles
+version: !ruby/object:Gem::Version
+  hash: 961915980
+  prerelease: true
+  segments:
+  - 0
+  - 1
+  - 0
+  - pre
+  version: 0.1.0.pre
+platform: ruby
+authors:
+- Elliot Winkler
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2010-12-08 00:00:00 -07:00
+default_executable:
+dependencies: []
+description: A gem that provides controller and view methods to make displaying of window/page titles DRYer.
+email:
+- elliot.winkler@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- README.md
+- README.textile
+- Rakefile
+- hierarchical_page_titles.gemspec
+- lib/hierarchical_page_titles.rb
+- lib/hierarchical_page_titles/controller_helpers.rb
+- lib/hierarchical_page_titles/railtie.rb
+- lib/hierarchical_page_titles/shared_methods.rb
+- lib/hierarchical_page_titles/version.rb
+- lib/hierarchical_page_titles/view_helpers.rb
+has_rdoc: true
+homepage: http://github.com/mcmire/hierarchical_page_titles
+licenses: []
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      hash: 3
+      segments:
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      hash: 25
+      segments:
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
+requirements: []
+rubyforge_project:
+rubygems_version: 1.3.7
+signing_key:
+specification_version: 3
+summary: A gem that provides controller and view methods to make displaying of window/page titles DRYer.
+test_files: []