RubyGems - happy-titles - Versions diffs - 0.9.0 - Mend

happy-titles 0.9.0

Files changed (10) hide show

data/.git_ignore ADDED Viewed

	@@ -0,0 +1 @@
1	+ .DS_Store

data/MIT-LICENCE ADDED Viewed

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Andy Pearson
+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.markdown ADDED Viewed

@@ -0,0 +1,139 @@
+# Happy Titles!
+A simple Rails plugin which adds an easy (and cheerful) way to handle page titles in your layouts.
+## Getting Started
+### Install the Plugin
+	script/plugin install git://github.com/andypearson/happy-titles.git
+### Set the Defaults
+Create a new file in `config/initializers` called `happy_titles.rb` or something else which makes sense!
+In this new file, add the following lines to set the default Site and Tagline.
+	ActionView::Base.happy_title_setting(:site, 'Your Site')
+	ActionView::Base.happy_title_setting(:tagline, 'Your witty but informative tagline')
+### Update your Layout
+In the layout where you want to display your title add the following call to the Happy Titles helper method.
+	<%= happy_title %>
+The header element of your layout might end up looking something like:
+	<head>
+		<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+		<%= happy_title %>
+	</head>
+Notice you don't need to wrap the helper in a `<title>` element, this is done for you.
+### Set the Title in your Views
+In each of your views call the `title` method to set the title for that page.
+	<% title 'Your very first Happy Title!' %>
+### See your Titles!
+Given the above settings, let's have a look at the output you will receive when you call the `happy_title` method in your layouts.
+On pages where the title has not been set you will see...
+	<title>Your Site | Your witty but informative tagline</title>
+...and on pages where the title _has_ been set you will see...
+	<title>Your very first Happy Title! | Your Site</title>
+That really is all there is to setting up and using Happy Titles!
+## Customising the Title Templates
+### Intro
+You have already seen how to set up and use Happy Titles, now let's take a look at how to customise the individual title templates.
+In all of the following examples I am going to assume the same defaults that are set up in the Set the Defaults section of this Readme.
+Before we have a look at that, let's have a look at the **placeholders** you can use. These placeholders will be replaced with the real content when the title is rendered.
+	:site 		-> 'Your Site'
+	:tagline 	-> 'Your witty but informative tagline'
+	:title 		-> Will become 'Your very first Happy Title!' or :tagline if a page title has not been set
+Now let's have a look at the default templates.
+	':site | :title'	-> Is used when there is no title set: 'Your Site | Your witty but informative tagline'
+	':title | :site'	-> Is used when there IS a title set: 'Your very first Happy Title! | Your Site'
+You can change the default templates by using the following setting in `config/initializers/happy_titles.rb`
+	# The first param sets the name of the template and takes a symbol
+	# The second param is the template to use when there is no title set
+	# The third param is the template to use when there is a title set
+	ActionView::Base.happy_title_template(:default, '[:site]', '[:site] :title')
+Then when you render your titles you will see the following
+	<title>[Your Site]</title> <!-- when there is no title -->
+	<title>[Your Site] Your very first Happy Title!</title> <!-- when the title is set -->
+### Adding Additional Templates
+As well as changing the default template, you can also add new templates and then use those when you need a different title format in a different layout.
+	# config/initializers/happy_titles.rb
+	ActionView::Base.happy_title_template(:extra, '++ :site ++', '++ :site ++ :title ++')
+Then in your layout, you can use the following to call the extra template.
+	<%= happy_title :extra %>
+And you will get the following output, as you probably would of guessed by now!
+	<title>++ Your Site ++</title> <!-- when there is no title -->
+	<title>++ Your Site ++ Your very first Happy Title! ++</title> <!-- when the title is set -->
+You can add as many additional title templates as you need!
+One final thing to mention, you can create templates that just have one format. So...
+	# config/initializers/happy_titles.rb
+	ActionView::Base.happy_title_template(:single, ':site (:title)')
+	# In your layout
+	<%= happy_title :single %>
+	# Output
+	<title>Your Site (Your witty but informative tagline)</title> <!-- when there is no title -->
+	<title>Your Site (Your very first Happy Title!)</title> <!-- when the title is set -->
+## Other Things...
+### Why Use Happy Titles?
+Happy Titles is a simple way to use multiple title formats in the same app. In my case, the app I was working on at the time required different title formats for public and private pages, and this is the best way I could think of managing that requirement in a suitably DRY fashion.
+### Why on earth is it called Happy Titles?
+What can I say, I was in a good mood when I started writing the plugin and I couldn't think of anything better to call it!
+### Inspiration and Thanks
+When it came to actually writing the plugin I studied the [Headliner plugin][hl] to see how that was done and got some ideas on how to set up my specs. I also want to thank [Justin French][jf] for his help when I created some small patches for his [Formtastic][ft] plugin. He made me realise that even though I don't have a lot of experience I can still help out the open source community. Please take a look at [Formtastic][ft] for a great way to make semantic forms really easy in Rails. Thanks also to all the clever chaps working on GitHub, I don't think I would of ever had the oomph to release this if GitHub wasn't here to make it so wonderfully easy and fun!
+### Please give me some feedback
+This plugin was written as an experiment and a learning experience. I am a relative newcomer to the world of Ruby, Rails and Github so if you have 5 Minutes to skim read the code and maybe suggest something I could do better in the future then please leave a comment and I will be very grateful of the feedback, thanks in advance!
+[hl]: http://github.com/mokolabs/headliner/tree/master "mokolabs Headliner on GitHub"
+[jf]: http://justinfrench.com/ "Justin French"
+[ft]: http://github.com/justinfrench/formtastic/tree/master "justinfrench Formtastic on GitHub"

data/Rakefile ADDED Viewed

@@ -0,0 +1,21 @@
+require 'rake'
+require 'spec/rake/spectask'
+desc 'Test the happy-titles plugin.'
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ["-c"]
+end
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "happy-titles"
+    gemspec.summary = "A simple way to handle page titles in your layouts."
+    gemspec.email = "andy@andy-pearson.com"
+    gemspec.homepage = "http://github.com/andypearson/happy-titles"
+    gemspec.authors = ["Andy Pearson"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION ADDED Viewed

	@@ -0,0 +1 @@
1	+ 0.9.0

data/init.rb ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ require File.dirname(__FILE__) + '/lib/happy_titles'
2	+ ActionView::Base.send(:include, HappyTitles)

data/lib/happy_titles.rb ADDED Viewed

@@ -0,0 +1,61 @@
+module HappyTitles
+  attr_accessor :page_title
+  @@happy_title_settings = {
+    :site => 'My Site',
+    :tagline => 'My short, descriptive and witty tagline',
+    :templates => {
+      :default => [':site | :title', ':title | :site']
+    }
+  }
+  def happy_title(template_key = :default)
+    content_tag(:title, render_title_template(template_key))
+  end
+  def title(page_title = nil)
+    if page_title
+      @page_title = h(page_title.gsub(/<\/?[^>]*>/, '')) if page_title
+    else
+      @page_title || ''
+    end
+  end
+  def self.included(base)
+    base.class_eval do
+      cattr_accessor :happy_title_settings
+      def self.happy_title_template(template_key, format, additional_format = nil)
+        template = [format]
+        template << additional_format if additional_format
+        @@happy_title_settings[:templates][template_key] = template
+      end
+      def self.happy_title_setting(key, value)
+        @@happy_title_settings[key] = value
+      end
+    end
+  end
+  private
+    def render_title_template(template_key)
+      key = (@page_title && @@happy_title_settings[:templates][template_key][1]) ? 1 : 0
+      substitute_placeholders(@@happy_title_settings[:templates][template_key][key])
+    end
+    def substitute_placeholders(template)
+      title = template
+      title = title.gsub(':title', title_text)
+      title = title.gsub(':site', @@happy_title_settings[:site])
+      title = title.gsub(':tagline', @@happy_title_settings[:tagline])
+    end
+    def title_text
+      (@page_title) ? @page_title : @@happy_title_settings[:tagline]
+    end
+end

data/spec/happy_titles_spec.rb ADDED Viewed

@@ -0,0 +1,274 @@
+require File.dirname(__FILE__) + '/spec_helper'
+describe 'Happy Titles!' do
+  before do
+    @view = ActionView::Base.new
+  end
+  describe 'after loading the plugin' do
+    it "should be mixed into ActionView::Base" do
+      ActionView::Base.included_modules.include?(HappyTitles).should be_true
+    end
+    it 'should respond to happy_title_settings class variable' do
+      ActionView::Base.happy_title_settings.should be_a(Hash)
+    end
+    it 'should respond to happy_title_template class method' do
+      ActionView::Base.should respond_to(:happy_title_template)
+    end
+    it 'should respond to happy_title_setting class method' do
+      ActionView::Base.should respond_to(:happy_title_setting)
+    end
+    it 'should respond to happy_title helper' do
+      @view.should respond_to(:happy_title)
+    end
+    it 'should respond to title helper' do
+      @view.should respond_to(:title)
+    end
+  end
+  describe 'default settings' do
+    it 'should have a default site setting' do
+      ActionView::Base.happy_title_settings[:site].should == 'My Site'
+    end
+    it 'should have a default tagline setting' do
+      ActionView::Base.happy_title_settings[:tagline].should == 'My short, descriptive and witty tagline'
+    end
+    describe 'templates' do
+      it 'should have a list of templates' do
+        ActionView::Base.happy_title_settings[:templates].should be_a(Hash)
+      end
+      it 'should have a default template' do
+        ActionView::Base.happy_title_settings[:templates][:default].should be_an(Array)
+      end
+      it 'should have a default template for when the page title is not set' do
+        ActionView::Base.happy_title_settings[:templates][:default][0].should == ':site | :title'
+      end
+      it 'should have a default template for when the page title is set' do
+        ActionView::Base.happy_title_settings[:templates][:default][1].should == ':title | :site'
+      end
+    end
+  end
+  describe 'custom settings' do
+    before do
+      @default_site = ActionView::Base.happy_title_settings[:site].dup
+      @default_tagline = ActionView::Base.happy_title_settings[:tagline].dup
+    end
+    after do
+      ActionView::Base.happy_title_setting(:site, @default_site)
+      ActionView::Base.happy_title_setting(:tagline, @default_tagline)
+    end
+    it 'should be able to change the default site' do
+      ActionView::Base.happy_title_setting(:site, 'My Custom Site')
+      ActionView::Base.happy_title_settings[:site].should == 'My Custom Site'
+    end
+    it 'should be able to change the default tagline' do
+      ActionView::Base.happy_title_setting(:tagline, 'My very custom tagline')
+      ActionView::Base.happy_title_settings[:tagline].should == 'My very custom tagline'
+    end
+    describe 'templates' do
+      before do
+        @default_templates = ActionView::Base.happy_title_settings[:templates].dup
+      end
+      after do
+        ActionView::Base.happy_title_settings[:templates] = @default_templates
+      end
+      it 'should be able to change the default templates' do
+        ActionView::Base.happy_title_template(:default, '[:site] :title', ':title at :site')
+        ActionView::Base.happy_title_settings[:templates][:default].should == ['[:site] :title', ':title at :site']
+      end
+      it 'should be able to add a new template' do
+        ActionView::Base.happy_title_template(:new_template, '[:site] :title', ':title at :site')
+        ActionView::Base.happy_title_settings[:templates][:new_template].should == ['[:site] :title', ':title at :site']
+      end
+      it 'should be able to add a new template with one format' do
+        ActionView::Base.happy_title_template(:new_template, '[:site] :title')
+        ActionView::Base.happy_title_settings[:templates][:new_template].should == ['[:site] :title']
+      end
+    end
+  end
+  describe 'setting the title' do
+    it 'should set the title' do
+      @view.title("Happy Title!")
+      @view.send(:page_title).should == "Happy Title!"
+    end
+    it 'should overwrite a privously set title' do
+      @view.title('First Page Title')
+      @view.title('Second Page Title')
+      @view.page_title.should eql("Second Page Title")
+    end
+    it 'should strip HTML elements from the title' do
+      @view.title('<strong>Cat is</strong>!')
+      @view.page_title.should eql('Cat is!')
+    end
+    it 'should escape special entities in the title element' do
+      @view.title('This & That')
+      @view.page_title.should eql('This &amp; That')
+    end
+    it 'should handle a mix of HTML and special entities' do
+      @view.title('<strong>This & That</strong>')
+      @view.page_title.should eql('This &amp; That')
+    end
+  end
+  describe 'reading the title method' do
+    it 'should return an empty string when called with no args' do
+      @view.title.should == ''
+    end
+    it 'should return @page_title when @page_title is set and is called with no args' do
+      @view.title('Happy Title!')
+      @view.title.should == 'Happy Title!'
+    end
+    it 'should not set the title when called with no args' do
+      @view.title
+      @view.happy_title.should have_tag('title', 'My Site | My short, descriptive and witty tagline')
+    end
+  end
+  describe 'showing the title' do
+    it 'should output a valid title element' do
+      @view.happy_title.should have_tag('title')
+    end
+    describe 'with default settings' do
+      it 'should use the default template when the page title is not set' do
+        @view.happy_title.should have_tag('title', 'My Site | My short, descriptive and witty tagline')
+      end
+      it 'should use the default template when the page title is set' do
+        @view.title('Example Page Title')
+        @view.happy_title.should have_tag('title', 'Example Page Title | My Site')
+      end
+    end
+    describe 'with custom settings' do
+      before do
+        @default_site = ActionView::Base.happy_title_settings[:site].dup
+        @default_tagline = ActionView::Base.happy_title_settings[:tagline].dup
+      end
+      after do
+        ActionView::Base.happy_title_setting(:site, @default_site)
+        ActionView::Base.happy_title_setting(:tagline, @default_tagline)
+      end
+      it 'should render the title with a custom site' do
+        ActionView::Base.happy_title_setting(:site, 'Custom Site')
+        @view.happy_title.should have_tag('title', 'Custom Site | My short, descriptive and witty tagline')
+      end
+      it 'should render the title with a custom tagline' do
+        ActionView::Base.happy_title_setting(:tagline, 'My custom tagline...')
+        @view.happy_title.should have_tag('title', 'My Site | My custom tagline...')
+      end
+      describe '(templates)' do
+        before do
+          @default_templates = ActionView::Base.happy_title_settings[:templates].dup
+        end
+        after do
+          ActionView::Base.happy_title_settings[:templates] = @default_templates
+        end
+        describe 'template with a single format' do
+          before do
+            ActionView::Base.happy_title_template(:default, '[:site] :title')
+          end
+          it 'should render the template when the title is not set' do
+            @view.happy_title.should have_tag('title', '[My Site] My short, descriptive and witty tagline')
+          end
+          it 'should render the template when the title is set' do
+            @view.title('Another example title')
+            @view.happy_title.should have_tag('title', '[My Site] Another example title')
+          end
+        end
+        describe 'template with two formats' do
+          before do
+            ActionView::Base.happy_title_template(:default, '[:site] :title', ':title at :site')
+          end
+          it 'should render the template when the title is not set' do
+            @view.happy_title.should have_tag('title', '[My Site] My short, descriptive and witty tagline')
+          end
+          it 'should render the alternate template when the title is set' do
+            @view.title('Would of thought these titles would of got a bit funnier by now')
+            @view.happy_title.should have_tag('title', 'Would of thought these titles would of got a bit funnier by now at My Site')
+          end
+        end
+        describe 'using a custom template' do
+          before do
+            ActionView::Base.happy_title_template(:custom, '++:site++', ':title ++:site++')
+          end
+          it 'should render a custom template when the title is not set' do
+            @view.happy_title(:custom).should have_tag('title', '++My Site++')
+          end
+          it 'should render a custom template when the title is not set' do
+            @view.title('Fraid not, I got nothing')
+            @view.happy_title(:custom).should have_tag('title', 'Fraid not, I got nothing ++My Site++')
+          end
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb ADDED Viewed

@@ -0,0 +1,25 @@
+# coding: utf-8
+require 'rubygems'
+gem 'activesupport', '2.3.8'
+gem 'actionpack', '2.3.8'
+require 'active_support'
+require 'action_pack'
+require 'action_view'
+require 'action_controller'
+gem 'rspec', '>= 1.2.6'
+gem 'rspec-rails', '>= 1.2.6'
+gem 'hpricot', '>= 0.6.1'
+gem 'rspec_tag_matchers', '>= 1.0.0'
+require 'rspec_tag_matchers'
+require File.join(File.dirname(__FILE__), "../lib/happy_titles")
+Spec::Runner.configure do |config|
+  config.include(RspecTagMatchers)
+end
+ActionView::Base.class_eval do
+  include HappyTitles
+end

metadata ADDED Viewed

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: happy-titles
+version: !ruby/object:Gem::Version
+  prerelease: false
+  segments:
+  - 0
+  - 9
+  - 0
+  version: 0.9.0
+platform: ruby
+authors:
+- Andy Pearson
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2010-06-01 00:00:00 +01:00
+default_executable:
+dependencies: []
+description:
+email: andy@andy-pearson.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.markdown
+files:
+- .git_ignore
+- MIT-LICENCE
+- README.markdown
+- Rakefile
+- VERSION
+- init.rb
+- lib/happy_titles.rb
+- spec/happy_titles_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/andypearson/happy-titles
+licenses: []
+post_install_message:
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      segments:
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      segments:
+      - 0
+      version: "0"
+requirements: []
+rubyforge_project:
+rubygems_version: 1.3.6
+signing_key:
+specification_version: 3
+summary: A simple way to handle page titles in your layouts.
+test_files:
+- spec/happy_titles_spec.rb
+- spec/spec_helper.rb