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

lwe-page_title_helper 0.4.0

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 (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