flowmor_router 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2c0e0b8f28d14381f316e7b078f003b6b34ad4e3
+  data.tar.gz: d3e74563ae117dd9845b403d40dda5fb4959b602
+SHA512:
+  metadata.gz: d419cdd6d363da16774c775ce50a650b8e6efa4dcd5ffdd359cc6c752f8a321fb4661e3f71069eb2bf6d2a5def06ee643426d9b7586745f256021348b82c7149
+  data.tar.gz: cebc0c41d34de490877241f6c85788710b0f281f47d4335d2930a9fc815d01219f9df33c0df69ce7a19862a017048f3c84620a364f00117ebe78dbf876221a6c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Michael Lang
+
+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.md

@@ -0,0 +1,175 @@
+# FlowmorRouter
+
+FlowmorRouter is a Rails::Engine that enables ActiveRecord Models to route themselves in Rails 4.x applications. For example:
+
+```ruby
+class Post < RoutableRecord
+end
+
+p = Post.create(title: "My First Post")
+puts p.name # => "my-first-example"
+puts p.path # => "/posts/my-first-example"
+```
+
+or in a view where PostCategory has_many :posts
+
+```haml
+- PostCategory.all.each do |category|
+  %h3= link_to category.title, category.path
+  %ul
+    - category.posts.recently_published.each do |post|
+      %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.
+
+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:
+
+```haml
+=%h1 About
+%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.
+
+## State of the project
+
+### 0.0.1
+
+Its got enough functionality to work really well for me [(mwlang)](https://github.com/mwlang) in its current form.  Its 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.  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!
+
+
+
+### To Install
+
+Add to your Rails project Gemfile:
+
+```
+gem 'flowmor_router'
+```
+
+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.
+
+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:
+
+```ruby
+class PostController < ApplicationController
+  before_action :set_post, only: [:show]
+
+  private
+  
+  def set_post
+    @post = Post.find(params[:id])
+  end
+end
+```
+
+Note that you can find the record using the params[:id] which will be the actual id of the record because the routes are constructed specific to the ID for the object to be fetched.  This way we can skip the whole #to_param and params[:id].to_i non-sense or doing a more expensive SQL query and indexing on real titles, names, etc.  The other thing I like about this approach is that it plays nice with other toys like ActiveAdmin, which can get finicky about those #to_param changes.
+
+To make an ActiveRecord model routable, change the inheritance after generating the model from ActiveRecord::Base to RoutableRecord like so:
+
+```ruby
+class Post < RoutableRecord
+  # ...
+end
+```
+
+### 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:
+
+```ruby
+class NewsArticle < RoutableRecord
+  set_derived_name_field :caption # changes from :title
+  set_name_field  :slug # changes from :name
+end
+```
+To change the controller and action:
+
+```ruby
+class PostCategory < RoutableRecord 
+  set_controller_action "blog#category"
+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 < RoutableRecord
+  has_many :posts, foreign_key: "category_id"
+
+  set_controller_action "blog#category"
+
+  # 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"
+  end
+end
+
+class Post < RoutableRecord
+  belongs_to :category, class_name: "PostCategory", counter_cache: true
+
+  set_controller_action "blog#show"
+
+  # 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
+  
+  # The route is also changed in this example from /posts/some-title to /general/some-title
+  def route
+    "/#{category_name}/#{name}"
+  end
+end
+```
+
+If you need to get any fancier than that, then just about everything you need can be found in the [app/models/routable_record.rb](https://github.com/mwlang/flowmor_router/blob/master/app/models/routable_record.rb) implementation.
+
+### TODO and Contributing
+
+This is largely an extraction of functionality from multiple Rails projects.  As such, it has the features I needed to fully extract to the engine.  However, some possible enhancements came to mind as I pulled this together:
+
+* if a model belongs_to another model, then use ActiveRecord's Reflections to automatically build richer routes
+* scan sub-directories under static to build nested pages that the static_controller can serve.
+* instead of routing *all* RoutableRecord's, add "routable" scope that defaults to *all* but can be easily changed by redefining the :routable scope on the descendant model class.
+* potentially optimize the route generator to only update the routes that actually changed (currently all routes are triggered to reload).
+
+Please don't hold your breath for me, though.  Unless [I need 'em for a specific project](http://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it), they won't happen.  If you need it, implement and contribute back with pull request.  I'll take enhancements as long as they're test covered and don't break backwards compatibility.
+
+## Testing
+
+Testing makes use of a dummy Rails app, which can be found under [test/dummy folder](https://github.com/mwlang/flowmor_router/tree/master/test/dummy).  The test scripts for this app is under [test/dummy/test](https://github.com/mwlang/flowmor_router/tree/master/test/dummy/test) and you'll find many of the examples presented above as working examples in this dummy app.
+
+To test for the first time, you'll need to initialize the database with:
+
+```
+RAILS_ENV=test rake db:migrate
+```
+
+Following this, you can run the test suite with:
+
+```
+rake test
+```
+
+### LICENSE
+
+This project uses MIT-LICENSE.  Please see the MIT-LICENSE file.

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'FlowmorRouter'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/app/controllers/static_controller.rb

@@ -0,0 +1,2 @@
+class StaticController < ApplicationController
+end

data/app/models/routable_record.rb

@@ -0,0 +1,121 @@
+class RoutableRecord < ActiveRecord::Base
+  self.abstract_class = true
+
+  def self.route_model
+    name.underscore.downcase
+  end
+
+  def route_model
+    self.class.route_model
+  end
+  
+  def self.set_controller_action value
+    @controller_action = value
+  end
+
+  def self.default_controller_action
+    "#{route_model.underscore}#show"
+  end
+
+  def self.controller_action
+    @controller_action || default_controller_action
+  end
+  
+  def controller_action
+    self.class.controller_action
+  end
+  
+  def self.set_derived_name_field value
+    @derived_name_field = value
+  end
+
+  def self.derived_name_field
+    @derived_name_field || 'title'
+  end
+  
+  def derived_name_field
+    self.class.derived_name_field
+  end
+
+  def derived_name_field_value
+    if respond_to? derived_name_field
+      send(derived_name_field)
+    else
+      raise RuntimeError
+    end
+  end
+
+  def self.set_name_field value
+    @name_field = value
+  end
+  
+  def self.name_field
+    @name_field || 'name'
+  end
+  
+  def name_field
+    self.class.name_field
+  end
+
+  def name_field_value
+    attributes[name_field]
+  end
+
+  include Rails.application.routes.url_helpers
+
+  after_save :reload_routes
+  before_save :populate_name
+
+  def route_name_prefix
+    "#{route_model.pluralize}"
+  end
+  
+  def route_name
+    name_suffix = new_name_value
+    raise UnroutableRecord if name_suffix.blank?
+    
+    "#{route_name_prefix}_#{name_suffix}".underscore
+  end
+
+  def route_prefix
+    "/#{route_model.pluralize.gsub('_', '-')}"
+  end
+  
+  def route
+    "#{route_prefix}/#{new_name_value}"
+  end
+  
+  def default_url_options
+    { :host => Thread.current[:host], :port => Thread.current[:port] }
+  end
+  
+  def url
+    send("#{route_name}_url", default_url_options)
+  end
+
+  def path
+    send("#{route_name}_path")
+  end
+  
+  def new_name_value
+    if value = derived_name_field_value and !value.blank?
+      value.downcase.gsub(/[^\w\s\d\_\-]/,'').gsub(/\s\s+/,' ').gsub(/[^\w\d]/, '-')
+    else
+      raise FlowmorRouter::UnroutableRecord if value.blank?
+    end
+  end
+  
+  def name_field_changed?
+    new_name_value != attributes[name_field]
+  end
+  
+  def populate_name
+    if attributes[name_field].blank? || name_field_changed?
+      send("#{name_field}=", new_name_value)
+    end
+  end
+  
+  def reload_routes
+    Rails.application.routes_reloader.reload!
+  end
+end

data/bin/rails

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" with Rails 4 gems installed from the root of your application.
+
+ENGINE_ROOT = File.expand_path('../..', __FILE__)
+ENGINE_PATH = File.expand_path('../../lib/flowmor_router/engine', __FILE__)
+
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+
+require 'rails/all'
+require 'rails/engine/commands'

data/config/routes.rb

@@ -0,0 +1,21 @@
+Rails.application.routes.draw do
+
+  # Routes from RoutableRecord descendants
+  RoutableRecord.descendants.each do |model|
+    model.all.each do |record|
+      get record.route,
+      to: record.controller_action,
+      defaults: { id: record.id },
+      as: record.route_name
+    end
+  end
+  
+  # Routes from app/view/static
+  Dir.glob(File.join(Rails.root, 'app', 'views', 'static', '*')).reject{|r| File.directory?(r)}.each do |fn|
+    route = File.basename fn.split(".").first
+    # ignore partials
+    if route[0] != "_"
+      get("/#{route}", to: "static##{route}", as: "static_#{route}") 
+    end
+  end
+end

data/lib/flowmor_router/engine.rb

@@ -0,0 +1,4 @@
+module FlowmorRouter
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/flowmor_router/exceptions.rb

@@ -0,0 +1,3 @@
+module FlowmorRouter
+  class UnroutableRecord < RuntimeError; end
+end

data/lib/flowmor_router/version.rb

@@ -0,0 +1,3 @@
+module FlowmorRouter
+  VERSION = "0.0.1"
+end

data/lib/flowmor_router.rb

@@ -0,0 +1,24 @@
+require "flowmor_router/engine"
+require "flowmor_router/exceptions"
+
+module FlowmorRouter
+
+  class HostAndPortGrabber
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      req = Rack::Request.new(env)
+      Thread.current[:host] = req.host
+      Thread.current[:port] = req.port
+      
+      @app.call(env)
+    end
+  end
+
+  class Engine < ::Rails::Engine
+    config.flowmor_router = FlowmorRouter
+    config.app_middleware.insert_after(ActionDispatch::ParamsParser, FlowmorRouter::HostAndPortGrabber)
+  end
+end

data/lib/tasks/flowmor_router_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :flowmor_router do
+#   # Task goes here
+# end

data/test/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Rails.application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/test/dummy/app/assets/javascripts/blog.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/test/dummy/app/assets/javascripts/static.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/test/dummy/app/assets/stylesheets/blog.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/test/dummy/app/assets/stylesheets/static.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,5 @@
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+end

data/test/dummy/app/controllers/blog_controller.rb

@@ -0,0 +1,9 @@
+class BlogController < ApplicationController
+  before_action :set_post, only: [:show]
+
+  private
+  
+  def set_post
+    @post = Post.find(params[:id])
+  end
+end

data/test/dummy/app/controllers/static_controller.rb

@@ -0,0 +1,2 @@
+class StaticController < ApplicationController
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/test/dummy/app/helpers/blog_helper.rb

@@ -0,0 +1,2 @@
+module BlogHelper
+end

data/test/dummy/app/helpers/static_helper.rb

@@ -0,0 +1,2 @@
+module StaticHelper
+end

data/test/dummy/app/models/article.rb

@@ -0,0 +1,3 @@
+class Article < RoutableRecord
+
+end

data/test/dummy/app/models/news_article.rb

@@ -0,0 +1,4 @@
+class NewsArticle < RoutableRecord
+  set_derived_name_field :caption
+  set_name_field  :slug
+end

data/test/dummy/app/models/post.rb

@@ -0,0 +1,18 @@
+class Post < RoutableRecord
+  belongs_to :category, class_name: "PostCategory", counter_cache: true
+
+  set_controller_action "blog#show"
+
+  # Appending category name to the route name prefix
+  def route_name_prefix
+    super + "_#{category_name}"
+  end
+  
+  def category_name
+    category.try(:name) || 'general'
+  end
+  
+  def route
+    "/#{category_name}/#{name}"
+  end
+end

data/test/dummy/app/models/post_category.rb

@@ -0,0 +1,9 @@
+class PostCategory < RoutableRecord
+  has_many :posts, foreign_key: "category_id"
+
+  set_controller_action "blog#category"
+
+  def route_model
+    "category"
+  end
+end

data/test/dummy/app/views/blog/show.html.erb

@@ -0,0 +1 @@
+<h1><%= @post.title %></h1>

data/test/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy</title>
+  <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track' => true %>
+  <%= javascript_include_tag 'application', 'data-turbolinks-track' => true %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/test/dummy/app/views/static/index.html.erb

@@ -0,0 +1,3 @@
+<h1>Static Page Example</h1>
+
+<p>It Works!</p>

data/test/dummy/bin/bundle

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+load Gem.bin_path('bundler', 'bundle')

data/test/dummy/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path('../../config/application',  __FILE__)
+require_relative '../config/boot'
+require 'rails/commands'

data/test/dummy/bin/rake

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative '../config/boot'
+require 'rake'
+Rake.application.run