para-seo_tools 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a34f864ccd5b3365f87eff521544ce23fe555c6a
-  data.tar.gz: 98b4747257ce0acd81643e9c0b101e9706fbadb5
+  metadata.gz: f4b8959221c49d287170b758d7dbe9a0e2bb291b
+  data.tar.gz: 2c9f4d8e455c31bf0f47c7c1cdb1dffdd54a571f
 SHA512:
-  metadata.gz: bf073b75a0b537fef122a1cec5614505b1e6e0ca0288f417a917bf68ffe015fd663de442fcde4fdda9d7de28791524e8be8acea01a5f9e0b098f318a5a9a9883
-  data.tar.gz: 6660839f153d03a48b1957aef6dc1118e8456957d3fc00e8fb729ad015ac921074eaa7c0633fdb6bd9bdd78505e39f5994dec455033bfe38e554150aad3683f3
+  metadata.gz: dd129c962571f25f126aeafed737ef17e86fb2e2ef73351bf1b416a4372c4a917f80b41017a614506001a2a2fe26ba829b7108e2675df715fe99015bea4ddc73
+  data.tar.gz: 0880f858c0a6db534a542182e456f46f126a2ce4271bef67fc19a7e62297fb1b1330b297b4278db6f435866bc564e280f631fcd71b61816ab1278e75989b1c07

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source 'http://rubygems.org'
 
 # Specify your gem's dependencies in seo_tools-para.gemspec
 gemspec

data/README.md

@@ -87,6 +87,166 @@ by default.
 page :posts, priority: 1, change_frequency: 'weekly'
 ```
 
+#### Default meta tag values
+
+The `page` method allows to define default data for seo_tools to use as default
+values for the title and description meta tags.
+
+For example, using your post title as default meta title and its excerpt as the
+default description meta tag value is as easy as :
+
+```ruby
+Posts.find_each do |post|
+  page :post, resource: post, defaults: { title: post.title, description: post.excerpt }
+end
+```
+
+#### Arbitrary scoping of pages
+
+SeoTools ensures your page identifiers are unique. This avoids duplicating pages
+and unwanted side effects. This identifier is generated with the first argument
+of the `#page` method (`:post` in our examples), and the id of the resource
+passed in the `:resource` argument, when present.
+
+For a `:post` with id `25`, this results in an identifier containing :
+`"post:25"`.
+
+Sometimes you'll need to have multiple pages that allows accessing a single
+resource, and your identifier would be duplicated. In this case, you can use
+the `:scope` argument, which will allow to create multiple identifiers with
+the same value, scoped to the given arguments.
+
+As an example, you can this of posts belonging to multiple categories, which
+would result in a structure where a post could appear under multiple categories.
+
+To handle this case, we would write :
+
+```ruby
+Categories.each do |category|
+  category.posts.each do |post|
+    page :post, resource: post, path: category_post_path(category, post), scope: :category_id, category_id: post.category_id
+  end
+end
+```
+
+As a side effect, you can find all "sibling" pages of a given page, allowing
+you to handle canonical URLs or HREFLANG meta tags with ease.
+
+#### Batch scoping and params forwarding
+
+When you have many pages scoped with the same parameters, you may want to DRY
+out scope params passing to the `#page` method calls.
+
+This can be accomplished with the `#with_params` helper method. When used,
+every call to the `#page` method would automatically fetch params passed to the
+`#with_params` method as default params to build or update the underlying page
+object.
+
+Below's an example of a situation where you would have a multi-store shop, and
+want to scope all product categories and products pages depending on their
+belonging store, given that some products and categories could exist in multiple
+stores, requiring you to scope them.
+
+```ruby
+Stores.each do |store|
+  with_params store_id: store.id, scope: :store_id do
+    store.product_categories.each do |product_category|
+      page :product_category, resource: product_category
+
+      product_category.products.each do |product|
+        page :product, resource: product
+      end
+    end
+  end
+end
+```
+
+Global skeleton-wide default params can also be passed to the
+`Para::SeoTools::Skeleton.draw` call at the top of the skeleton file :
+
+```ruby
+Para::SeoTools::Skeleton.draw(scope: :store_id) do
+  # You code scoped by store_id here
+end
+```
+
+#### Locales support
+
+SeoTools comes with multi-locale support built-in. By default, each call to the
+`page` method assigns the current `I18n.locale` to the created page resource.
+
+Localized page path handling is dependent on your app logic, but you can easily
+generate pages for each locale.
+
+If routing to a specific locale only needs a `:locale` argument passed to your
+URL helpers, and you want to create a page for each available locale, here how
+you'd do it :
+
+```ruby
+Para::SeoTools::Skeleton.draw(scope: :locale) do
+  I18n.available_locales.each do |locale|
+    I18n.with_locale(locale) do
+      Posts.find_each do |post|
+        page :post, resource: post, path: post_path(post, locale: locale)
+      end
+    end
+  end
+```
+
+By using `I18n.with_locale`, we force the current locale in the block, and
+SeoTools automatically assigns the locale to the page resource.
+
+#### Lazy skeleton building.
+
+On large applications, building the skeleton with all its pages at application
+boot time is not an option. You can opt out from this strategy and choose to
+build it yourself from a rake task by using the `Para::SeoTools::Skeleton.draw`
+`:lazy` param and calling the rake task from a CRON or similar job.
+
+```ruby
+Para::SeoTools::Skeleton.draw(lazy: true) do
+  # ...
+end
+```
+
+Then use the following rake task :
+
+```bash
+rake seo_tools:skeleton:build
+```
+
+#### Domain and subdomains handling
+
+By default, SeoTools doesn't handle specifically domains and subdomains, since
+it stores the page paths with a leading `/`.
+
+You can tell it to take those parameters into account when building the
+skeleton, and when fetching data during the request.
+
+The first step is to activate one or both of domain and subdomain handling, use
+the `#handle_domain` and `#handle_subdomain` in the para initializer file :
+
+```ruby
+Para.config do |config|
+  config.seo_tools do |seo_tools|
+    seo_tools.handle_domain = true
+    seo_tools.handle_subdomain = true
+  end
+end
+```
+
+Then, you need to pass the domain and subdomain as parameters of the `#page`
+call of your skeleton.rb, or with batch params assignation as described above
+[Batch scoping and params forwarding](#batch-scoping-and-params-forwarding)
+
+```ruby
+page :post, resource: post, subdomain: 'blog', domain: 'example.com'
+```
+
+Now, when the page data is fetched during the request, the `request.subdomain`
+and `request.domain` will be used.
+
+
 ### 2. Display the meta tags admin panel
 
 For the admin panel to display, all you'll need to do is create the component
@@ -103,7 +263,7 @@ section :your_section do
 end
 ```
 
-The go to the admin panel, and click the **Sitemap** menu link.
+Then go to the admin panel, and click the **Sitemap** menu link.
 
 ### 3. Generate a sitemap.xml
 

data/app/models/para/seo_tools/page.rb

@@ -3,9 +3,16 @@ module Para
     class Page < ActiveRecord::Base
       META_TAGS = :title, :description, :keywords, :image, :canonical
 
+      store_accessor :config, :scope
+
       has_attached_file :image, styles: { thumb: '200x200#' }
       validates_attachment :image, content_type: { content_type: /\Aimage\/.*\Z/ }
 
+      validate :identifier_uniqueness
+
+      scope :with_subdomain, ->(subdomain) { where("config->>'subdomain' = ?", subdomain) }
+      scope :with_domain, ->(domain) { where("config->>'domain' = ?", domain) }
+
       def meta_tag(name)
         if (value = send(name).presence) && (meta = process(name, value)).present?
           return meta
@@ -44,6 +51,29 @@ module Para
         Arel::Nodes::SqlLiteral.new(expr.to_sql)
       end
 
+      def scope_attributes
+        scope.each_with_object({}) do |attribute, hash|
+          hash[attribute] = if self.class.column_names.include?(attribute.to_s)
+            send(attribute)
+          else
+            config[attribute.to_s]
+          end
+        end
+      end
+
+      def sitemap_host
+        host = []
+        host << config['subdomain'] if Para::SeoTools.handle_subdomain
+
+        if Para::SeoTools.handle_domain
+          host << config['domain']
+        else
+          host << Para::SeoTools.host
+        end
+
+        host.join('.')
+      end
+
       private
 
       def process(name, value)
@@ -53,6 +83,23 @@ module Para
           value
         end
       end
+
+      def identifier_uniqueness
+        conditions = PageScoping.new(self).uniqueness_scope_conditions
+        conditions = conditions.where.not(id: id) if persisted?
+
+        if conditions.where(identifier: identifier).exists?
+          errors.add(:identifier, :taken)
+        end
+      end
+
+      def method_missing(method_name, *args, &block)
+        if config.key?(method_name.to_s)
+          config[method_name.to_s]
+        else
+          super
+        end
+      end
     end
   end
 end

data/db/migrate/20160930064950_add_config_to_seo_tools_pages.rb

@@ -0,0 +1,5 @@
+class AddConfigToSeoToolsPages < ActiveRecord::Migration
+  def change
+    add_column :seo_tools_pages, :config, :jsonb
+  end
+end

data/lib/para/seo_tools.rb

@@ -12,6 +12,7 @@ module Para
     autoload :Routes
     autoload :Skeleton
     autoload :Sitemap
+    autoload :PageScoping
 
     autoload :MetaTaggable
     autoload :MetaTaggableMacro
@@ -20,6 +21,12 @@ module Para
     mattr_writer :host
     @@host = ENV['APP_DOMAIN']
 
+    mattr_accessor :handle_domain
+    @@handle_domain = false
+
+    mattr_accessor :handle_subdomain
+    @@handle_subdomain = false
+
     mattr_accessor :title_methods
     @@title_methods = %w(title name)
 

data/lib/para/seo_tools/controller.rb

@@ -37,7 +37,11 @@ module Para
       end
 
       def fetch_meta_tags_page
-        if (page = Para::SeoTools::Page.find_by_path(request.path))
+        page_conditions = Para::SeoTools::Page.where(path: request.path)
+        page_conditions = page_conditions.with_subdomain(request.subdomain) if Para::SeoTools.handle_subdomain
+        page_conditions = page_conditions.with_domain(request.domain) if Para::SeoTools.handle_domain
+
+        if (page = page_conditions.first)
           set_meta_tags_from_page(page)
         end
       end

data/lib/para/seo_tools/page_scoping.rb

@@ -0,0 +1,39 @@
+# Common class used by the Page model and PageBuilder to build and handle
+# pages scoping and building their unique identifiers
+#
+module Para
+  module SeoTools
+    class PageScoping
+      attr_reader :resource
+
+      def initialize(resource)
+        @resource = resource
+      end
+
+      def scoped?
+        resource.scope.present?
+      end
+
+      def column?(attribute)
+        resource.class.column_names.include?(attribute.to_s)
+      end
+
+      def uniqueness_scope_conditions
+        return resource.class unless scoped?
+
+        resource.scope_attributes.reduce(resource.class) do |query, (attribute, value)|
+          if column?(attribute)
+            query.where(attribute => value)
+          else
+            query.where("config->>'#{ attribute }' = ?", value)
+          end
+        end
+      end
+
+      def unique_identifier
+        return resource.identifier unless scoped?
+        resource.scope_attributes.merge(identifier: resource.identifier).to_json
+      end
+    end
+  end
+end

data/lib/para/seo_tools/sitemap.rb

@@ -1,10 +1,33 @@
 module Para
   module SeoTools
     class Sitemap
+      def self.generate!
+        puts " * GENERATE SITEMAP ..."
+
+        build
+
+        puts " * BUILD ..."
+
+        ::Sitemap::Generator.instance.build!
+
+        puts " * SAVE ..."
+
+        ::Sitemap::Generator.instance.save(path)
+
+        puts " * SAVED !"
+      end
+
+      def self.path
+        @path ||= begin
+          root = ::Sitemap.configuration.save_path || ENV["LOCATION"] || Rails.public_path
+          File.join(root, "sitemap.xml")
+        end
+      end
+
       def self.build
-        ::Sitemap::Generator.instance.load host: Para::SeoTools.host do
+        ::Sitemap::Generator.instance.load do
           Para::SeoTools::Page.find_each do |page|
-            literal page.path
+            literal page.path, host: page.sitemap_host
           end
         end
       end

data/lib/para/seo_tools/skeleton.rb

@@ -4,10 +4,10 @@ module Para
       extend ActiveSupport::Autoload
 
       autoload :Site
-      autoload :Page
+      autoload :PageBuilder
       autoload :Worker
 
-      mattr_accessor :site, :config, :enable_logging
+      mattr_accessor :site, :config, :options, :enable_logging
 
       def self.with_logging(&block)
         self.enable_logging = true
@@ -25,18 +25,23 @@ module Para
         require skeleton_path if File.exists?(skeleton_path)
       end
 
-      def self.draw(lazy: false, &block)
+      def self.draw(lazy: false, **options, &block)
         self.config = block
+        self.options = options
         build unless lazy
       end
 
-      def self.build
+      def self.build(load_skeleton: false)
         return if migrating?
         return unless ActiveRecord::Base.connection.table_exists?(Para::SeoTools::Page.table_name)
 
+        load if load_skeleton
+
         log "   * Building app skeleton pages ..."
 
-        self.site = Skeleton::Site.new(enable_logging: enable_logging)
+        site_options = options.merge(enable_logging: enable_logging)
+        self.site = Skeleton::Site.new(site_options)
+
         # Evaluate the configuration block
         site.instance_exec(&config)
 

data/lib/para/seo_tools/skeleton/{page.rb → page_builder.rb}

@@ -1,27 +1,50 @@
 module Para
   module SeoTools
     module Skeleton
-      class Page
+      class ScopeAttributeUndefined < StandardError; end
+
+      class PageBuilder
         include Rails.application.routes.url_helpers
 
-        attr_reader :name, :resource, :options, :locale
+        attr_reader :name, :resource, :locale, :defaults, :config
 
         def initialize(name, path: nil, resource: nil, **options)
           @name = name
           @path = path
           @resource = resource
-          @options = options
 
           # Fetch locale on page build to allow calling the `page` skeleton
           # method inside a `I18n.with_locale` block
           #
-          @locale = options.fetch(:locale, I18n.locale)
+          @locale = options.delete(:locale) || I18n.locale
+          @defaults = options.delete(:defaults) || {}
+
+          # Remaining options will be stored as config in a JSONB attribute
+          @config = options
         end
 
         def identifier
           @identifier ||= [name, resource.try(:id)].compact.join(':')
         end
 
+        def scope
+          @scope ||= config[:scope]
+        end
+
+        def scope_attributes
+          scope.each_with_object({}) do |attribute, hash|
+            hash[attribute] = if (value = config[attribute])
+              value
+            elsif respond_to?(attribute)
+              send(attribute)
+            else
+              raise ScopeAttributeUndefined, "Your Skeleton page is scoped " +
+                "with the '#{ attribute }' attribute but you did not pass it " +
+                "as a parameter of the #page : #{ inspect }"
+            end
+          end
+        end
+
         def display_name
           @display_name ||= [name, resource.try(:id)].compact.join(' #').humanize
         end
@@ -31,18 +54,13 @@ module Para
         end
 
         def model
-          @model ||= self.class.model_for(identifier).tap do |page|
+          @model ||= self.class.model_for(self).tap do |page|
             # Override path (i.e.: slug changed)
             page.path = path if path.to_s != page.path
             page.locale = locale
             # Do not override meta tags if already present
-            page.defaults = options[:defaults] || {}
-          end
-        end
-
-        def sitemap_options
-          [:priority, :change_frequency].each_with_object({}) do |param, hash|
-            hash[param] = options[param] if options.key?(param)
+            page.defaults = defaults
+            page.config = config
           end
         end
 
@@ -56,15 +74,21 @@ module Para
           end
         end
 
-        def self.model_for(identifier)
-          models[identifier] ||= ::Para::SeoTools::Page.new(identifier: identifier)
+        def self.model_for(page)
+          models[unique_identifier_for(page)] ||= ::Para::SeoTools::Page.new(
+            identifier: page.identifier
+          )
         end
 
         def self.models
           @models ||= Para::SeoTools::Page.all.each_with_object({}) do |page, hash|
-            hash[page.identifier] = page
+            hash[unique_identifier_for(page)] = page
           end
         end
+
+        def self.unique_identifier_for(page)
+          Para::SeoTools::PageScoping.new(page).unique_identifier
+        end
       end
     end
   end

data/lib/para/seo_tools/skeleton/site.rb

@@ -3,19 +3,29 @@ module Para
     module Skeleton
       class Site
         include Rails.application.routes.url_helpers
-        attr_reader :enable_logging
+        attr_reader :enable_logging, :default_page_options
 
         def initialize(options = {})
-          @enable_logging = options[:enable_logging]
+          @enable_logging = options.delete(:enable_logging)
+          @default_page_options = options
         end
 
         def page(name, options = {} , &block)
-          Skeleton::Page.new(name, options).tap do |page|
+          options.reverse_merge!(default_page_options)
+
+          Skeleton::PageBuilder.new(name, options).tap do |page|
             pages << page
             save if pages.length == max_pages_before_save
           end
         end
 
+        def with_params(params = {}, &block)
+          previous_default_page_options = default_page_options
+          @default_page_options = default_page_options.dup.merge(params)
+          block.call
+          @default_page_options = previous_default_page_options
+        end
+
         def pages
           @pages ||= []
         end

data/lib/para/seo_tools/version.rb

@@ -1,5 +1,5 @@
 module Para
   module SeoTools
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/tasks/para_seo_tools_tasks.rake

@@ -0,0 +1,22 @@
+namespace :para do
+  namespace :seo_tools do
+    namespace :skeleton do
+      desc "Builds or refreshes the app skeleton."
+      task build: :environment do
+        Para::SeoTools::Skeleton.build(load_skeleton: true)
+      end
+    end
+
+    namespace :sitemap do
+      desc "Generates a new sitemap."
+      task generate: :environment do
+        Para::SeoTools::Sitemap.generate!
+      end
+
+      desc "Ping engines."
+      task ping: :environment do
+        ::Sitemap::Ping.send_request(Para::SeoTools::Sitemap.path)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: para-seo_tools
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Valentin Ballestrino
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-27 00:00:00.000000000 Z
+date: 2016-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -118,6 +118,7 @@ files:
 - db/migrate/20150601085253_create_seo_tools_pages.rb
 - db/migrate/20160610094032_add_meta_tags_to_seo_tools_pages.rb
 - db/migrate/20160614081242_add_locale_and_remove_meta_tags_list_to_seo_tools_pages.rb
+- db/migrate/20160930064950_add_config_to_seo_tools_pages.rb
 - lib/generators/para/seo_tools/install/install_generator.rb
 - lib/generators/para/seo_tools/install/templates/initializer.rb
 - lib/generators/para/seo_tools/install/templates/skeleton.rb
@@ -138,17 +139,17 @@ files:
 - lib/para/seo_tools/meta_tags/vendors/base.rb
 - lib/para/seo_tools/meta_tags/vendors/open_graph.rb
 - lib/para/seo_tools/meta_tags/vendors/twitter.rb
+- lib/para/seo_tools/page_scoping.rb
 - lib/para/seo_tools/routes.rb
 - lib/para/seo_tools/sitemap.rb
 - lib/para/seo_tools/skeleton.rb
-- lib/para/seo_tools/skeleton/page.rb
+- lib/para/seo_tools/skeleton/page_builder.rb
 - lib/para/seo_tools/skeleton/site.rb
 - lib/para/seo_tools/skeleton/worker.rb
 - lib/para/seo_tools/version.rb
 - lib/para/seo_tools/view_helpers.rb
 - lib/tasks/migration.rake
-- lib/tasks/sitemap.rake
-- lib/tasks/skeleton.rake
+- lib/tasks/para_seo_tools_tasks.rake
 - para-seo_tools.gemspec
 - test/fixtures/seo_tools/pages.yml
 - test/models/seo_tools/page_test.rb

data/lib/tasks/sitemap.rake

@@ -1,17 +0,0 @@
-namespace :seo_tools do
-  namespace :sitemap do
-    desc "Generates a new sitemap."
-    task generate: :environment do
-      Para::SeoTools::Sitemap.build
-      root = ::Sitemap.configuration.save_path || ENV["LOCATION"] || Rails.public_path
-      path = File.join(root, "sitemap.xml")
-      ::Sitemap::Generator.instance.build!
-      ::Sitemap::Generator.instance.save(path)
-    end
-
-    desc "Ping engines."
-    task ping: :environment do
-      ::Sitemap::Ping.send_request(ENV["LOCATION"])
-    end
-  end
-end

data/lib/tasks/skeleton.rake

@@ -1,9 +0,0 @@
-namespace :seo_tools do
-  namespace :skeleton do
-    desc "Builds or refreshes the app skeleton."
-    task build: :environment do
-      Para::SeoTools::Skeleton.load
-      Para::SeoTools::Skeleton::Worker.perform
-    end
-  end
-end