flowmor_router 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 31be1a7b4a12e22cfe628df2fc2c377b1f3168f8
-  data.tar.gz: 347abb0a062209b551050aa406fae2cf66ec6c07
+  metadata.gz: b98386121b4bdf28961d5609e38be1b73e05cc47
+  data.tar.gz: 603ce477d9752cd29bd925367d289a1d3d40de76
 SHA512:
-  metadata.gz: 6cb6b02478779500ac77b34003c6b725b368eb116ac643d7143e58cc933ecdbfd0546cb5809ee5dc6f24d6a05e259c5868d12fa2158cf51b9ebd1d4d5129f3a0
-  data.tar.gz: ea5baea315539090ff19c54fee5fc213d62ace2bc2f43ea5582b43becc43060e5027398125444d6e03887b328977afab6ee017179984fd85eaf6c666095365ef
+  metadata.gz: b61723cb2b8612f01af3f75d56240544aa7487af10f648b12866400ff60a962a6713131b5f1861d0a6fa852be4b9e884ceb1b651b9e7b04e115d88464dc0c439
+  data.tar.gz: 6e3b88f55e1afbdd752ea9465c507fa9c42f727e245e882d23255e21868bc52dc922f11feb09ee11fdb266db60bcfd4ab2e6e0b0fbeeea0eb89d77163ffc5eaf

data/README.md

@@ -8,7 +8,6 @@ class Post < ActiveRecord::Base
 end
 
 p = Post.create(title: "My First Post")
-puts p.name # => "my-first-example"
 puts p.path # => "/posts/my-first-example"
 ```
 
@@ -22,7 +21,7 @@ or in a view where PostCategory has_many :posts
       %li= link_to post.title, post.path
 ```
 
-FlowmorRouter also supports static pages.  All you have to do is create an app/views/static folder and place templates in that folder.  Routes are automatically generated and served by the StaticController.  Currently, this only goes one level deep.  That is, sub-directories of static not yet implemented.
+FlowmorRouter also supports static pages.  All you have to do is create an app/views/static folder and place templates in that folder.  Routes are automatically generated and served by the StaticController.  Currently, this only goes one level deep.  That is, sub-directories of static not yet implemented.  Useful for rapidly importing WordPress archive pages!  For an idea of how I rapidly ported my WordPress and python/Zope websites to Rails, check out the following [gist](https://gist.github.com/mwlang/a4dbf5c098fd8f9502b2).
 
 If you're blogging with markdown or other file-based approaches, you'll appreciate how easy it is to reference your posts in those static views with linking:
 
@@ -31,21 +30,160 @@ If you're blogging with markdown or other file-based approaches, you'll apprecia
 %p Please be sure to read my post, #{link_to "How to Use Flowmor Router", post_how_to_use_flowmor_router_path}
 ```
 
-Every model instance's route is named after the model and name.
+Every model instance's path is named after the model and title/slug/name for the record.  How the paths and path names are generated can be customized.
+
 
 ## State of the project
 
-### 0.1.1
-### Tested and Works on Rails 4.x and Ruby 2.x
-### added ability to use act_as_routable instead of inheriting from RoutableRecord
+* 0.2.1
+* Tested and Works on Rails 4.x and Ruby 2.x
+* Changed usage pattern to use act_as_routable instead of inheriting from RoutableRecord
+* Completely refactored to remove as much code out of the ActiveRecord class and into a new RouterClasses object.
+* Also greatly simplified some of the implementation and cleaned up weird naming conventions.
+* Added ability to have multiple actors on one model
+* Added suffix and prefix
 
 Its got enough functionality to work really well for me [(mwlang)](https://github.com/mwlang) in its current form.  It's a simple implementation with relatively few lines of code, adequately test covered.  It works and is used in production on a handful of sites.  You can see it in action on [my personal site](http://codeconnoisseur.org) and [business site](http://cybrains.net).
 
 ### Is it For You?
 
-This isn't for everyone.  It does build routes from objects in the database.  Rails purists will argue this method pollutes the routes space.  It does provide functionality similar to [friendly_id](https://github.com/norman/friendly_id) or by simply redefining the id of a model with AR's #to_param. If you run multiple instances of an application, you'll need to take care of syncing when the database is updated.  The simplest way to do this is by adding Post.reload_routes (for example) to the before_filter callback of the controller.  Sounds like a performance killer, but its really not.  Just think every time you refresh during development that the routes are reloaded! 
+This isn't for everyone.  The Flowmor Router build routes ahead of time based on objects in the database.  Rails purists will argue this method pollutes the routes space.  It does provide functionality similar to [friendly_id](https://github.com/norman/friendly_id) or by simply redefining the id of a model with AR's #to_param.  If you run multiple instances of an application, you'll need to take care of syncing when the database is updated.  The simplest way to do this is by adding Post.reload_routes (for example) to the before_filter callback of the controller.  Sounds like a performance killer, but its really not.  Just think every time you refresh during development that the routes are reloaded! 
+
+On the other hand, this approach allows you a lot of flexibility to creating truly custom routes in your app.  It also allows you to avoid using a global "match any" in your config/routes.rb.  A use case is porting over a WordPress site to Rails where there was a highly customized permalink structure in place.  It's really only meant for "#show" actions.  I personally wouldn't try to also incorporate CRUD actions with friendly route names.  Rails' conventional routes does the job extremely well for CRUD actions.  This also means other gems like ActiveAdmin will work as advertised since friendly routes aren't interfering with Rails routes.
+
+## TL;DR
+
+For those of you who just need good examples and not a lot of words.  The following examples are class definitions followed by what's generated:
+
+```ruby
+class KitchenSink < ActiveRecord::Base
+  acts_as_routable :sink,
+    scope: -> { where(nothing_missing: true) }
+    prefix: -> { :kitchen },
+    suffix: [:faucet, :drain],
+    delimiter: "_",
+    name_field: :appliance
+    title_field: :display
+    name: -> { :sluggerize }
+    route: -> { :route }
+
+    def kitchen
+      [:fancy, :kitchen]
+    end
+      
+    def sluggerize 
+      self.title.downcase.parameterize("_")
+    end
+    
+  def route 
+    "/kitchen/sink/#{sluggerize}"
+  end
+end
+```
+NOTE: prefix and suffix can be either a Symbol/String, an Array of such, or a Proc which references a method on the Model that returns a String/Symbol or Array of such.
+
+```ruby  
+class Post < ActiveRecord::Base
+  acts_as_routable
+end
+
+@post = Post.create(title: "Title me Silly")
+
+route_name   = posts_title_me_silly
+route_path   = posts_title_me_silly_path
+route_url    = posts_title_me_silly_url
+@post.path   = /posts/title-me-silly
+@post.url    = http://example.com/posts/title-me-silly
+```
+
+```ruby  
+class Post < ActiveRecord::Base
+  acts_as_routable :ramblings
+end
+
+@post = Post.create(title: "Title me Silly")
+
+route_name   = ramblings_title_me_silly
+route_path   = ramblings_title_me_silly_path
+route_url    = ramblings_title_me_silly_url
+@post.path   = /ramblings/title-me-silly
+@post.url    = http://example.com/ramblings/title-me-silly
+```
+
+```ruby
+class Post < ActiveRecord::Base
+  acts_as_routable :ramblings, prefix: :posts
+end
+
+@post = Post.create(title: "Title me Silly")
+
+route_name   = posts_ramblings_title_me_silly
+route_path   = posts_ramblings_title_me_silly_path
+route_url    = posts_ramblings_title_me_silly_url
+@post.path   = /posts/ramblings/title-me-silly
+@post.url    = http://example.com/posts/ramblings/title-me-silly
+```
+
+```ruby
+class Post < ActiveRecord::Base
+  acts_as_routable :ramblings, prefix: [:blog, :posts]
+end
+
+@post = Post.create(title: "Title me Silly")
+
+route_name   = blog_posts_ramblings_title_me_silly
+route_path   = blog_posts_ramblings_title_me_silly_path
+route_url    = blog_posts_ramblings_title_me_silly_url
+@post.path   = /blog/posts/ramblings/title-me-silly
+@post.url    = http://example.com/blog/posts/ramblings/title-me-silly
+```
+
+```ruby
+class Post < ActiveRecord::Base
+  belongs_to :category
+  acts_as_routable :ramblings, prefix: -> { category.name }
+  acts_as_routable :archive, suffix: [:posts]
+end
+
+@post = Post.create(title: "Title me Silly")
+
+route_name   = silly_category_ramblings_title_me_silly
+route_path   = silly_category_ramblings_title_me_silly_path
+route_url    = silly_category_ramblings_title_me_silly_url
+@post.path   = /silly-category/posts/ramblings/title-me-silly
+@post.url    = http://example.com/silly-category/posts/ramblings/title-me-silly
+
+# AND
+
+route_name               = archive_posts_title_me_silly
+route_path               = archive_posts_title_me_silly_path
+route_url                = archive_posts_title_me_silly_url
+@post.posts_archive_path = /archive/posts/title-me-silly
+@post.posts_archive_url  = http://example.com/archive/posts/title-me-silly
+```
+
+```ruby
+class Post < ActiveRecord::Base
+  acts_as_routable, scope: -> { where(published: true) }
+  acts_as_routable :archive, prefix: [:posts]
+end
+
+@post = Post.create(title: "Title me Silly")
+
+route_name   = posts_title_me_silly
+route_path   = posts_title_me_silly_path
+route_url    = posts_title_me_silly_url
+@post.path   = /posts/title-me-silly
+@post.url    = http://example.com/posts/title-me-silly
 
-On the other hand, this approach allows you a lot of flexibility to creating truly custom routes in your app.  It also allows you to avoid using a global "match any" in your config/routes.rb.  A use case is porting over a WordPress site to Rails where there was a highly customized permalink structure in place.  
+# AND
+
+route_name               = posts_archive_title_me_silly
+route_path               = posts_archive_title_me_silly_path
+route_url                = posts_archive_title_me_silly_url
+@post.posts_archive_path = /posts/archive/title-me-silly
+@post.posts_archive_url  = http://example.com/posts/archive/title-me-silly
+```  
 
 ### To Install
 
@@ -59,7 +197,7 @@ And then run the `bundle install` command.
 
 ## Convention over Configuration
 
-I wanted a *simple* implementation and library to work with, so the convention is the model has a `title` field and a `name` field.  You (or your user) sets the title and the name field gets auto-populated with a routable name.  Hyphens are used instead of underscores because Google Webmaster Guidelines favors hyphens over underscores for SEO.
+I wanted a *simple* implementation and library to work with, so the convention is the model has a `title` field and a `name` field.  You (or your user) sets the title and the name field, which should be populated with a parameterized/routable value.  Just for kicks, if you don't have a name field on the model, then the Title field is always used to generate a parameterized value.  Hyphens are used by default instead of underscores because Google Webmaster Guidelines favors hyphens over underscores for SEO.  But you can override this passing the :delimiter option.
 
 For example, "FlowmorRouter, the amazing little engine that could" will populate the name field with 'flowmor-router-the-amazing-little-engine-that-could'.  The controller by convention will have the same name as the model's name while the default action will be the #show action on that controller.  If you have a Post model, then its expected that your application has a PostController.  You're expected to provide the controller implementation.  Here's an example:
 
@@ -86,17 +224,45 @@ class Post < ActiveRecord::Base
 end
 ```
 
+### By Convention...
+
+The router looks for a :name field as the valid end of the route string ("my-fancy-post-title").  You're responsible for populating this field with a valid and sensible value for URI strings.  
+
+If the :name field is missing, the router will compute a parameterized name from the :title field.  That is, if the :title field contains "My Fancy Pants Post" then the computed name (a.k.a. slug, or parameterized value) will be "my-fancy-pants-post".  This is appended to arrive at the fully qualified route.
+
+The model that you add "acts_as_routable" to becomes the root of the route.  So Post ```ActiveRecord::Base; acts_as_routable; end``` will yield routes starting at "/posts/" and ultimately "/posts/my-fancy-pants-posts" in the above example's case.
+
 ### Conventions Suck, I Really Want to Customize!
 
-Ok, here's how to do it.  To change the field that the route name is derived from:
+Ok, here's how to do it.  
+
+
+#### :title_field, :name_field  and :name
+
+To change the field that the route name is derived from:
 
 ```ruby
 class NewsArticle < ActiveRecord::Base
   acts_as_routable \
-    derived_name_field: :caption,  # changes from :title
-    name_field: :slug              # changes from :name
+    title_field: :caption,   # changes from :title to :caption
+    name_field: :slug        # changes from :name to :slug
 end
 ```
+
+Alternatively, you can do a lazy evaluation that incorporates other data for the record by passing the :name property
+
+```ruby
+class NewsArticle < ActiveRecord::Base
+  acts_as_routable name: :custom_slug
+  
+  def custom_slug
+    "#{self.author.name}_#{self.name}".parameterize("_")
+  end
+end
+```
+
+Using the :name property supersedes both :name_field and :title_field properties
+
 To change the controller and action:
 
 ```ruby
@@ -108,44 +274,52 @@ end
 To change how the route and route name are constructed (say you have Post that belongs_to PostCategory and need to avoid naming collision should two posts have same title, but belong to different categories):
 
 ```ruby
-class PostCategory < ActiveRecord::Base
-  has_many :posts, foreign_key: "category_id"
+class Post < ActiveRecord::Base
+  belongs_to :category
 
-  acts_as_routable controller_action: "blog#category"
+  acts_as_routable prefix: -> { :category },
+    controller_action: "blog#show"
 
-  # Not necessary here, but shows you how to change the route's model name.
-  # Here, we change "post_category" (the default) to "category"
-  # For example, PostCategory.create(title: "General"), the 
-  # route name becomes "category_general" instead of "post_category_general"
-  def route_model
-    "category"
+  # defaults to "general" category when none assigned
+  def category
+    (self.category.try(:name) || "general").parameterize
   end
 end
 
-class Post < ActiveRecord::Base
-  belongs_to :category, class_name: "PostCategory", counter_cache: true
+@post.create('Programming Ruby', category: Category.find_by_name("General"))
+@post.path # => /general/posts/programming-ruby
+```
 
-  acts_as_routable controller_action: "blog#show"
+Note that the Proc triggers calling the model's "category" method when it's time to construct the route name and path.
 
-  # Assuming you have a Post.create(title: "Some Title", category: PostCategory.create(title: "General"))
-  # The names of the post route's name changes from post_some_title to post_general_some_title by
-  # appending category name to the route name prefix
-  def route_name_prefix
-    super + "_#{category_name}"
-  end
-  
-  # as a bonus, automatically "categorize" as "general" when no category assigned.
-  def category_name
-    category.try(:name) || 'general'
-  end
+Similar to :prefix is the :suffix and it's inserted into the route constructed right before the record's name value.
+
+### route
+
+If you want to skip all the fancy route building provided by the Engine, then pass in a Proc to the :route option.
+
+```ruby
+class Post < ActiveRecord::Base
+  acts_as_routable route: :custom_route
   
-  # The route is also changed in this example from /posts/some-title to /general/some-title
-  def route
-    "/#{category_name}/#{name}"
+  def custom_route
+    "/posts/#{date_created.strftime("%Y/%m/%d/")}#{name.parameterize}"
   end
 end
 ```
 
+### delimiter 
+
+The :delimiter option allows you to change the default hyphen to something else when the route name is computed from the title field.
+
+```
+class Post < ActiveRecord::Base
+  acts_as_routable delimiter: "_-_"
+end
+
+@post.path # => /posts/my_-_silly_-_title
+```
+
 If you need to get any fancier than that, then just about everything you need can be found in the [lib/flowmor_router/acts_as_flowmor_routable.rb](https://github.com/mwlang/flowmor_router/blob/master/lib/flowmor_router/acts_as_flowmor_routable.rb) implementation.
 
 By default, all acts_as_routable models and their instances are added to the routes table.  What gets routed can be customized by supplying a :scope option.

data/Rakefile

@@ -17,8 +17,6 @@ end
 APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
 load 'rails/tasks/engine.rake'
 
-
-
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'

data/config/routes.rb

@@ -1,23 +1,6 @@
 Rails.application.routes.draw do
 
-  FlowmorRouter::ROUTABLE_MODEL_CLASSES.each do |model|
-    model.routable.each do |record|
-      get record.route,
-      to: record.controller_action,
-      defaults: { id: record.id },
-      as: record.route_name
-    end
-  end
-  
-  # Routes from RoutableRecord descendants
-  RoutableRecord.descendants.each do |model|
-    model.routable.each do |record|
-      get record.route,
-      to: record.controller_action,
-      defaults: { id: record.id },
-      as: record.route_name
-    end
-  end
+  puts "REDRAWING ROUTES for #{FlowmorRouter::RouterClasses.router_classes.map{|m| m.model.name.to_s}}"
   
   # Routes from app/view/static
   Dir.glob(File.join(Rails.root, 'app', 'views', 'static', '*')).reject{|r| File.directory?(r)}.each do |fn|
@@ -27,4 +10,15 @@ Rails.application.routes.draw do
       get("/#{route.gsub("_", "-")}", to: "static##{route}", as: "static_#{route.gsub("-", "_")}") 
     end
   end
+
+  FlowmorRouter::RouterClasses.router_classes.each do |router_class|
+    puts "   MODEL: #{router_class.model.name}"
+    router_class.routable.each do |record|
+      puts "   ROUTING: #{router_class.route_path(record)} to: #{router_class.controller_action} defaults: { id: #{record.id} } as: #{router_class.route_name(record)}"
+      get router_class.route_path(record),
+        to: router_class.controller_action,
+        defaults: { id: record.id },
+        as: router_class.route_name(record)
+    end
+  end
 end

data/lib/flowmor_router/acts_as_routable.rb

@@ -0,0 +1,56 @@
+module FlowmorRouter
+  module ActsAsRoutable
+    extend ActiveSupport::Concern
+    
+    included do
+      
+      after_save :reload_routes
+
+      def reload_routes
+        Rails.application.routes_reloader.reload!
+      end
+    end
+
+    module ClassMethods
+
+      def acts_as_routable(actor = nil, options = {})
+        # juggle what was passed in to correct variables
+        actor, options = nil, actor if actor.is_a?(Hash) && options == {}
+        if actor.nil?
+          singular_name = name.underscore.downcase.split("/").last
+          actor = singular_name.pluralize 
+          options[:controller_action] = options[:controller_action] || "#{singular_name}#show"
+        end
+        
+        # Register and assign a distinctive name to the router_class
+        router_class = FlowmorRouter::RouterClasses.register(actor, self, options)
+        puts "REGISTERED #{router_class.named_instance}"
+        class_attribute router_class.named_instance
+        self.send "#{router_class.named_instance}=", router_class
+
+        scope router_class.scope_name, options[:scope] || lambda {}
+
+        define_method router_class.route_name_method_name do 
+          router_class.route_name self
+        end
+        
+        define_method router_class.url_method_name do 
+          router_class.url self
+        end
+        
+        define_method router_class.path_method_name do 
+          router_class.path self
+        end
+        
+        begin
+          Rails.application.routes_reloader.reload! unless Rails.configuration.eager_load
+        rescue SystemStackError
+          # NOP -- Supressing Stack Level Too deep error
+          # caused by models being loaded lazily during development mode.
+        end
+      end
+    end
+  end
+end
+ 
+ActiveRecord::Base.send :include, FlowmorRouter::ActsAsRoutable

data/lib/flowmor_router/exceptions.rb

@@ -1,4 +1,5 @@
 module FlowmorRouter
   class UnroutableRecord < RuntimeError; end
   class UnroutedRecord < RuntimeError; end
+  class DuplicateRouterActors < RuntimeError; end
 end

data/lib/flowmor_router/foo.rb

@@ -0,0 +1,63 @@
+class Foo
+  def hello
+    puts "gonna say hello"
+    "Hello #{world}"
+  end
+  
+  def world
+    "World"
+  end
+  
+  attr_reader :say_it
+  
+  def initialize options = {}
+    @say_it = options[:another_way] || method(:hello)
+    define_singleton_method(:world, options[:another_world]) if options[:another_world]
+  end
+  
+  def speak
+    instance_exec &say_it
+  end
+end
+
+begin
+  foobar = Foo.new
+  puts "lazy?"
+  puts foobar.speak
+rescue Exception => e
+  puts "#{e.class.to_s}: #{e.message}"
+end
+
+begin
+  foobaz = Foo.new(another_way: lambda { "#{hello}, Sir!" })
+  puts "lazy?"
+  puts foobaz.speak
+rescue Exception => e
+  puts "#{e.class.to_s}: #{e.message}"
+end
+
+begin
+  foobaz = Foo.new(another_world: lambda { "Earth" })
+  puts "lazy?"
+  puts foobaz.speak
+rescue Exception => e
+  puts "#{e.class.to_s}: #{e.message}"
+end
+
+class Bar
+  def self.register(name = nil, options = {})
+    if name.nil?
+      name = "foobaz"
+    elsif name.is_a?(Hash) && options == {}
+      name, options = "foobar", name
+    end
+    puts [name, options].inspect
+  end
+end
+
+Bar.register :something, :foo => 1, :bar => 2
+Bar.register \
+  foo: 2, 
+  bar: -> { puts "yeah" }, 
+  baz: 3
+Bar.register

data/lib/flowmor_router/proxy_foo.rb

@@ -0,0 +1,50 @@
+class Foo
+  def hello
+    puts "gonna say hello"
+    "Hello #{world}"
+  end
+  
+  def world
+    "World"
+  end
+  
+  attr_reader :say_it
+  
+  def initialize options = {}
+    @say_it = options[:another_way] || method(:hello)
+    define_singleton_method(:world, options[:another_world]) if options[:another_world]
+  end
+  
+  def speak
+    hello
+  end
+end
+
+class Proxy
+  def
+end
+
+begin
+  foobar = Foo.new
+  puts "lazy?"
+  puts foobar.speak
+rescue Exception => e
+  puts "#{e.class.to_s}: #{e.message}"
+end
+
+begin
+  foobaz = Foo.new(another_way: lambda { "#{hello}, Sir!" })
+  puts "lazy?"
+  puts foobaz.speak
+rescue Exception => e
+  puts "#{e.class.to_s}: #{e.message}"
+end
+
+begin
+  foobaz = Foo.new(another_world: lambda { "Earth" })
+  puts "lazy?"
+  puts foobaz.speak
+rescue Exception => e
+  puts "#{e.class.to_s}: #{e.message}"
+end
+