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

happy-titles 0.9.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 (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