RubyGems - seo_helper - Versions diffs - 0.1.0 → 1.0.1 - Mend

seo_helper 0.1.0 → 1.0.1

Files changed (9) hide show

data/README.markdown +258 -0
data/lib/seo_helper/configuration.rb +28 -0
data/lib/seo_helper/engine.rb +5 -1
data/lib/seo_helper/format.rb +9 -0
data/lib/seo_helper/helper.rb +76 -22
data/lib/seo_helper/railtie.rb +5 -1
data/lib/seo_helper/version.rb +1 -1
data/lib/seo_helper.rb +12 -0
metadata +7 -4

data/README.markdown ADDED Viewed

@@ -0,0 +1,258 @@
+# SeoHelper
+SeoHelper is a set of helpers for rendering page-specific `<title>` tag, common `<meta />` tags and `<link rel='image_src' />` tag.
+It contains not only a set of `tag()` helper wrappers, but can also help you doing things like
+* specifying **title**, **description** and **image_url** for the current page, and render them with `<title>` and corresponding `meta`-tags or `link`-tags
+* automatically append **page number** and **site name** into the title (both formats are customizable)
+Pull requests are welcome.
+# Usage
+Add this to your Gemfile:
+    gem 'seo_helper', '~> 1.0'
+If you want to use the edge version on Github, specify the `:git` option.
+    gem 'seo_helper', '~> 1.0', :git => 'git://github.com/techbang/seo_helper.git'
+And run
+    bundle install
+to install this plug-in.
+After installation, add `config/initializers/seo_helper.rb` into your Rails application, specifying the basic configuration like this:
+```ruby
+SeoHelper.configure do |config|
+  config.site_name = "My Awesome Web Application"
+end
+```
+Please specify at least the `site_name`, or SeoHelper will take the class name of your Rails application as default.
+Don't forget to restart your Rails application.
+# Page Title Rendering
+It's always been a complex job to render a pretty title and put it in both the `<title>` tag and the title `meta` tag.  With SeoHelper, you can easily set and render the title text.
+## Rendering the Default Title in Layout
+First, put this in your layout file, between `<head>` and `</head>`:
+```ruby
+<%= render_page_title_tag %>
+```
+You can replace the hard-coded `<title>` tag with this helper.
+Now visit any page of your application, you'll see that the browser's title will be the `site_name` that you specified (or the application's class name if not specified).
+## Specifying the Title
+To specify the title of current page in an controller action, for example, in the `Articles#show` action, use `set_page_title`
+```ruby
+def show
+  # ...
+  set_page_title @article.title
+end
+```
+Now visit any article, you'll see the title becomes
+    Article Title | My Awesome Web Application
+The `site_name` is still a part of the title text.
+If `params[:page]` exists it'll automatically be appended to the title.  For example, in `Articles#index`, when you visit the 2nd page, you'll see the title becomes
+    Article Index - Page 2 | My Awesome Web Application
+# Rendering SEO-oriented Tags
+For SEO, you may want to put some `<meta>` tags and `<link rel="image-src" />` tag in your webpage.  With SeoHelper, you can easily do these things.
+## Rendering Meta Tags for Title, Description and Keywords
+First, put this in your layout file, between `<head>` and `</head>`:
+```erb
+<%= render_page_title_meta_tag %><%# This might be unnecessary %>
+<%= render_page_description_meta_tag %>
+<%= render_page_keywords_meta_tag %>
+```
+You can replace the hard-coded `<meta>` tags with these helpers.
+To specify the description and keywords of current page in an controller action, for example, in the `Articles#show` action, use `set_page_description`
+```ruby
+def show
+  # ...
+  set_page_title       @article.title   # same as <title> tag
+  set_page_description @article.excerpt # or @article.content.truncate(100)
+  set_page_keywords    @article.tags    # or @article.keywords
+end
+```
+Now visit any article, and open it's source, you'll see these meta tags:
+```html
+<meta name="title" content="Article Title | My Awesome Web Application" />
+<meta name="description" content="Lorem ipsum dolor sit amet, ..." />
+<meta name="keywords" content="faketext,lorem,ipsum" />
+```
+If `set_pages_keywords` receives an array, it'll convert the array to a string joined with a single comma (`','`).
+## Rendering `<link rel="image_src" />` tag
+This tag tells search engine what the related image of this page is.  To render this tag, put `render_page_image_link_tag` in your layout file, between `<head>` and `</head>`:
+```ruby
+<%= render_page_image_link_tag %>
+```
+You can replace the hard-coded `<link rel="image_src" />` tag with this helper.
+To specify the title of current page in an controller action, for example, in the `Articles#show` action, use `set_page_image`
+```ruby
+def show
+  # ...
+  set_page_image @article.excerpt_image_url
+end
+```
+Now visit any article, and open it's source, you'll see this link tag:
+```html
+<link href="http://www.example.com/articles/123/the-excerpt-image.jpg" rel="image_src" />
+```
+## Re-use Page-Specific SEO Data in View
+Sometimes you may want to use the page title, description, keywords and the image url.  Say you're working with [OpenGraph Meta tags](http://developers.facebook.com/docs/opengraph/), you may re-use them in your view:
+```erb
+<meta property="og:title"       content="<%= page_title %>"/>
+<meta property="og:description" content="<%= page_description %>"/>
+<meta property="og:image"       content="<%= page_image %>"/>
+```
+You may also want to use our [OpenGraphHelper](https://github.com/techbang/open_graph_helper), too.
+## Blank Tags: Skipping Them or Not
+Sometimes you just want to skip SEO tags when their contents are empty.  This is the default behavior of SeoHelper, that is, if you've never `set_page_description` to something in a request flow, the meta description tag will not be rendered.
+If you want to force SeoHelper to render a default description meta tag, keywords meta tag, or image_src link tag, you can explicitly tell SeoHelper with configure block, in the initializer:
+```ruby
+SeoHelper.configure do |config|
+  # ...
+  config.skip_blank               = false
+  config.default_page_description = "This is a really really awesome website"
+  config.default_page_keywords    = "hello,world,yay"
+  config.default_page_image       = "http://www.example.com/title.png"
+end
+```
+Then, when page description, keywords or image was not specified, SeoHelper will fallback to default text.
+## Rendering SEO-oriented Tags Directly
+While SeoHelper provides `set_page_XXX` and `render_page_XXX_meta_tag` helper pairs, it is still possible to render these meta tags directly, with the corresponding `XXX_meta_tag` helpers, the `title_tag` helper and the `image_src_link_tag` helper.
+For example,
+```erb
+<%= title_tag("Hello! World") %>
+<%= description_meta_tag("Lorem ipsum dolor sit amet!") %>
+<%= image_src_link_tag("http://www.example.com/title.png") %>
+```
+yields
+```html
+<title>Hello! World</title>
+<meta name="description" content="Lorem ipsum dolor sit amet!" />
+<link rel="image_src" href="http://www.example.com/title.png" />
+```
+You can also add Site Name to the customized title, just put `true` as the second argument. For example, if you set `site_name` to `My Awesome Web Application`, then
+```erb
+<%= title_tag("Hello! World", true) %>
+```
+yields
+```html
+<title>Hello! World | My Awesome Web Application</title>
+```
+which applies the default format of site name in page title, and thus customizable (see below).
+# Customizing Page Title Format
+The page number format and site name format in a page title are customizable, via the configure block.  They're basically lambda blocks, and invoked dynamically during runtime.
+## Customizing Format of Page Number in Title
+The default format of Page Number in Title is:
+    Title - Page X | My Awesome Web Application
+Changing the page number format by specifying a new lambda block:
+```ruby
+SeoHelper.configure do |config|
+  config.pagination_formatter = lambda { |title, page_number| "#{title} - Page No.#{page_number}" }
+end
+```
+Now you'll get
+    Title - Page No.X | My Awesome Web Application
+as your page title.
+## Customizing Format of Site Name in TItle
+The default format of Site Name in Title is:
+    Title | My Awesome Web Application
+Changing the site name format by specifying a new lambda block:
+```ruby
+SeoHelper.configure do |config|
+  config.site_name_formatter  = lambda { |title, site_name|   "#{title} &laquo; #{site_name}" }
+end
+```
+Now you'll get
+    Title &laquo; My Awesome Web Application
+as your page title.
+# License
+This software is released under the MIT License.
+Copyright (c) 2011- Techbang
+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/lib/seo_helper/configuration.rb ADDED Viewed

@@ -0,0 +1,28 @@
+module SeoHelper
+  class Configuration
+    attr_accessor :site_name
+    attr_accessor :default_page_description
+    attr_accessor :default_page_keywords
+    attr_accessor :default_page_image
+    attr_accessor :skip_blank
+    attr_accessor :pagination_formatter
+    attr_accessor :site_name_formatter
+    def initialize
+      # Set default site_name according to the Rails application class name
+      self.site_name    = ::Rails.application.class.to_s.split("::").first
+      self.skip_blank   = true
+      self.default_page_description = ""
+      self.default_page_keywords    = ""
+      self.default_page_image       = ""
+      self.pagination_formatter = lambda {|title, page_number| "#{title} - Page #{page_number}" }
+      self.site_name_formatter  = lambda {|text, site_name|    "#{text} | #{site_name}"}
+    end
+  end
+end

data/lib/seo_helper/engine.rb CHANGED Viewed

@@ -1,9 +1,13 @@
 require "seo_helper/helper"
-module SeoImageHelper
+module SeoHelper
   class Engine < ::Rails::Engine
     initializer "seo_helper.view_helpers" do
       ActionView::Base.send :include, SeoHelper::Helper
     end
+    initializer "seo_helper.controller_helpers" do
+      ActionController::Base.send :include, SeoHelper::ControllerHelper
+    end
   end
 end

data/lib/seo_helper/format.rb ADDED Viewed

@@ -0,0 +1,9 @@
+module SeoHelper
+  def self.format_current_page(title, page_number)
+    self.configuration.pagination_formatter.call(title, page_number)
+  end
+  def self.format_site_name(text, site_name)
+    self.configuration.site_name_formatter.call(text, site_name)
+  end
+end

data/lib/seo_helper/helper.rb CHANGED Viewed

@@ -1,42 +1,96 @@
 module SeoHelper
   module Helper
-    def meta_title(title)
-      return nil if title.blank?
-      title = title + " | " + (SITE_NAME rescue "SITE_NAME")
-      tag(:meta, {:name => "title", :content => title})
+    # <title>...</title>
+    def title_tag(title, with_site_name=false)
+      title = SeoHelper.format_site_name(title, SeoHelper.configuration.site_name) if with_site_name == true
+      content_tag(:title, h(title), nil, false)  # option=nil, escape=false
     end
-    def meta_description(content, site_name = false)
-      return nil if content.blank?
-      content = content + " | " + (SITE_NAME rescue "SITE_NAME") if site_name
-      tag(:meta, { :name => "description", :content => strip_tags(content) }, true)
+    # <meta name="title" content="..." />
+    def title_meta_tag(title, with_site_name=false)
+      title = SeoHelper.format_site_name(title, SeoHelper.configuration.site_name) if with_site_name == true
+      tag(:meta, {:name => "title", :content => h(title)})
     end
-    def meta_keywords(word)
-      return nil if word.blank?
-      # word = word + (SITE_NAME rescue "SITE_NAME")
-      tag(:meta, {:name => "keywords", :content => word})
+    # <meta name="description" content="..." />
+    def description_meta_tag(content, with_site_name=false)
+      title = SeoHelper.format_site_name(title, SeoHelper.configuration.site_name) if with_site_name == true
+      # use String.new to avoid always (html_save == true) which makes h() inactive
+      content = h(String.new(strip_tags(content)))
+      tag(:meta, { :name => "description", :content => content })
     end
-    def render_rel_image(image_url)
-      return nil if image_url.blank?
-      tag(:link, {:rel => "image_src", :href => image_url})
+    # <meta name="keywords" content="..." />
+    def keywords_meta_tag(keywords)
+      keywords = keywords.join(',') if keywords.is_a? Array
+      tag(:meta, {:name => "keywords", :content => h(keywords)})
     end
-    def link_image(image_url)
-      return nil if image_url.blank?
-      tag(:link, { :rel => "image_src", :href => image_url }, true)
+    # <link rel="image_src" content="..." />
+    def image_src_link_tag(image_url)
+      tag(:link, { :rel => "image_src", :href => image_url })
     end
-    def link_favicon(ico_url = "/favicon.ico")
-      tag(:link, { :rel => "shortcut icon", :href => ico_url }, true)
+    # <meta name="robots" content="INDEX,FOLLOW" />
+    def robots_meta_tag(content = "INDEX,FOLLOW")
+      tag(:meta, { :name => "robots", :content => content })
     end
+    attr_reader :page_title, :page_description, :page_keywords, :page_image
-    def meta_robots(content = "INDEX,FOLLOW")
-      tag(:meta, { :name => "robots", :content => content }, true)
+    def render_page_title_tag
+      # fallback to site_name if @page_title has never been set
+      title_tag(page_title || SeoHelper.configuration.site_name)
+    end
+    def render_page_title_meta_tag
+      title_meta_tag(page_title || SeoHelper.configuration.site_name)
+    end
+    # @page_xxx |   skip_blank  | don't skip_blank
+    # ----------+---------------+-------------------
+    # present   |   @page_xxx   |  @page_xxx
+    # blank     |  (no output)  |  default_page_xxx
+    def render_page_description_meta_tag
+      return if SeoHelper.configuration.skip_blank && page_description.blank?
+      description_meta_tag(page_description || SeoHelper.configuration.default_page_description)
+    end
+    def render_page_keywords_meta_tag
+      return if SeoHelper.configuration.skip_blank && page_keywords.blank?
+      keywords_meta_tag(page_keywords || SeoHelper.configuration.default_page_keywords)
+    end
+    def render_page_image_link_tag
+      return if SeoHelper.configuration.skip_blank && page_image.blank?
+      image_src_link_tag(page_image || SeoHelper.configuration.default_page_image)
     end
   end
+  module ControllerHelper
+    # will also append current page number and the site name
+    def set_page_title(title)
+      if params[:page]
+        @page_title = SeoHelper.format_current_page(title, params[:page])
+      else
+        @page_title = title
+      end
+      @page_title = SeoHelper.format_site_name(@page_title, SeoHelper.configuration.site_name)
+    end
+    def set_page_description(description)
+      @page_description = description
+    end
+    def set_page_keywords(keywords)
+      @page_keywords = keywords
+    end
+    def set_page_image(image_src)
+      @page_image = image_src
+    end
+  end
 end

data/lib/seo_helper/railtie.rb CHANGED Viewed

@@ -1,9 +1,13 @@
 require "seo_helper/helper"
-module SeoImageHelper
+module SeoHelper
   class Railtie < Rails::Railtie
     initializer "seo_helper.view_helpers" do
       ActionView::Base.send :include, SeoHelper::Helper
     end
+    initializer "seo_helper.controller_helpers" do
+      ActionController::Base.send :include, SeoHelper::ControllerHelper
+    end
   end
 end

data/lib/seo_helper/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module SeoHelper
-  VERSION = "0.1.0"
+  VERSION = "1.0.1"
 end

data/lib/seo_helper.rb CHANGED Viewed

@@ -1,4 +1,11 @@
+require 'seo_helper/configuration'
+require 'seo_helper/format'
 module SeoHelper
+  class << self
+    attr_accessor :configuration
+  end
   module Rails
     if ::Rails.version < "3.1"
       require "seo_helper/railtie"
@@ -6,4 +13,9 @@ module SeoHelper
       require "seo_helper/engine"
     end
   end
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
 end

metadata CHANGED Viewed

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: seo_helper
 version: !ruby/object:Gem::Version
-  hash: 27
+  hash: 21
   prerelease:
   segments:
-  - 0
   - 1
   - 0
-  version: 0.1.0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors:
 - xdite
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2011-12-22 00:00:00 +08:00
+date: 2012-02-07 00:00:00 +08:00
 default_executable:
 dependencies: []
@@ -31,9 +31,12 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- README.markdown
 - Rakefile
 - lib/seo_helper.rb
+- lib/seo_helper/configuration.rb
 - lib/seo_helper/engine.rb
+- lib/seo_helper/format.rb
 - lib/seo_helper/helper.rb
 - lib/seo_helper/railtie.rb
 - lib/seo_helper/version.rb