periscope-data_mapper 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (6) hide show
  1. data/LICENSE +22 -0
  2. data/README.md +143 -0
  3. data/lib/periscope-data_mapper.rb +1 -0
  4. data/lib/periscope/adapters/data_mapper.rb +18 -0
  5. data/periscope-data_mapper.gemspec +30 -0
  6. metadata +190 -0
data/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ Copyright (c) 2011 Steve Richert
2
+
3
+ MIT License
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining
6
+ a copy of this software and associated documentation files (the
7
+ "Software"), to deal in the Software without restriction, including
8
+ without limitation the rights to use, copy, modify, merge, publish,
9
+ distribute, sublicense, and/or sell copies of the Software, and to
10
+ permit persons to whom the Software is furnished to do so, subject to
11
+ the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be
14
+ included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,143 @@
1
+ # Periscope [![Build Status](https://secure.travis-ci.org/laserlemon/periscope.png)](http://travis-ci.org/laserlemon/periscope) [![Dependency Status](https://gemnasium.com/laserlemon/periscope.png)](https://gemnasium.com/laserlemon/periscope)
2
+
3
+ Periscope provides a simple way to chain scopes on your models and to open those scopes up to your users.
4
+
5
+ ## Installation
6
+
7
+ Periscope sits on top of your favorite ORM. Currently, the following ORMs are supported through individual gems extending Periscope:
8
+
9
+ * ActiveRecord ([periscope-activerecord](https://rubygems.org/gems/periscope-activerecord))
10
+ * MongoMapper ([periscope-mongo_mapper](https://rubygems.org/gems/periscope-mongo_mapper))
11
+ * Mongoid ([periscope-mongoid](https://rubygems.org/gems/periscope-mongoid))
12
+ * DataMapper ([periscope-data_mapper](https://rubygems.org/gems/periscope-data_mapper))
13
+
14
+ Simply add the gem to your bundle and you're off!
15
+
16
+ ## The Problem
17
+
18
+ More often than not, the index action in a RESTful Rails controller is expected to do a lot more than simply return all the records for a given model. We ask it to do all sorts of stuff like filtering, sorting and paginating results. Of course, this is typically done using _scopes_.
19
+
20
+ But it can get ugly building long, complicated chains of scopes in the controller, especially when you try to give your users control over the scoping. Picture this:
21
+
22
+ ```ruby
23
+ def index
24
+ @articles = Article.scoped
25
+ @articles = @articles.published_after(params[:published_after]) if params.key?(:published_after)
26
+ @articles = @articles.published_before(params[:published_before]) if params.key?(:published_before)
27
+ end
28
+ ```
29
+
30
+ You can imagine how bad this would get if more than two scopes were involved.
31
+
32
+ ## The Solution
33
+
34
+ With Periscope, you can have this instead:
35
+
36
+ ```ruby
37
+ def index
38
+ @articles = Article.periscope(request.query_parameters)
39
+ end
40
+ ```
41
+
42
+ The `periscope` method will find keys in your params matching your scope names and chain your scopes for you.
43
+
44
+ **Note:** We're using `request.query_parameters` so that we can exclude our controller and action params. `request.query_parameters` will just return the params that appear in the query string.
45
+
46
+ ## But Wait!
47
+
48
+ "What if I don't want to make all my scopes publicly accessible?"
49
+
50
+ Within your model you can use the `scope_accessible` method to specify which scopes you want Periscope to honor.
51
+
52
+ ```ruby
53
+ class User < ActiveRecord::Base
54
+ scope :gender, lambda{|g| where(gender: g) }
55
+ scope :makes, lambda{|s| where('salary >= ?', s) }
56
+
57
+ scope_accessible :gender
58
+ end
59
+ ```
60
+
61
+ And in your controller:
62
+
63
+ ```ruby
64
+ class UsersController < ApplicationController
65
+ def index
66
+ @users = User.periscope(request.query_parameters)
67
+ end
68
+ end
69
+ ```
70
+
71
+ Requests to `/users?gender=male` will filter results to only male users. But a request to `/users?makes=1000000` will return all users, silently ignoring the protected scope.
72
+
73
+ By default, all scopes are protected.
74
+
75
+ ## There's More!
76
+
77
+ ### Custom Parameter Parsing
78
+
79
+ Sometimes the values you get from the query parameters aren't quite good enough. They may need to be massaged in order to work with your scopes and class methods. In those cases, you can provide a `:parser` option to your `scope_accessible` method.
80
+
81
+ Parsers must respond to the `call` method, receiving the raw query parameter and returning an array of arguments to pass to the scope or class method.
82
+
83
+ ```ruby
84
+ class User < ActiveRecord::Base
85
+ scope :gender, lambda{|g| where(gender: g) }
86
+
87
+ scope_accessible :gender, parser: lambda{|g| [g.downcase] }
88
+ end
89
+ ```
90
+
91
+ ### On/Off Scopes
92
+
93
+ But not all scopes accept arguments. For scopes that you want to toggle on or off, you can set a `:boolean => true` option. Whenever the received parameter is truthy, the scope will be applied. Otherwise, it will be skipped.
94
+
95
+ ```ruby
96
+ class User < ActiveRecord::Base
97
+ scope :male, where(gender: 'male')
98
+ scope :female, where(gender: 'female')
99
+
100
+ scope_accessible :male, :female, boolean: true
101
+ end
102
+ ```
103
+
104
+ ### Custom Method Names
105
+
106
+ Sometimes the query parameters you want to open up to your users may collide with existing method names or reserved Ruby words. In order to avoid collision, you can set a `:method` option to specify what method to use for a query parameter.
107
+
108
+ ```ruby
109
+ class Project < ActiveRecord::Base
110
+ scope_accessible :begin, method: :begins_after
111
+ scope_accessible :end, method: :ends_before
112
+
113
+ def self.begins_after(date)
114
+ where('begins_at >= ?', date)
115
+ end
116
+
117
+ def self.ends_before(date)
118
+ where('ends_at <= ?', date)
119
+ end
120
+ end
121
+ ```
122
+
123
+ Alternatively, you can set `:prefix` and/or `:suffix` options, which will be applied to the query parameter name to determine the corresponding method name.
124
+
125
+ ```ruby
126
+ class Project < ActiveRecord::Base
127
+ scope_accessible :begin, :end, suffix: '_date'
128
+
129
+ def self.begin_date(date)
130
+ where('begins_at >= ?', date)
131
+ end
132
+
133
+ def self.end_date(date)
134
+ where('ends_at <= ?', date)
135
+ end
136
+ end
137
+ ```
138
+
139
+ ## This sucks. How can I make it better?
140
+
141
+ 1. Fork it.
142
+ 2. Make it better.
143
+ 3. Send me a pull request.
data/lib/periscope-data_mapper.rb ADDED
@@ -0,0 +1 @@
1
+ require 'periscope/adapters/data_mapper'
data/lib/periscope/adapters/data_mapper.rb ADDED
@@ -0,0 +1,18 @@
1
+ require 'periscope'
2
+ require 'data_mapper'
3
+
4
+ module Periscope
5
+ module Adapters
6
+ module DataMapper
7
+ include Periscope
8
+
9
+ private
10
+
11
+ def periscope_default_scope
12
+ all
13
+ end
14
+ end
15
+ end
16
+ end
17
+
18
+ DataMapper::Model.send(:include, Periscope::Adapters::DataMapper)
data/periscope-data_mapper.gemspec ADDED
@@ -0,0 +1,30 @@
1
+ # encoding: utf-8
2
+
3
+ Gem::Specification.new do |gem|
4
+ gem.name = 'periscope-data_mapper'
5
+ gem.version = '1.0.0'
6
+
7
+ gem.authors = ['Steve Richert']
8
+ gem.email = ['steve.richert@gmail.com']
9
+ gem.description = %(Push your DataMapper models' scopes up to the surface)
10
+ gem.summary = gem.description
11
+ gem.homepage = 'https://github.com/laserlemon/periscope'
12
+
13
+ gem.add_dependency 'data_mapper', '~> 1.0'
14
+ gem.add_dependency 'periscope', '~> 1.0'
15
+
16
+ gem.add_development_dependency 'database_cleaner', '~> 0.8'
17
+ gem.add_development_dependency 'dm-sqlite-adapter', '~> 1.0'
18
+ gem.add_development_dependency 'factory_girl', '>= 2', '< 4'
19
+ gem.add_development_dependency 'rake', '~> 0.9'
20
+ gem.add_development_dependency 'rspec', '~> 2.0'
21
+ gem.add_development_dependency 'sqlite3'
22
+
23
+ gem.files = %w(
24
+ LICENSE
25
+ lib/periscope-data_mapper.rb
26
+ lib/periscope/adapters/data_mapper.rb
27
+ periscope-data_mapper.gemspec
28
+ README.md
29
+ )
30
+ end
metadata ADDED
@@ -0,0 +1,190 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: periscope-data_mapper
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0
5
+ prerelease:
6
+ platform: ruby
7
+ authors:
8
+ - Steve Richert
9
+ autorequire:
10
+ bindir: bin
11
+ cert_chain: []
12
+ date: 2012-06-30 00:00:00.000000000 Z
13
+ dependencies:
14
+ - !ruby/object:Gem::Dependency
15
+ name: data_mapper
16
+ requirement: !ruby/object:Gem::Requirement
17
+ none: false
18
+ requirements:
19
+ - - ~>
20
+ - !ruby/object:Gem::Version
21
+ version: '1.0'
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ none: false
26
+ requirements:
27
+ - - ~>
28
+ - !ruby/object:Gem::Version
29
+ version: '1.0'
30
+ - !ruby/object:Gem::Dependency
31
+ name: periscope
32
+ requirement: !ruby/object:Gem::Requirement
33
+ none: false
34
+ requirements:
35
+ - - ~>
36
+ - !ruby/object:Gem::Version
37
+ version: '1.0'
38
+ type: :runtime
39
+ prerelease: false
40
+ version_requirements: !ruby/object:Gem::Requirement
41
+ none: false
42
+ requirements:
43
+ - - ~>
44
+ - !ruby/object:Gem::Version
45
+ version: '1.0'
46
+ - !ruby/object:Gem::Dependency
47
+ name: database_cleaner
48
+ requirement: !ruby/object:Gem::Requirement
49
+ none: false
50
+ requirements:
51
+ - - ~>
52
+ - !ruby/object:Gem::Version
53
+ version: '0.8'
54
+ type: :development
55
+ prerelease: false
56
+ version_requirements: !ruby/object:Gem::Requirement
57
+ none: false
58
+ requirements:
59
+ - - ~>
60
+ - !ruby/object:Gem::Version
61
+ version: '0.8'
62
+ - !ruby/object:Gem::Dependency
63
+ name: dm-sqlite-adapter
64
+ requirement: !ruby/object:Gem::Requirement
65
+ none: false
66
+ requirements:
67
+ - - ~>
68
+ - !ruby/object:Gem::Version
69
+ version: '1.0'
70
+ type: :development
71
+ prerelease: false
72
+ version_requirements: !ruby/object:Gem::Requirement
73
+ none: false
74
+ requirements:
75
+ - - ~>
76
+ - !ruby/object:Gem::Version
77
+ version: '1.0'
78
+ - !ruby/object:Gem::Dependency
79
+ name: factory_girl
80
+ requirement: !ruby/object:Gem::Requirement
81
+ none: false
82
+ requirements:
83
+ - - ! '>='
84
+ - !ruby/object:Gem::Version
85
+ version: '2'
86
+ - - <
87
+ - !ruby/object:Gem::Version
88
+ version: '4'
89
+ type: :development
90
+ prerelease: false
91
+ version_requirements: !ruby/object:Gem::Requirement
92
+ none: false
93
+ requirements:
94
+ - - ! '>='
95
+ - !ruby/object:Gem::Version
96
+ version: '2'
97
+ - - <
98
+ - !ruby/object:Gem::Version
99
+ version: '4'
100
+ - !ruby/object:Gem::Dependency
101
+ name: rake
102
+ requirement: !ruby/object:Gem::Requirement
103
+ none: false
104
+ requirements:
105
+ - - ~>
106
+ - !ruby/object:Gem::Version
107
+ version: '0.9'
108
+ type: :development
109
+ prerelease: false
110
+ version_requirements: !ruby/object:Gem::Requirement
111
+ none: false
112
+ requirements:
113
+ - - ~>
114
+ - !ruby/object:Gem::Version
115
+ version: '0.9'
116
+ - !ruby/object:Gem::Dependency
117
+ name: rspec
118
+ requirement: !ruby/object:Gem::Requirement
119
+ none: false
120
+ requirements:
121
+ - - ~>
122
+ - !ruby/object:Gem::Version
123
+ version: '2.0'
124
+ type: :development
125
+ prerelease: false
126
+ version_requirements: !ruby/object:Gem::Requirement
127
+ none: false
128
+ requirements:
129
+ - - ~>
130
+ - !ruby/object:Gem::Version
131
+ version: '2.0'
132
+ - !ruby/object:Gem::Dependency
133
+ name: sqlite3
134
+ requirement: !ruby/object:Gem::Requirement
135
+ none: false
136
+ requirements:
137
+ - - ! '>='
138
+ - !ruby/object:Gem::Version
139
+ version: '0'
140
+ type: :development
141
+ prerelease: false
142
+ version_requirements: !ruby/object:Gem::Requirement
143
+ none: false
144
+ requirements:
145
+ - - ! '>='
146
+ - !ruby/object:Gem::Version
147
+ version: '0'
148
+ description: Push your DataMapper models' scopes up to the surface
149
+ email:
150
+ - steve.richert@gmail.com
151
+ executables: []
152
+ extensions: []
153
+ extra_rdoc_files: []
154
+ files:
155
+ - LICENSE
156
+ - lib/periscope-data_mapper.rb
157
+ - lib/periscope/adapters/data_mapper.rb
158
+ - periscope-data_mapper.gemspec
159
+ - README.md
160
+ homepage: https://github.com/laserlemon/periscope
161
+ licenses: []
162
+ post_install_message:
163
+ rdoc_options: []
164
+ require_paths:
165
+ - lib
166
+ required_ruby_version: !ruby/object:Gem::Requirement
167
+ none: false
168
+ requirements:
169
+ - - ! '>='
170
+ - !ruby/object:Gem::Version
171
+ version: '0'
172
+ segments:
173
+ - 0
174
+ hash: -3628630839409987277
175
+ required_rubygems_version: !ruby/object:Gem::Requirement
176
+ none: false
177
+ requirements:
178
+ - - ! '>='
179
+ - !ruby/object:Gem::Version
180
+ version: '0'
181
+ segments:
182
+ - 0
183
+ hash: -3628630839409987277
184
+ requirements: []
185
+ rubyforge_project:
186
+ rubygems_version: 1.8.24
187
+ signing_key:
188
+ specification_version: 3
189
+ summary: Push your DataMapper models' scopes up to the surface
190
+ test_files: []