sinatra-trails 0.0.5 → 0.0.6

data/README.rdoc

@@ -0,0 +1,312 @@
+sinatra-trails
+--------------
+
+Is a very thin Rails inspired route naming DSL for using with Sinatra apps.
+It doesn't monkeypatch or overrides any Sinatra::Base methods 
+It provides helpers for generating routes for resources and single resource, namespaces and named routes.
+
+Instalation
+----------
+
+    $ [sudo] gem install sinatra-trails
+
+Usage
+----
+
+Basic
+=====
+
+Named routes are generated with map, not passing :to option sets the path to be the same as the name:
+
+    require 'sinatra/trails'
+
+    class MyApp < Sinatra::Base
+      register Sinatra::Trails
+
+      map :dashboard                 # => '/dashboard'
+      map :home, :to => '/'          # => '/'
+      map :post, :to => '/posts/:id' # => '/posts/:id'
+    end
+
+    MyApp.print_routes
+    # prints
+    #    dashboard => /dashboard
+    #         home => /
+    #         post => /posts/:id   
+
+Routes can be define beforehand:
+
+    map :dashboard
+    
+    # GET '/dashboard'
+    get route_for(:dashboard) do
+      ...  
+    end
+
+Or when defining the action:
+
+    # GET '/dashboard'
+    get map(:dashboard) do
+      ...
+    end 
+
+All defined routes will be available in the views and action blocks:
+
+    get map(:posts, :to => '/posts/:id') do
+      ...
+    end
+
+    get map(:dashboard) do
+      path_for(:dashboard) # => '/dashboard'
+      url_for(:dashboard)  # => 'http://www.example.com/dashboard'
+      path_for(:dashboard, :option => 'hi') # => '/dashboard?option=hi'
+      # all required params must be meet, an object can be passed to meet :id but it must respond to #to_param
+      path_for(:posts, 1) # => '/posts/1'
+    end 
+
+
+Namespaces
+==========
+
+Pasing a symbol namespaces both the path and the route name:
+
+    namespace :admin do
+      map(:dashboard)
+    end
+    
+    route_for(:admin_dashboard) # => '/admin/dashboard'
+  
+Passing a string only namespaces the path:
+
+    namespace 'admin' do
+      map(:dashboard)
+    end
+
+    route_for(:dashboard) # => '/admin/dashboard'
+
+Passing nil to namespace only sets a context:
+
+    namespace nil do
+      map(:dashboard)
+    end
+
+    route_for(:dashboard) # => '/dashboard'
+
+
+Resources
+=========
+  
+Restful routes for plural resources can be generated as follows, inside the resource
+definition block a route can be accessed by its name as a method call or using the path_for method:
+
+    resources :users do
+      # GET /users
+      get users do
+        ...
+      end
+
+      # POST /users
+      post users do
+        ...
+      end
+      
+      # GET /users/new
+      get new_user do
+        ...
+      end
+      
+      # GET /users/:id
+      get user do
+        ...
+      end
+      
+      # GET /users/:id/edit
+      get edit_user do
+        ...
+      end
+
+      # PUT /users/:id
+      put user do
+        ...
+      end
+
+      # DELETE /users/:id
+      delete user do
+        ...
+      end
+    end
+
+It is important to note that the order in wich the sinatra action blocks are defined is important.
+in this case `get(new_user)` must be defined before `get(user)`
+
+As with previous examples routes can be defined beforehand:
+
+    resources :users
+    # GET '/users'
+    get path_for(:users) do
+      ...
+    end
+
+
+Nested Resources
+================
+
+Resources can be nested in a similar way as with Rails nested resources:
+  
+    resources :users do
+      ...
+      resources :comments do
+        # GET /users/:user_id/comments
+        get user_comments do
+          ...
+        end
+        
+        # GET /users/:user_id/comments/:id
+        get user_comment do
+          ...
+        end
+      end  
+    end
+
+    print_routes
+    #              users => /users
+    #           new_user => /users/new
+    #               user => /users/:id
+    #          edit_user => /users/:id/edit
+    #      user_comments => /users/:user_id/comments
+    #   new_user_comment => /users/:user_id/comments/new
+    #       user_comment => /users/:user_id/comments/:id
+    #  edit_user_comment => /users/:user_id/comments/:id/edit  
+      
+  
+And for actions that don't need to load the parent resource the route generation can be shallow:
+
+    resources :users, :shallow => true do
+      resources :comments
+    end
+    
+    print_routes
+    #            users => /users
+    #         new_user => /users/new
+    #             user => /users/:id
+    #        edit_user => /users/:id/edit
+    #    user_comments => /users/:user_id/comments
+    # new_user_comment => /users/:user_id/comments/new
+    #          comment => /comments/:id
+    #     edit_comment => /comments/:id/edit 
+
+There's an alternative way of generating routes for nested resources:
+
+    resources :users => {:posts => :comments}, :shallow => true do
+      ...
+    end
+    print_routes
+    #             users => /users
+    #          new_user => /users/new
+    #              user => /users/:id
+    #         edit_user => /users/:id/edit
+    #        user_posts => /users/:user_id/posts
+    #     new_user_post => /users/:user_id/posts/new
+    #              post => /posts/:id
+    #         edit_post => /posts/:id/edit
+    #     post_comments => /posts/:post_id/comments
+    #  new_post_comment => /posts/:post_id/comments/new
+    #           comment => /comments/:id
+    #      edit_comment => /comments/:id/edit  
+
+Some keys to the params hash are added when routes are defined using sinatra-trails:
+    
+    params[:resource]  # the name of the resource in REST actions
+    params[:action]    # the name of the action in REST actions
+    params[:namespace] # the name of the current namespace
+
+
+Singleton Resource
+=================
+
+Same principles apply for singleton resource:
+    
+    resource :user
+    print_routes
+    #       user => /user
+    #   new_user => /user/new
+    #  edit_user => /user/edit
+
+
+Before and After Filters
+========================
+
+Defining a filter within a context (namespace, resources, resource) without passing any path will execute that filter for
+all actions defined in that context:
+
+    namespace :admin do
+      before do
+        @admin = true
+      end
+      
+      get map(:dashboard) do
+        @admin # => true
+      end
+    end
+
+    get map(:home, :to => '/') do
+      @admin # => nil
+    end
+
+
+Within a context named routes, strings or regexps can be used as arguments for before and after filters:
+
+    resources :users do
+      before new_user, edit_user do
+      end
+    end
+
+A symbol can be passed to the filter definition and it will be lazily evaluated against the routes within the context:
+
+    namespace :admin do
+      before :dashboard do
+        ...
+      end
+      
+      get map(:dashboard) do
+        ...
+      end
+    end
+
+
+Accessing Routes from Outside the App
+=====================================
+
+On registering Sinatra::Trails a dynamic module for the Sinatra app is created and it is assigned to the constant `Routes`
+including that module in another class gives that class access to the app's paths, a single class can access paths for
+several Sinatra apps:
+
+    class MyApp < Sinatra::Base
+      register Sinatra::Trails
+      
+      get map(:users) do
+        ...
+      end
+      
+      get map(:user, :to => '/users/:id') do
+        ...
+      end
+    end
+
+    class OtherApp < Sinatra::Base
+      include MyApp::Routes
+      
+      get 'index' do
+        redirect to path_for(:users)
+      end
+    end
+
+    class User < Sequel::Model
+      include MyApp::Routes
+
+      def to_param() id end
+
+      def route
+        path_for(:user, self) # => '/users/1'
+      end
+    end

data/lib/sinatra/trails/version.rb

@@ -1,5 +1,5 @@
 module Sinatra
   module Trails
-    VERSION = "0.0.5"
+    VERSION = "0.0.6"
   end
 end

data/lib/sinatra/trails.rb

@@ -89,10 +89,7 @@ module Sinatra
         @actual_keys ||= routes.map{ |m| m.keys }.flatten
       end
 
-      def keys
-        self
-      end
-
+      def keys() self end
       def any?() actual_keys.any? end
       def zip(arr) actual_keys.zip(arr) end
     end
@@ -108,8 +105,8 @@ module Sinatra
       end
 
       def map name, opts = {}, &block
-        path = opts.delete(:to) || name
-        route = Route.new(path, name, [*ancestors, self], self)
+        path  = opts.delete(:to) || name
+        route = Route.new(path, name.to_sym, [*ancestors, self], self)
         instance_eval &block if block_given?
         route
       end
@@ -131,6 +128,12 @@ module Sinatra
         @sinatra_app.before ScopeMatcher.new(self, args), opts, &block
       end
 
+      def after *args, &block
+        # TODO: no specs
+        opts = Hash === args.last ? args.pop : {}
+        @sinatra_app.after ScopeMatcher.new(self, args), opts, &block
+      end
+
       def generate_routes! &block
         instance_eval &block if block_given?
         @routes
@@ -242,7 +245,6 @@ module Sinatra
 
       def map action
         ancestors  = [*self.ancestors, plural_name, action]
-
         ancestors[0, ancestors.size - 2] = ancestors[0..-3].reject{ |ancestor| Resource === ancestor } if opts[:shallow]
         Route.new([plural_name, action], action.to_s, ancestors, self)
       end

data/spec/route_generation_spec.rb

@@ -13,7 +13,7 @@ describe 'trails' do
     describe 'basic' do
       before :all do
         app.map :home, :to => '/'
-        app.map :dashboard
+        app.map 'dashboard'
         app.map :edit_user, :to => '/users/:id/edit'
       end
 
@@ -166,7 +166,6 @@ describe 'trails' do
         app.resources :users do
           map(:confirm)
         end
-        puts app.print_routes
       end
       it_should_behave_like 'generates routes for users'
       it { app.route_for(:users_confirm).should  == '/users/confirm' }
@@ -314,17 +313,29 @@ describe 'trails' do
   end
 
   describe 'single resource' do
-    before :all do
-      app.resource :user => :profile
-    end
-    it { app.route_for(:user).should               == '/user' }
-    it { app.route_for(:new_user).should           == '/user/new' }
-    it { app.route_for(:edit_user).should          == '/user/edit' }
-    it { app.route_for(:user_profile).should       == '/user/profile' }
-    it { app.route_for(:new_user_profile).should   == '/user/profile/new' }
-    it { app.route_for(:edit_user_profile).should  == '/user/profile/edit' }
+    describe 'basic' do
+      before :all do
+        app.resource :user => :profile
+      end
+      it { app.route_for(:user).should               == '/user' }
+      it { app.route_for(:new_user).should           == '/user/new' }
+      it { app.route_for(:edit_user).should          == '/user/edit' }
+      it { app.route_for(:user_profile).should       == '/user/profile' }
+      it { app.route_for(:new_user_profile).should   == '/user/profile/new' }
+      it { app.route_for(:edit_user_profile).should  == '/user/profile/edit' }
+    end
+
+    describe 'as namespace' do
+      before :all do
+        app.resource :user do
+          map(:confirm)
+        end
+      end
+      it { app.route_for(:user_confirm).should  == '/user/confirm' }
+    end
   end
 
+
   describe 'finding route for scope' do
     before :all do
       @scope = Sinatra::Trails::Scope.new(app, :admin)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-trails
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-05 00:00:00.000000000Z
+date: 2011-11-29 00:00:00.000000000 -06:00
+default_executable: 
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &2156534160 !ruby/object:Gem::Requirement
+  requirement: &70095708882740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2156534160
+  version_requirements: *70095708882740
 - !ruby/object:Gem::Dependency
   name: i18n
-  requirement: &2156533740 !ruby/object:Gem::Requirement
+  requirement: &70095708881640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +33,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2156533740
+  version_requirements: *70095708881640
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &2156533240 !ruby/object:Gem::Requirement
+  requirement: &70095708880780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +44,10 @@ dependencies:
         version: '3.0'
   type: :runtime
   prerelease: false
-  version_requirements: *2156533240
+  version_requirements: *70095708880780
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2156532820 !ruby/object:Gem::Requirement
+  requirement: &70095708880260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +55,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156532820
+  version_requirements: *70095708880260
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2156532360 !ruby/object:Gem::Requirement
+  requirement: &70095708879500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +66,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156532360
+  version_requirements: *70095708879500
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &2156555720 !ruby/object:Gem::Requirement
+  requirement: &70095708878680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,7 +77,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156555720
+  version_requirements: *70095708878680
 description: A named routes Sinatra DSL inspired by Rails routing
 email:
 - macarui@gmail.com
@@ -87,12 +88,14 @@ files:
 - .gitignore
 - .rspec
 - Gemfile
+- README.rdoc
 - Rakefile
 - lib/sinatra/trails.rb
 - lib/sinatra/trails/version.rb
 - spec/route_generation_spec.rb
 - spec/spec_helper.rb
 - trails.gemspec
+has_rdoc: true
 homepage: http://github.com/maca/trails
 licenses: []
 post_install_message: 
@@ -113,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: sinatra-trails
-rubygems_version: 1.8.8
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: A named routes Sinatra DSL inspired by Rails routing