sitemap_generator 2.1.8 → 2.2.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ./
   specs:
-    sitemap_generator (2.1.8)
+    sitemap_generator (2.2.1)
 
 GEM
   remote: http://rubygems.org/

data/README.md

@@ -26,6 +26,8 @@ Does your website use SitemapGenerator to generate Sitemaps?  Where would you be
 Changelog
 -------
 
+- v2.2.1: Support adding new search engines to ping and modifying the default search engines.
+          Allow the URL of the sitemap index to be passed as an argument to `ping_search_engines`.  See **Pinging Search Engines**.
 - v2.1.8: Extend and improve Video Sitemap support.  Include sitemap docs in the README, support all element attributes, properly format values.
 - v2.1.7: Improve format of float priorities; Remove Yahoo from ping - the Yahoo
           service has been shut down.
@@ -57,41 +59,29 @@ Those who knew him know what an amazing guy he was, and what an excellent Rails
 
 The canonical repository is now: [http://github.com/kjvarga/sitemap_generator][canonical_repo]
 
-Install for Rails
+Install
 =======
 
-Rails 3
--------
+Rails
+-----
 
-Add the gem to your `Gemspec`:
+Add the gem to your `Gemfile`:
 
     gem 'sitemap_generator'
 
-Then run `bundle`.
-
-Rails 2 Gem
---------
-
-1.  Follow the Rails 3 install if you are using a `Gemfile`.
-
-    If you are not using a `Gemfile` add the gem to your `config/environment.rb` configuration block with:
-
-        config.gem 'sitemap_generator'
+Alternatively, if you are not using a `Gemfile` add the gem to your `config/environment.rb` file config block:
 
-    Then run `rake gems:install`.
+    config.gem 'sitemap_generator'
 
-2. Include the gem's Rake tasks in your `Rakefile`:
+**Rails 1 or 2 only**, add the following code to your `Rakefile` to include the gem's Rake tasks in your project (Rails 3 does this for you automatically, so this step is not necessary):
 
-        begin
-          require 'sitemap_generator/tasks'
-        rescue Exception => e
-          puts "Warning, couldn't load gem tasks: #{e.message}! Skipping..."
-        end
-
-Rails 2 Plugin
-----------
+    begin
+      require 'sitemap_generator/tasks'
+    rescue Exception => e
+      puts "Warning, couldn't load gem tasks: #{e.message}! Skipping..."
+    end
 
-Run `script/plugin install git://github.com/kjvarga/sitemap_generator.git` from your application's root directory.
+<i>If you would prefer to install as a plugin (deprecated) don't do any of the above.  Simply run `script/plugin install git://github.com/kjvarga/sitemap_generator.git` from your application root directory.</i>
 
 Getting Started
 ======
@@ -107,11 +97,32 @@ Run `rake sitemap:refresh` as needed to create or rebuild your sitemap files.  S
 
 **To disable all non-essential output from `rake` run the tasks passing a `-s` option.**  For example: `rake -s sitemap:refresh`.
 
-Search Engine Notification
+Pinging Search Engines
 -----
 
 Using `rake sitemap:refresh` will notify major search engines to let them know that a new sitemap is available (Google, Bing, Ask, SitemapWriter).  To generate new sitemaps without notifying search engines (for example when running in a local environment) use `rake sitemap:refresh:no_ping`.
 
+If you want to customize the hash of search engines you can access it at:
+
+    SitemapGenerator::Sitemap.search_engines
+
+Usually you would be adding a new search engine to ping.  In this case you can modify the `search_engines` hash directly.  This ensures that when `SitemapGenerator::Sitemap.ping_search_engines` is called your new search engine will be included.
+
+If you are calling `ping_search_engines` manually (for example if you have to wait some time or perform a custom action after your sitemaps have been regenerated) then you can pass you new search engine directly in the call as in the following example:
+
+    SitemapGenerator::Sitemap.ping_search_engines(:newengine => 'http://newengine.com/ping?url=%s')
+
+The key gives the name of the search engine as a string or symbol and the value is the full URL to ping with a string interpolation that will be replaced by the CGI escaped sitemap index URL.  If you have any literal percent characters in your URL you need to escape them with `%%`.
+
+If you are calling `SitemapGenerator::Sitemap.ping_search_engines` from outside of your sitemap config file then you will need to set `SitemapGenerator::Sitemap.default_host` and any other options that you set in your sitemap config which affect the location of the sitemap index file.  For example:
+
+    SitemapGenerator::Sitemap.default_host = 'http://example.com'
+    SitemapGenerator::Sitemap.ping_search_engines
+
+Alternatively you can pass in the full URL to your sitemap index in which case we would have just the following:
+
+    SitemapGenerator::Sitemap.ping_search_engines('http://example.com/sitemap_index.xml.gz')
+
 Crontab
 -----
 

data/VERSION

@@ -1 +1 @@
-2.1.8
+2.2.1

data/lib/sitemap_generator/link_set.rb

@@ -82,14 +82,17 @@ module SitemapGenerator
     #
     # * <tt>:sitemaps_namer</tt> - A +SitemapNamer+ instance for generating the sitemap names.
     #
-    # * <tt>include_index</tt> - Boolean.  Whether to <b>add a link to the sitemap index<b>
+    # * <tt>:include_index</tt> - Boolean.  Whether to <b>add a link to the sitemap index<b>
     #   to the current sitemap.  This points search engines to your Sitemap Index to
     #   include it in the indexing of your site.  Default is `true`.  Turned off when
     #  `sitemaps_host` is set or within a `group()` block.
     #
-    # * <tt>include_root</tt> - Boolean.  Whether to **add the root** url i.e. '/' to the
+    # * <tt>:include_root</tt> - Boolean.  Whether to **add the root** url i.e. '/' to the
     #   current sitemap.  Default is `true`.  Turned off within a `group()` block.
     #
+    # * <tt>:search_engines</tt> - Hash.  A hash of search engine names mapped to
+    #   ping URLs.  See ping_search_engines.
+    #
     # * <tt>:verbose</tt> - If +true+, output a summary line for each sitemap and sitemap
     #   index that is created.  Default is +false+.
     def initialize(options={})
@@ -97,7 +100,13 @@ module SitemapGenerator
         :include_root => true,
         :include_index => true,
         :filename => :sitemap,
-        :verbose => false
+        :verbose => false,
+        :search_engines => {
+          :google         => "http://www.google.com/webmasters/sitemaps/ping?sitemap=%s",
+          :ask            => "http://submissions.ask.com/ping?sitemap=%s",
+          :bing           => "http://www.bing.com/webmaster/ping.aspx?siteMap=%s",
+          :sitemap_writer => "http://www.sitemapwriter.com/notify.php?crawler=all&url=%s"
+        }
       })
       options.each_pair { |k, v| instance_variable_set("@#{k}".to_sym, v) }
 
@@ -182,23 +191,51 @@ module SitemapGenerator
       @group
     end
 
-    # Ping search engines.
+    # Ping search engines to notify them of updated sitemaps.
+    #
+    # Search engines are already notified for you if you run `rake sitemap:refresh`.
+    # If you want to ping search engines separately to your sitemap generation, run
+    # `rake sitemap:refresh:no_ping` and then run a rake task or script
+    # which calls this method as in the example below.
+    #
+    # == Arguments
+    # * sitemap_index_url - The full URL to your sitemap index file.
+    #   If not provided the location is based on the `host` you have
+    #   set and any other options like your `sitemaps_path`.  The URL
+    #   will be CGI escaped for you when included as part of the
+    #   search engine ping URL.
+    #
+    # == Options
+    # A hash of one or more search engines to ping in addition to the
+    # default search engines.  The key is the name of the search engine
+    # as a string or symbol and the value is the full URL to ping with
+    # a string interpolation that will be replaced by the CGI escaped sitemap
+    # index URL.  If you have any literal percent characters in your URL you
+    # need to escape them with `%%`.  For example if your sitemap index URL
+    # is `http://example.com/sitemap_index.xml.gz` and your
+    # ping url is `http://example.com/100%%/ping?url=%s`
+    # then the final URL that is pinged will be `http://example.com/100%/ping?url=http%3A%2F%2Fexample.com%2Fsitemap_index.xml.gz`
+    #
+    # == Examples
+    #
+    # Both of these examples will ping the default search engines in addition to `http://superengine.com/ping?url=http%3A%2F%2Fexample.com%2Fsitemap_index.xml.gz`
+    #
+    #   SitemapGenerator::Sitemap.host('http://example.com/')
+    #   SitemapGenerator::Sitemap.ping_search_engines(:super_engine => 'http://superengine.com/ping?url=%s')
+    #
+    # Is equivalent to:
     #
-    # @see http://en.wikipedia.org/wiki/Sitemap_index
-    def ping_search_engines
+    #   SitemapGenerator::Sitemap.ping_search_engines('http://example.com/sitemap_index.xml.gz', :super_engine => 'http://superengine.com/ping?url=%s')
+    def ping_search_engines(*args)
+      engines = args.last.is_a?(Hash) ? args.pop : {}
+      index_url = CGI.escape(args.shift || sitemap_index_url)
+
       require 'open-uri'
       require 'timeout'
 
-      sitemap_index_url = CGI.escape(sitemap_index.location.url)
-      search_engines = {
-        :google         => "http://www.google.com/webmasters/sitemaps/ping?sitemap=#{sitemap_index_url}",
-        :ask            => "http://submissions.ask.com/ping?sitemap=#{sitemap_index_url}",
-        :bing           => "http://www.bing.com/webmaster/ping.aspx?siteMap=#{sitemap_index_url}",
-        :sitemap_writer => "http://www.sitemapwriter.com/notify.php?crawler=all&url=#{sitemap_index_url}"
-      }
-
       puts "\n" if verbose
-      search_engines.each do |engine, link|
+      search_engines.merge(engines).each do |engine, link|
+        link = link % index_url
         begin
           Timeout::timeout(10) {
             open(link)
@@ -221,16 +258,21 @@ module SitemapGenerator
       @sitemaps_host || @default_host
     end
 
-    # Lazy-initialize a sitemap instance when it's accessed
+    # Lazy-initialize a sitemap instance and return it.
     def sitemap
       @sitemap ||= SitemapGenerator::Builder::SitemapFile.new(sitemap_location)
     end
 
-    # Lazy-initialize a sitemap index instance when it's accessed
+    # Lazy-initialize a sitemap index instance and return it.
     def sitemap_index
       @sitemap_index ||= SitemapGenerator::Builder::SitemapIndexFile.new(sitemap_index_location)
     end
 
+    # Return the full url to the sitemap index file.
+    def sitemap_index_url
+      sitemap_index.location.url
+    end
+
     def finalize!
       finalize_sitemap!
       finalize_sitemap_index!
@@ -414,6 +456,20 @@ module SitemapGenerator
         self.sitemap_index_namer = SitemapGenerator::SitemapIndexNamer.new("#{@filename}_index")
       end
 
+      # Set the search engines hash to a new hash of search engine names mapped to
+      # ping URLs (see ping_search_engines).  If the value is nil it is converted
+      # to an empty hash.
+      # === Example
+      # <tt>search_engines = { :google => "http://www.google.com/webmasters/sitemaps/ping?sitemap=%s" }</tt>
+      def search_engines=(value)
+        @search_engines = value || {}
+      end
+
+      # Return the hash of search engines.
+      def search_engines
+        @search_engines || {}
+      end
+
       # Set the namer to use when generating SitemapFiles (does not apply to the
       # SitemapIndexFile)
       def sitemaps_namer=(value)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: sitemap_generator
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 5
   prerelease: 
   segments: 
   - 2
+  - 2
   - 1
-  - 8
-  version: 2.1.8
+  version: 2.2.1
 platform: ruby
 authors: 
 - Karl Varga
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-16 00:00:00 -08:00
+date: 2012-01-07 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency