vigetlabs-routing-filter 0.2.4

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1 @@
1
+ script: "ruby -Ilib -Itest test/all.rb"
data/Gemfile ADDED
@@ -0,0 +1,8 @@
1
+ source :rubygems
2
+
3
+ group :test do
4
+ gem 'rails', '~> 3.0'
5
+ gem 'i18n'
6
+ gem 'test_declarative'
7
+ gem 'ruby-debug'
8
+ end
@@ -0,0 +1,82 @@
1
+ GEM
2
+ remote: http://rubygems.org/
3
+ specs:
4
+ abstract (1.0.0)
5
+ actionmailer (3.0.3)
6
+ actionpack (= 3.0.3)
7
+ mail (~> 2.2.9)
8
+ actionpack (3.0.3)
9
+ activemodel (= 3.0.3)
10
+ activesupport (= 3.0.3)
11
+ builder (~> 2.1.2)
12
+ erubis (~> 2.6.6)
13
+ i18n (~> 0.4)
14
+ rack (~> 1.2.1)
15
+ rack-mount (~> 0.6.13)
16
+ rack-test (~> 0.5.6)
17
+ tzinfo (~> 0.3.23)
18
+ activemodel (3.0.3)
19
+ activesupport (= 3.0.3)
20
+ builder (~> 2.1.2)
21
+ i18n (~> 0.4)
22
+ activerecord (3.0.3)
23
+ activemodel (= 3.0.3)
24
+ activesupport (= 3.0.3)
25
+ arel (~> 2.0.2)
26
+ tzinfo (~> 0.3.23)
27
+ activeresource (3.0.3)
28
+ activemodel (= 3.0.3)
29
+ activesupport (= 3.0.3)
30
+ activesupport (3.0.3)
31
+ arel (2.0.6)
32
+ builder (2.1.2)
33
+ columnize (0.3.2)
34
+ erubis (2.6.6)
35
+ abstract (>= 1.0.0)
36
+ i18n (0.5.0)
37
+ linecache (0.43)
38
+ mail (2.2.12)
39
+ activesupport (>= 2.3.6)
40
+ i18n (>= 0.4.0)
41
+ mime-types (~> 1.16)
42
+ treetop (~> 1.4.8)
43
+ mime-types (1.16)
44
+ polyglot (0.3.1)
45
+ rack (1.2.1)
46
+ rack-mount (0.6.13)
47
+ rack (>= 1.0.0)
48
+ rack-test (0.5.6)
49
+ rack (>= 1.0)
50
+ rails (3.0.3)
51
+ actionmailer (= 3.0.3)
52
+ actionpack (= 3.0.3)
53
+ activerecord (= 3.0.3)
54
+ activeresource (= 3.0.3)
55
+ activesupport (= 3.0.3)
56
+ bundler (~> 1.0)
57
+ railties (= 3.0.3)
58
+ railties (3.0.3)
59
+ actionpack (= 3.0.3)
60
+ activesupport (= 3.0.3)
61
+ rake (>= 0.8.7)
62
+ thor (~> 0.14.4)
63
+ rake (0.8.7)
64
+ ruby-debug (0.10.4)
65
+ columnize (>= 0.1)
66
+ ruby-debug-base (~> 0.10.4.0)
67
+ ruby-debug-base (0.10.4)
68
+ linecache (>= 0.3)
69
+ test_declarative (0.0.5)
70
+ thor (0.14.6)
71
+ treetop (1.4.9)
72
+ polyglot (>= 0.3.1)
73
+ tzinfo (0.3.23)
74
+
75
+ PLATFORMS
76
+ ruby
77
+
78
+ DEPENDENCIES
79
+ i18n
80
+ rails (~> 3.0)
81
+ ruby-debug
82
+ test_declarative
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2008 Sven Fuchs
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,204 @@
1
+ # Routing Filter
2
+
3
+ Routing filters wrap around the complex beast that the Rails routing system is
4
+ to allow for unseen flexibility and power in Rails URL recognition and
5
+ generation.
6
+
7
+ As powerful and awesome the Rails' routes are, when you need to design your
8
+ URLs in a manner that only slightly leaves the paved cowpaths of Rails
9
+ conventions, you're usually unable to use all the goodness of helpers and
10
+ convenience that Rails ships with.
11
+
12
+ This library comes with four more or less reusable filters and it is easy to
13
+ implement custom ones. Maybe the most popular one is the Locale routing filter:
14
+
15
+ * `Locale` - prepends the page's :locale (e.g. /de/products)
16
+ * `Pagination` - appends page/:num (e.g. /products/page/2)
17
+ * `Uuid` - prepends a uuid for authentication or other purposes (e.g. /d00fbbd1-82b6-4c1a-a57d-098d529d6854/products/1)
18
+ * `Extension` - appends an extension (e.g. /products.html)
19
+
20
+ Please note that Rails 3's routing system is much more powerful and flexible
21
+ than Rails 2 was. There are many usecases that now can be covered with just
22
+ Rails 3 default routing features that weren't doable in Rails 2. For an example
23
+ of a quite complex and flexible route see this [gist by Andrew White](http://gist.github.com/653543)
24
+
25
+ ## Requirements
26
+
27
+ routing-filter currently only works with Rails. It should not be all too hard
28
+ to get it working with plain Rack::Mount but I haven't had that usecase, yet.
29
+
30
+ ## Installation
31
+
32
+ Just install the Gem:
33
+
34
+ $ gem install routing-filter
35
+
36
+ The Gem should work out of the box for Rails 3 after specifying it in your
37
+ application's Gemfile.
38
+
39
+ # Gemfile
40
+ gem 'routing-filter'
41
+
42
+ In order to use it with Rails 2.x you could specify it in your environment.rb
43
+
44
+ # config/environment.rb
45
+ gem 'routing-filter'
46
+
47
+ ## Usage
48
+
49
+ Once the Gem has loaded you can setup the filters in your routes file like this:
50
+
51
+ # in config/routes.rb
52
+ Rails.application.routes.draw do
53
+ filter :pagination, :uuid
54
+ end
55
+
56
+ Filters can also accept options:
57
+
58
+ Rails.application.routes.draw do
59
+ filter :extension, :exclude => %r(^admin/)
60
+ end
61
+
62
+ ## Running the tests
63
+
64
+ There are two Gemfiles in the `ci` directory in order to run the tests against different dependencies. The Rails 3 Gemfile is symlinked to the root folder, so it will be used by default.
65
+
66
+ Running the tests with Rails 3.x:
67
+
68
+ $ bundle install
69
+ $ ruby -Itest -Ilib test/all.rb
70
+
71
+ Running the tests with Rails 2.3.x:
72
+
73
+ $ BUNDLE_GEMFILE=ci/Gemfile.rails-2.3.x bundle install
74
+ $ BUNDLE_GEMFILE=ci/Gemfile.rails-2.3.x ruby -Itest -Ilib test/all.rb
75
+
76
+ ## Filter order
77
+
78
+ You can picture the way routing-filter wraps filters around your application as a russian puppet pattern. Your application sits in the center and is wrapped by a number of filters. An incoming request's path will be past through these layers of filters from the outside in until it is passed to the regular application routes set. When you generate URLs on the other hand then the filters will be run from the inside out.
79
+
80
+ Filter order might be confusing at first. The reason for that is that the way rack/mount (which is used by Rails as a core routing engine) is confusing in this respect and Rails tries to make the best of it.
81
+
82
+ Suppose you have a filter :custom in your application routes.rb file and an engine that adds a :common filter. Then Rails makes it so that your application's routes file will be loaded first (basically route.rb files are loaded in reverse engine load order).
83
+
84
+ Thus routing-filter will make your :custom filter the *inner-most* filter, wrapping the application *first*. The :common filter from your engine will be wrapped *around* that onion and will be made the *outer-most* filter.
85
+
86
+ This way common base filters (such as the locale filter) can run first and do not need to know about the specifics of other (more specialized, custom) filters. Custom filters on the other hand can easily take into account that common filters might already have run and adjust accordingly.
87
+
88
+
89
+ ## Implementing your own filters
90
+
91
+ For example implementations have a look at the existing filters in
92
+ [lib/routing_filter/filters](http://github.com/svenfuchs/routing-filter/tree/master/lib/routing_filter/filters)
93
+
94
+ The following would be a sceleton of an empty filter:
95
+
96
+ module RoutingFilter
97
+ class Awesomeness < Filter
98
+ def around_recognize(path, env, &block)
99
+ # Alter the path here before it gets recognized.
100
+ # Make sure to yield (calls the next around filter if present and
101
+ # eventually `recognize_path` on the routeset):
102
+ yield.tap do |params|
103
+ # You can additionally modify the params here before they get passed
104
+ # to the controller.
105
+ end
106
+ end
107
+
108
+ def around_generate(params, &block)
109
+ # Alter arguments here before they are passed to `url_for`.
110
+ # Make sure to yield (calls the next around filter if present and
111
+ # eventually `url_for` on the controller):
112
+ yield.tap do |result|
113
+ # You can change the generated url_or_path here. Make sure to use
114
+ # one of the "in-place" modifying String methods though (like sub!
115
+ # and friends).
116
+ end
117
+ end
118
+ end
119
+ end
120
+
121
+ You can specify the filter explicitely in your routes.rb:
122
+
123
+ Rails.application.routes.draw do
124
+ filter :awesomeness
125
+ end
126
+
127
+ (I am not sure if it makes sense to provide more technical information than
128
+ this because the usage of this plugin definitely requires some advanced
129
+ knowledge about Rails internals and especially its routing system. So, I
130
+ figure, anyone who could use this should also be able to read the code and
131
+ figure out what it's doing much better then from any lengthy documentation.
132
+
133
+ If I'm mistaken on this please drop me an email with your suggestions.)
134
+
135
+
136
+ ## Rationale: Two example usecases
137
+
138
+ ### Conditionally prepending the locale
139
+
140
+ An early usecase from which this originated was the need to define a locale
141
+ at the beginning of an URL in a way so that
142
+
143
+ * the locale can be omitted when it is the default locale
144
+ * all the url\_helpers that are generated by named routes as well as url_for continue to work in
145
+ a concise manner (i.e. without specifying all parameters again and again)
146
+ * ideally also plays nicely with default route helpers in tests/specs
147
+
148
+ You can read about this struggle and two possible, yet unsatisfying solutions
149
+ [here](http://www.artweb-design.de/2007/5/13/concise-localized-rails-url-helpers-solved-twice).
150
+ The conclusion so far is that Rails itself does not provide the tools to solve
151
+ this problem in a clean and dry way.
152
+
153
+ ### Expanding /sections/:id to nested tree segments
154
+
155
+ Another usecase that eventually spawned the implementation of this plugin was
156
+ the need to map an arbitrary count of path segments to a certain model
157
+ instance. In an application that I've been working on recently I needed to
158
+ map URL paths to a nested tree of models like so:
159
+
160
+ root
161
+ + docs
162
+ + api
163
+ + wiki
164
+
165
+ E.g. the docs section should map to the path `/docs`, the api section to
166
+ the path `/docs/api` and so on. Furthermore, after these paths there need to be
167
+ more things to be specified. E.g. the wiki needs to define a whole Rails
168
+ resource with URLs like `/docs/wiki/pages/1/edit`.
169
+
170
+ The only way to solve this problem with Rails' routing toolkit is to map
171
+ a big, bold `/*everything` catch-all ("globbing") route and process the whole
172
+ path in a custom dispatcher.
173
+
174
+ This, of course, is a really unsatisfying solution because one has to
175
+ reimplement everything that Rails routes are here to help with: regarding both
176
+ URL recognition (like parameter mappings, resources, ...) and generation
177
+ (url\_helpers).
178
+
179
+ ## Solution
180
+
181
+ This plugin offers a solution that takes exactly the opposite route.
182
+
183
+ Instead of trying to change things *between* the URL recognition and
184
+ generation stages to achieve the desired result it *wraps around* the whole
185
+ routing system and allows to pre- and post-filter both what goes into it
186
+ (URL recognition) and what comes out of it (URL generation).
187
+
188
+ This way we can leave *everything* else completely untouched.
189
+
190
+ * We can tinker with the URLs that we receive from the server and feed URLs to
191
+ Rails that perfectly match the best breed of Rails' conventions.
192
+ * Inside of the application we can use all the nice helper goodness and
193
+ conveniences that rely on these conventions being followed.
194
+ * Finally we can accept URLs that have been generated by the url\_helpers and,
195
+ again, mutate them in the way that matches our requirements.
196
+
197
+ So, even though the plugin itself is a blatant monkey-patch to one of the
198
+ most complex area of Rails internals, this solution seems to be effectively
199
+ less intrusive and pricey than others are.
200
+
201
+ ## Etc
202
+
203
+ Authors: [Sven Fuchs](http://www.artweb-design.de) <svenfuchs at artweb-design dot de>
204
+ License: MIT
@@ -0,0 +1,31 @@
1
+ $:.unshift File.expand_path('../lib', __FILE__)
2
+ require 'routing_filter/version'
3
+ require 'rake'
4
+ require 'rake/testtask'
5
+
6
+ Rake::TestTask.new do |t|
7
+ t.libs << 'lib' << 'test'
8
+ t.pattern = 'test/**/*_test.rb'
9
+ t.verbose = false
10
+ end
11
+
12
+ begin
13
+ require 'jeweler'
14
+ Jeweler::Tasks.new do |gem|
15
+ gem.name = "vigetlabs-routing-filter"
16
+ gem.summary = %Q{Routing filters wraps around the complex beast that the Rails routing system is, allowing for unseen flexibility and power in Rails URL recognition and generation.}
17
+ gem.description = %Q{Routing filters wraps around the complex beast that the Rails routing system is, allowing for unseen flexibility and power in Rails URL recognition and generation.}
18
+ gem.email = "svenfuchs@artweb-design.de"
19
+ gem.homepage = "https://github.com/vigetlabs/routing-filter"
20
+ gem.authors = ["Sven Fuchs", "Brian Landau", "David Eisinger"]
21
+ gem.add_dependency('actionpack')
22
+ gem.version = RoutingFilter::VERSION
23
+ # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
24
+ end
25
+ Jeweler::GemcutterTasks.new
26
+ rescue LoadError
27
+ puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
28
+ end
29
+
30
+ task :default => :test
31
+
@@ -0,0 +1,8 @@
1
+ source :rubygems
2
+
3
+ group :test do
4
+ gem 'rails', '~> 2.3.0'
5
+ gem 'i18n'
6
+ gem 'test_declarative'
7
+ gem 'ruby-debug'
8
+ end
@@ -0,0 +1,40 @@
1
+ GEM
2
+ remote: http://rubygems.org/
3
+ specs:
4
+ actionmailer (2.3.10)
5
+ actionpack (= 2.3.10)
6
+ actionpack (2.3.10)
7
+ activesupport (= 2.3.10)
8
+ rack (~> 1.1.0)
9
+ activerecord (2.3.10)
10
+ activesupport (= 2.3.10)
11
+ activeresource (2.3.10)
12
+ activesupport (= 2.3.10)
13
+ activesupport (2.3.10)
14
+ columnize (0.3.2)
15
+ i18n (0.5.0)
16
+ linecache (0.43)
17
+ rack (1.1.0)
18
+ rails (2.3.10)
19
+ actionmailer (= 2.3.10)
20
+ actionpack (= 2.3.10)
21
+ activerecord (= 2.3.10)
22
+ activeresource (= 2.3.10)
23
+ activesupport (= 2.3.10)
24
+ rake (>= 0.8.3)
25
+ rake (0.8.7)
26
+ ruby-debug (0.10.4)
27
+ columnize (>= 0.1)
28
+ ruby-debug-base (~> 0.10.4.0)
29
+ ruby-debug-base (0.10.4)
30
+ linecache (>= 0.3)
31
+ test_declarative (0.0.5)
32
+
33
+ PLATFORMS
34
+ ruby
35
+
36
+ DEPENDENCIES
37
+ i18n
38
+ rails (~> 2.3.0)
39
+ ruby-debug
40
+ test_declarative
@@ -0,0 +1,8 @@
1
+ source :rubygems
2
+
3
+ group :test do
4
+ gem 'rails', '~> 3.0'
5
+ gem 'i18n'
6
+ gem 'test_declarative'
7
+ gem 'ruby-debug'
8
+ end
@@ -0,0 +1,40 @@
1
+ PATH
2
+ remote: .
3
+ specs:
4
+ routing-filter (0.2.2)
5
+ actionpack
6
+
7
+ GEM
8
+ remote: http://rubygems.org/
9
+ specs:
10
+ actionmailer (2.3.10)
11
+ actionpack (= 2.3.10)
12
+ actionpack (2.3.10)
13
+ activesupport (= 2.3.10)
14
+ rack (~> 1.1.0)
15
+ activerecord (2.3.10)
16
+ activesupport (= 2.3.10)
17
+ activeresource (2.3.10)
18
+ activesupport (= 2.3.10)
19
+ activesupport (2.3.10)
20
+ i18n (0.5.0)
21
+ rack (1.1.0)
22
+ rails (2.3.10)
23
+ actionmailer (= 2.3.10)
24
+ actionpack (= 2.3.10)
25
+ activerecord (= 2.3.10)
26
+ activeresource (= 2.3.10)
27
+ activesupport (= 2.3.10)
28
+ rake (>= 0.8.3)
29
+ rake (0.8.7)
30
+ test_declarative (0.0.5)
31
+
32
+ PLATFORMS
33
+ ruby
34
+
35
+ DEPENDENCIES
36
+ actionpack
37
+ i18n
38
+ rails (~> 2.3)
39
+ routing-filter!
40
+ test_declarative