title_helpers 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e5693bd6d2f7573f0e5a69a0f1697e87c730ab2b
+  data.tar.gz: bc66c6741e147e9057c4b456e11687bbe498552b
+SHA512:
+  metadata.gz: 3c47c0652ee0a5ddfb542e5167f4a601032813f87efa5f29f5886f30ac8f3fb588d16a097b099ddb3beb93acc97d392f3949c2de5252ec3e06bc3c599add0a15
+  data.tar.gz: 231d45d31a8341a0805f051f0472071134261d23e9d8e56ced8c7c11badd9d56834200479a69d26e7badbb08647574fe2184ad7119aa9cdc25b5f4c05f2463f7

data/README.markdown

@@ -0,0 +1,144 @@
+# Title Helpers
+
+Rails plugin providing helpers to set and show the site `<title>`.
+
+
+## Showing the title
+
+Show titles like
+
+    <title><%= title("My Site") %></title>
+  
+where "My Site" is your base title. If no custom title has been set for the current page, the returned title will just be that base title (except in development – see below).
+
+You can provide the base title inline, like above. You could also, of course, provide it from a constant or a configuration object that you set up in an initializer, e.g.
+
+    <title><%= title(SITE_TITLE) %></title>
+    
+Your views and controllers can set title prefixes ("Welcome – My Site") as well as override the full title ("Welcome to My Site!").
+
+You can use `title` without an argument to get just the title prefix. This is handy for headers:
+
+    <% self.title = "Welcome" %>
+
+    <title><%= title("My Site")</title>
+    ⋮
+    <h1><%= title %></h1>
+  
+will give the title "Welcome – My Site" and the header "Welcome".
+
+You could even do something like
+
+    <% self.title = "Welcome" %>
+    <% self.full_title = "Welcome to %s!" %>
+
+    <title><%= title("My Site")</title>
+    ⋮
+    <h1><%= title %></h1>
+
+to set the full title to "Welcome to My Site!" and the header to "Welcome".
+
+The `title` helper applies `h` so you don't have to.
+
+
+## Setting the title
+
+Define titles like
+
+    self.title = "Welcome"
+  
+in a controller or
+
+    <% self.title = "Welcome" %>
+
+in a view. The above example would give "Welcome – My Site".
+
+If you do not want the page suffix for a particular page, do e.g.
+
+    self.full_title = "Welcome"
+  
+which would give "Welcome". You can use "%s" to substitute the base title when
+using `full_title`:
+
+    self.full_title = "Welcome to %s!"
+  
+gives "Welcome to My Site!"
+
+Since the `full_title` is treated as a format string (with %s), remember
+to escape any non-format string percentage signs by doubling them:
+
+    self.full_title = "Welcome to %s – 100%% French bulldogs"
+  
+gives "Welcome to My Site – 100% French bulldogs".
+
+If your `full_title` contains dynamic data, you can use the `format_string_escape`
+(or `fs_escape` for short) helper:
+
+    user.name = "%see%my%vest%"
+    self.full_title = "#{fs_escape user.name} on %s"
+  
+When using `title=`, data is automatically escaped, since format strings can only be
+used with `full_title`:
+
+    user.name = "%see%my%vest%"
+    self.title = user.name
+  
+gives "%see%my%vest% – My Site".
+
+
+## Title hints in development
+
+If no title has been set for a page, the base title will be shown. *In development*, however, you will see
+
+    ~ PLEASE SET A TITLE ~
+    
+This is intended to help you remember to title every page. If you really just wanted the
+base title on a page and do not want to see this helpful hint, just do
+
+    self.title!
+
+
+## Tips
+
+You can override the `title=` method in your controllers to e.g. get a common prefix:
+
+    class UsersController < ApplicationController
+
+    protected
+
+      def title=(title)
+        title = "User: #{title}"
+        super(title)
+      end
+
+    end
+    
+Now you can do
+
+    self.title = @user.name
+    
+from the controller or its views, to get titles like "User: User Name – My Site".
+  
+## Credits and license
+
+By [Henrik Nyh](http://henrik.nyh.se/) under the MIT license:
+
+>  Copyright (c) 2008 Henrik Nyh
+>
+>  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/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.pattern = "test/*_test.rb"
+end
+
+task :default => :test

data/TODO.tasks

@@ -0,0 +1,3 @@
+- Customize delimiter?
+- Multi-level titles?
+- Perhaps _self.title = "Full title"_ for full and _self.title << "Prefix"_ for prefix? Ties in with multi-level.

data/init.rb

@@ -0,0 +1 @@
+ActionController::Base.send(:include, TitleHelpers)

data/lib/title_helpers/version.rb

@@ -0,0 +1,3 @@
+module TitleHelpers
+  VERSION = "0.0.2"
+end

data/lib/title_helpers.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+require "erb"
+require "rubygems"
+require "active_support"
+
+module TitleHelpers
+  HINT = "~ PLEASE SET A TITLE ~"
+
+  def self.included(klass)
+    klass.helper_method :title, :title=,
+      :full_title=, :title!,
+      :format_string_escape, :fs_escape
+  end
+
+private
+
+  def title(site_title = nil)
+    if Rails.env.development? && !@title && !@full_title
+      @full_title = HINT
+    end
+
+    unless site_title
+      title = fs_escape(@title || @full_title)
+    else
+      title = @full_title || (@title && "#{fs_escape @title} – %s") || "%s"
+    end
+
+    ERB::Util.h(title % site_title)
+  end
+
+  # If the helpers are used in a view, then the code runs _after_ instance variables have
+  # been copied from the controller to the template. Without manually copying them over like
+  # this, they would not be available to layouts.
+
+  def title=(title)
+    @title = @template.instance_variable_set("@title", title)
+  end
+
+  def full_title=(title)
+    @full_title = @template.instance_variable_set("@full_title", title)
+  end
+
+  def title!
+    self.full_title=("%s")
+  end
+
+  def format_string_escape(string)
+    string.to_s.gsub('%', '%%')
+  end
+  alias_method :fs_escape, :format_string_escape
+end

data/test/title_helpers_test.rb

@@ -0,0 +1,164 @@
+# encoding: utf-8
+
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '../lib/title_helpers')
+
+class Rails
+  class << self
+    attr_accessor :is_dev
+  end
+
+  def self.env
+    env = Object.new
+    def env.development?() Rails.is_dev end
+    env
+  end
+end
+
+class FakeController
+  def self.helper_method(*args); end
+
+  def initialize
+    @template = Object.new
+  end
+
+  include TitleHelpers
+end
+
+
+class TitleHelpersTest < Test::Unit::TestCase
+
+  def setup
+    @controller = FakeController.new
+  end
+
+  def assert_equal_in_controller(expected, &block)
+    assert_equal expected, @controller.instance_eval(&block)
+  end
+
+
+  def test_format_string_escape
+    assert_equal_in_controller("x") { format_string_escape("x") }
+    assert_equal_in_controller("%%s") { format_string_escape("%s") }
+  end
+
+
+  def test_title_with_suffix
+    assert_equal_in_controller("Welcome – My Site") do
+      self.title = "Welcome"
+      title("My Site")
+    end
+  end
+
+  def test_title_with_no_suffix
+    assert_equal_in_controller("Welcome") do
+      self.title = "Welcome"
+      title
+    end
+  end
+
+  def test_title_with_format_string_without_suffix
+    assert_equal_in_controller("%s") do
+      self.title = "%s"
+      title
+    end
+  end
+
+  def test_title_with_format_string_with_suffix
+    assert_equal_in_controller("%s – My Site") do
+      self.title = "%s"
+      title("My Site")
+    end
+  end
+
+  def test_title_escapes_html
+    assert_equal_in_controller("&lt;b&gt;ad") do
+      self.title = "<b>ad"
+      title
+    end
+  end
+
+
+
+  def test_full_title_without_format_string
+    assert_equal_in_controller("Welcome!") do
+      self.full_title = "Welcome!"
+      title("My Site")
+    end
+  end
+
+  def test_full_title_with_format_string
+    assert_equal_in_controller("Welcome to My Site!") do
+      self.full_title = "Welcome to %s!"
+      title("My Site")
+    end
+  end
+
+  def test_full_title_without_suffix_without_format_string
+    assert_equal_in_controller("Welcome") do
+      self.full_title = "Welcome"
+      title
+    end
+  end
+
+  def test_full_title_without_suffix_with_format_string
+    assert_equal_in_controller("Welcome to %s") do
+      self.full_title = "Welcome to %s"
+      title
+    end
+  end
+
+  def test_full_title_with_percentage_sign_and_suffix
+    assert_raises(ArgumentError) do
+      assert_equal_in_controller("100% French bulldogs") do
+        self.full_title = "100% French bulldogs"
+        title("My Site")
+      end
+    end
+    assert_nothing_raised do
+      assert_equal_in_controller("100% French bulldogs") do
+        self.full_title = "100%% French bulldogs"
+        title("My Site")
+      end
+    end
+  end
+
+  def test_full_title_with_percentage_sign_and_no_suffix
+    assert_equal_in_controller("100% French bulldogs") do
+      self.full_title = "100% French bulldogs"
+      title
+    end
+  end
+
+  def test_full_title_escapes_html
+    assert_equal_in_controller("&lt;b&gt;ad") do
+      self.full_title = "<b>ad"
+      title("My Site")
+    end
+  end
+
+
+  def test_combining_title_and_full_title
+    assert_equal_in_controller(["Welcome to My Site!", "Welcome"]) do
+      self.title = "Welcome"
+      self.full_title = "Welcome to %s!"
+      [title("My Site"), title]
+    end
+  end
+
+
+  def test_no_title_set_in_development
+    Rails.is_dev = true
+    assert_equal_in_controller([TitleHelpers::HINT, TitleHelpers::HINT]) do
+      [title("My Site"), title]
+    end
+  end
+
+  def test_no_title_set_in_non_development
+    Rails.is_dev = false
+    assert_equal_in_controller(["My Site", ""]) do
+      [title("My Site"), title]
+    end
+  end
+
+end

data/title_helpers.gemspec

@@ -0,0 +1,16 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/title_helpers/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Henrik Nyh"]
+  gem.email         = ["henrik@nyh.se"]
+  gem.summary       = %q{Rails title helpers.}
+  gem.homepage      = "https://github.com/henrik/title_helpers"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "title_helpers"
+  gem.require_paths = ["lib"]
+  gem.version       = TitleHelpers::VERSION
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: title_helpers
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Henrik Nyh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-17 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- henrik@nyh.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.markdown
+- Rakefile
+- TODO.tasks
+- init.rb
+- lib/title_helpers.rb
+- lib/title_helpers/version.rb
+- pkg/title_helpers-0.0.1.gem
+- test/title_helpers_test.rb
+- title_helpers.gemspec
+homepage: https://github.com/henrik/title_helpers
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Rails title helpers.
+test_files:
+- test/title_helpers_test.rb