RubyGems - lwe-page_title_helper - Versions diffs - 0.4.0 - Mend

lwe-page_title_helper 0.4.0

Files changed (11) hide show

data/.gitignore +2 -0
data/LICENSE +20 -0
data/README.rdoc +92 -0
data/Rakefile +66 -0
data/VERSION.yml +4 -0
data/init.rb +1 -0
data/lib/page_title_helper.rb +96 -0
data/page_title_helper.gemspec +47 -0
data/test/page_title_helper_test.rb +87 -0
data/test/test_helper.rb +8 -0
metadata +64 -0

data/.gitignore ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ doc/
2	+ pkg/

data/LICENSE ADDED Viewed

@@ -0,0 +1,20 @@
+Copyright (c) 2009 by Lukas Westermann (Zurich, Switzerland)
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc ADDED Viewed

@@ -0,0 +1,92 @@
+= Page title helper
+Ever wondered if there was an easier and DRY-way to set your page titles (and/or headings). Backed
+byRails (>= 2.3) new support for <i>I18n</i> the solution is a simple helper method.
+In your layout add this to your <tt><head>-section</tt>:
+      ...
+      <title><%=h page_title %></title>
+      ...
+That's it. Now just add your translations, to the locales, in e.g. <tt>config/locales/en.yml</tt>:
+      en:
+        contacts:
+          index:
+            title: "Contacts"
+When <tt>contacs/index.html.erb</tt> is rendered, the key <tt>:en, :contacts, :index, :title</tt>
+is looked up and printed, together with the applications basename, like: <tt>My cool app - Contacts</tt>.
+The format etc. is of course configurable, just head down to the options.
+== Customize titles
+Need a custom title, or need to fill in some placeholders? Just provide a block, in e.g.
+<tt>contacts/show.html.erb</tt> the requirement is to display the contacts name in the
+<tt><title>-tag</tt> as well as in the heading?
+    <h1><%=h page_title { @contact.name } %></h1>
+A call to <tt>page_title</tt> will now return the contacts name, neat :) if for example the
+<tt>h1</tt> does not match the +title+, then
+well, just do something like:
+    <% page_title { @contact.name + " (" + @contact.company.name + ")" } %>
+    <h1><%=h @contact.name %></h1>
+Guess, that's it. Of course it's also possible to use +translate+ within the +page_title+ block, so
+to translate customzied titles, like:
+    # in config/locales/en.yml:
+    en:
+      dashboard:
+        index:
+          title: "Welcome back, {{name}}"
+    # in app/views/dashboard/index.html.erb:
+    <h1><%=h page_title { t '.title', :name => @user.first_name } %></h1>
+Btw - a helpful rule-of-thumb: if +page_title+ is used with a +block+ a title is <b>defined</b>,
+if it's used without the current title is rendered.
+== More fun with <tt>:format</tt>
+The <tt>:format</tt> option is used to specify how a title is formatted, i.e. if the app name is
+prependor appended, or if it contains the account name etc. It uses a similar approach as
+<tt>paperclip</tt>s path interpolations:
+    page_title :format => ':title / :app' # => "Contacts / My cool app"
+Adding custom interpolations is as easy as defining a block, for example to access the current
+controller:
+    PageTitleHelper.interpolates :controller do |title,options|
+      controller.class.humanize
+    end
+    page_title :format => ':title / :controller / :app' # => "Welcome back / Dashboard / My cool app"
+To access just the title, without any magic app stuff interpolated or appended, use:
+    page_title { "untitled" }
+    page_title :format => false # => "untitled"
+== All options - explained
+* <tt>page_title { ... }</tt> - not per se an option, but if a block is given the methods sets a
+  custom title and overwrites any DRY-I18n title.
+* <tt>:app</tt> - specifiy the applications name, however it's recommended to define the
+  translation key <tt>:'app.name'</tt>. If set to <tt>true</tt>, just returns the app name,
+  as defined in the translations or based on the +RAILS_ROOT+ humanized basename.
+* <tt>:default</tt> - string which is displayed when no translation exists and no custom title
+  has been specified. Can also be set to a symbol or array to take advantage of
+  <tt>I18n.translate</tt>s <tt>:default</tt> option. (Default is <tt>:'app.tagline'</tt>)
+* <tt>:format</tt> - defines the output format, accepts a string containing multiple interpolations,
+  see <i>More fun with <tt>:format</tt></i>. If set to +false+, just the current title is returned.
+  (Default is <tt>":app - :title"</tt>)
+* <tt>:suffix</tt> - not happy with the fact that the translations must be named like
+  <tt>en -> contacts -> index -> title</tt>, but prefer e.g. them to be suffixed with
+  <tt>page_title</tt>? Then just set <tt>:suffix => :page_title</tt>. (Default <tt>:title</tt>)
+Copyright (c) 2009 Lukas Westermann (Zurich, Switzerland), released under the MIT license

data/Rakefile ADDED Viewed

@@ -0,0 +1,66 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+desc 'Default: run unit tests.'
+task :default => :test
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "page_title_helper"
+    gemspec.summary = "Simple, internationalized and DRY page titles and headings for rails."
+    gemspec.email = "lukas.westermann@gmail.com"
+    gemspec.homepage = "http://github.com/lwe/page_title_helper"
+    gemspec.authors = ["Lukas Westermann"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+desc 'Test the page_title_helper plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+desc 'Generate documentation for the page_title_helper plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'PageTitleHelper'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+namespace :metrics do
+  desc 'Report code statistics for library and tests to shell.'
+  task :stats do |t|
+    require 'code_statistics'
+    dirs = {
+      'Libraries' => 'lib',
+      'Unit tests' => 'test'
+    }.map { |name,dir| [name, File.join(File.dirname(__FILE__), dir)] }
+    CodeStatistics.new(*dirs).to_s
+  end
+  desc 'Report code coverage to HTML (doc/coverage) and shell (requires rcov).'
+  task :coverage do |t|
+    rm_f "doc/coverage"
+    mkdir_p "doc/coverage"
+    rcov = %(rcov -Ilib:test --exclude '\/gems\/' -o doc/coverage -T test/*_test.rb )
+    system rcov
+  end
+end
+desc 'Start IRB console with loaded test/test_helper.rb and sqlite db.'
+task :console do |t|
+  chdir File.dirname(__FILE__)
+  exec 'irb -Ilib/ -r page_title_helper'
+end
+desc 'Clean up generated files.'
+task :clean do |t|
+  FileUtils.rm_rf "doc"
+end

data/VERSION.yml ADDED Viewed

@@ -0,0 +1,4 @@
+---
+:major: 0
+:minor: 4
+:patch: 0

data/init.rb ADDED Viewed

	@@ -0,0 +1 @@
1	+ require File.join(File.dirname(__FILE__), 'lib', 'page_title_helper')

data/lib/page_title_helper.rb ADDED Viewed

@@ -0,0 +1,96 @@
+# PageTitleHelper
+module PageTitleHelper
+  module Interpolations
+    extend self
+    # Returns a sorted list of all interpolations.
+    def self.all
+      self.instance_methods(false).sort
+    end
+    def self.interpolate(pattern, *args)
+      all.reverse.inject(pattern.dup) do |result, tag|
+        result.gsub(/:#{tag}/) do |match|
+          send(tag, *args)
+        end
+      end
+    end
+    def app(title, options)
+      options[:app] || I18n.translate(:'app.name', :default => File.basename(RAILS_ROOT).humanize)
+    end
+    def title(title, options)
+      title
+    end
+  end
+  # Add new, custom, interpolation.
+  def self.interpolates(key, &block)
+    Interpolations.send(:define_method, key, &block)
+  end
+  # Default options, which are globally referenced and can
+  # be changed globally, which might be useful in some cases.
+  def self.options
+    @options ||= {
+      :format => ':app - :title',
+      :default => :'app.tagline',
+      :suffix => :title
+    }
+  end
+  def page_title(options = nil, &block)
+    if block_given?
+      content_for(:page_title) { yield }
+      return read_page_title_content_block
+    end
+    options = PageTitleHelper.options.merge(options || {})
+    options.assert_valid_keys(:app, :suffix, :default, :format)
+    # just return the applications name
+    return Interpolations.app('', {}) if options[:app] == true
+    # read page title
+    page_title = read_page_title_content_block
+    page_title = I18n.translate(i18n_template_key(options[:suffix]), :default => options[:default]) if page_title.blank?
+    # return page title if format is set explicitly to false
+    return page_title if options[:format] == false
+    # else -> interpolate
+    Interpolations.interpolate options[:format] || ':app - :title', page_title, options
+  end
+  protected
+    # Access <tt>@content_for_page_title</tt> variable, though this is a tad
+    # hacky, because... what if they (the rails guys) change the behaviour of
+    # <tt>content_for</tt>? Well, in Rails 2.3.x it works so far.
+    #
+    # But to simplify compatibility with later versions, this method kinda abstracts
+    # away access to the content within a <tt>content_for</tt> block.
+    def read_page_title_content_block
+      instance_variable_get(:'@content_for_page_title')
+    end
+    # Access +ActionView+s internal <tt>@_first_render</tt> variable, to access
+    # template first rendered, this is to help create the DRY-I18n-titles magic,
+    # and also kind of a hack, because this really seems to be some sort if
+    # internal variable, that's why it's "abstracted" away as well.
+    #
+    def read_first_render_path
+      @_first_render.template_path
+    end
+    def i18n_template_key(suffix = nil)
+      ikey = read_first_render_path.gsub(/\.html\.erb$/, '').tr('/', '.')
+      ikey = ikey + "." + suffix.to_s unless suffix.nil?
+      ikey
+    end
+end
+# tie stuff together
+if Object.const_defined?('ActionView')
+  ActionView::Base.send(:include, PageTitleHelper)
+end

data/page_title_helper.gemspec ADDED Viewed

@@ -0,0 +1,47 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |s|
+  s.name = %q{page_title_helper}
+  s.version = "0.4.0"
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Lukas Westermann"]
+  s.date = %q{2009-07-07}
+  s.email = %q{lukas.westermann@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION.yml",
+     "init.rb",
+     "lib/page_title_helper.rb",
+     "page_title_helper.gemspec",
+     "test/page_title_helper_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/lwe/page_title_helper}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.2}
+  s.summary = %q{Simple, internationalized and DRY page titles and headings for rails.}
+  s.test_files = [
+    "test/page_title_helper_test.rb",
+     "test/test_helper.rb"
+  ]
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/test/page_title_helper_test.rb ADDED Viewed

@@ -0,0 +1,87 @@
+require 'test_helper'
+require 'page_title_helper'
+class MockRender
+  def initialize(template_path = 'contacts/index.html.erb')
+    @template_path = template_path
+  end
+  def template_path; @template_path; end
+end
+class MockView
+  include PageTitleHelper
+  def initialize(template_path = 'contacts/index.html.erb')
+    @_first_render = MockRender.new template_path
+  end
+  def content_for(sym, &block)
+    instance_variable_set('@content_for_' + sym.to_s, yield)
+  end
+end
+I18n.backend.store_translations :en, :contacts => { :list => { :title => 'contacts.list.title' }}
+I18n.backend.store_translations :en, :placeholder => 'Displaying {{name}}'
+class PageTitleHelperTest < ActiveSupport::TestCase
+  test "interpolations" do
+    assert_equal 'Page title helper', PageTitleHelper::Interpolations.app('untitled', {})
+    assert_equal 'Appname', PageTitleHelper::Interpolations.app('untitled', { :app => 'Appname' })
+    assert_equal 'untitled', PageTitleHelper::Interpolations.title('untitled', {})
+  end
+  test "adding custom interpolation" do
+    # extend Interpolations
+    PageTitleHelper.interpolates :app_reverse do |title, options|
+      app(title,options).reverse.downcase
+    end
+    assert_equal "anna", PageTitleHelper::Interpolations.app_reverse('untitled', { :app => 'Anna' })
+    assert_equal "ppa", PageTitleHelper::Interpolations.interpolate(':app_reverse', 'foo', { :app => 'app' })
+  end
+  test "setting title to 'foo' returns 'foo'" do
+    view = MockView.new
+    view.page_title { "foo" }
+    assert_equal 'Page title helper - foo', view.page_title
+  end
+  test "reading defaults from I18n" do
+    view = MockView.new 'contacts/list.html.erb'
+    assert_equal 'Page title helper - contacts.list.title', view.page_title
+  end
+  test "printing app name only if :app => true" do
+    view = MockView.new
+    assert_equal 'Page title helper', view.page_title(:app => true)
+  end
+  test "custom formatting options" do
+    view = MockView.new
+    view.page_title { "test" }
+    assert_equal "Some app :: test", view.page_title(:app => "Some app", :format => ':app :: :title')
+    assert_equal "Some app / test", view.page_title(:format => 'Some app / :title')
+  end
+  test "return value of block to be used as heading" do
+    view = MockView.new
+    assert_equal "untitled", view.page_title { "untitled" }
+  end
+  test "calling :format => false returns just current title, without any interpolations etc." do
+    view = MockView.new
+    view.page_title { "untitled" }
+    assert_equal "untitled", view.page_title(:format => false)
+    i18n_view = MockView.new 'contacts/list.html.erb'
+    assert_equal "contacts.list.title", i18n_view.page_title(:format => false)
+  end
+  test "custom title using a translation with a placeholder" do
+    view = MockView.new
+    view.page_title { I18n.t :placeholder, :name => 'Bella' }
+    assert_equal "Page title helper - Displaying Bella", view.page_title
+  end
+end

data/test/test_helper.rb ADDED Viewed

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'test/unit'
+require 'active_support'
+require 'active_support/test_case'
+ROOT = File.expand_path File.dirname(File.dirname(__FILE__))
+RAILS_ROOT = '/this/is/just/for/testing/page_title_helper'
+RAILS_ENV = 'test'

metadata ADDED Viewed

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: lwe-page_title_helper
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Lukas Westermann
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2009-07-07 00:00:00 -07:00
+default_executable:
+dependencies: []
+description:
+email: lukas.westermann@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.rdoc
+files:
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION.yml
+- init.rb
+- lib/page_title_helper.rb
+- page_title_helper.gemspec
+- test/page_title_helper_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/lwe/page_title_helper
+post_install_message:
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: "0"
+  version:
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: "0"
+  version:
+requirements: []
+rubyforge_project:
+rubygems_version: 1.2.0
+signing_key:
+specification_version: 3
+summary: Simple, internationalized and DRY page titles and headings for rails.
+test_files:
+- test/page_title_helper_test.rb
+- test/test_helper.rb