warped 0.1.0 → 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.rubocop.yml +19 -0
- data/Gemfile +0 -2
- data/Gemfile.lock +24 -18
- data/README.md +13 -271
- data/docs/controllers/FILTERABLE.md +114 -0
- data/docs/controllers/PAGEABLE.md +70 -0
- data/docs/controllers/README.md +8 -0
- data/docs/controllers/SEARCHABLE.md +95 -0
- data/docs/controllers/SORTABLE.md +94 -0
- data/docs/controllers/TABULATABLE.md +28 -0
- data/docs/jobs/README.md +22 -0
- data/docs/services/README.md +81 -0
- data/lib/generators/warped/install_generator.rb +1 -1
- data/lib/warped/controllers/filterable/ui.rb +68 -0
- data/lib/warped/controllers/filterable.rb +9 -5
- data/lib/warped/controllers/pageable/ui.rb +60 -0
- data/lib/warped/controllers/pageable.rb +10 -10
- data/lib/warped/controllers/searchable/ui.rb +35 -0
- data/lib/warped/controllers/searchable.rb +2 -0
- data/lib/warped/controllers/sortable/ui.rb +58 -0
- data/lib/warped/controllers/sortable.rb +2 -2
- data/lib/warped/controllers/tabulatable/ui.rb +50 -0
- data/lib/warped/controllers/tabulatable.rb +7 -18
- data/lib/warped/emails/components/align.rb +21 -0
- data/lib/warped/emails/components/base.rb +116 -0
- data/lib/warped/emails/components/button.rb +58 -0
- data/lib/warped/emails/components/divider.rb +15 -0
- data/lib/warped/emails/components/heading.rb +65 -0
- data/lib/warped/emails/components/layouts/columns.rb +36 -0
- data/lib/warped/emails/components/layouts/cta.rb +38 -0
- data/lib/warped/emails/components/layouts/main.rb +34 -0
- data/lib/warped/emails/components/link.rb +36 -0
- data/lib/warped/emails/components/spacer.rb +15 -0
- data/lib/warped/emails/components/stepper.rb +104 -0
- data/lib/warped/emails/components/table.rb +37 -0
- data/lib/warped/emails/components/text.rb +67 -0
- data/lib/warped/emails/helpers.rb +26 -0
- data/lib/warped/emails/slottable.rb +61 -0
- data/lib/warped/emails/styleable.rb +160 -0
- data/lib/warped/queries/filter.rb +32 -12
- data/lib/warped/version.rb +1 -1
- data/lib/warped.rb +1 -0
- metadata +31 -3
- data/lib/warped/emails/.keep +0 -0
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 01d84d855e451182cddf0b6d9e38d922e0dfd40c5ee05752496759d5344b042b
|
4
|
+
data.tar.gz: 9d0ddb61f7af15597abb5e0a12f11cbb602f86b2f52763288f4be797f2d41509
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 4b9d8acfdfd217f5755800657688ce6e2c5f7ddab564a8b658c6a94ee38d8b19ae1dc5f416ea3996d103015cf09793734beeaa63b1388356347b5354eb65da10
|
7
|
+
data.tar.gz: '0407936f782cdc2dbb0f210b43a7204a6758866e13bd1eb6772b3410e7063f49909dc3ed60d3cfd081ece0dfdccc10a6ced6e4f295d407f4795ea9f4bbe00b85'
|
data/.rubocop.yml
CHANGED
@@ -18,13 +18,32 @@ Layout/LineLength:
|
|
18
18
|
Exclude:
|
19
19
|
- "lib/warped/queries/paginate.rb"
|
20
20
|
|
21
|
+
Metrics/AbcSize:
|
22
|
+
Exclude:
|
23
|
+
- "lib/warped/controllers/filterable/ui.rb"
|
24
|
+
- "lib/warped/controllers/sortable/ui.rb"
|
25
|
+
- "lib/warped/emails/components/**/*.rb"
|
26
|
+
- "lib/warped/queries/filter.rb"
|
27
|
+
|
21
28
|
Metrics/BlockLength:
|
22
29
|
Exclude:
|
30
|
+
- "lib/warped/emails/components/**/*.rb"
|
23
31
|
- "spec/**/*"
|
24
32
|
|
33
|
+
Metrics/ParameterLists:
|
34
|
+
Exclude:
|
35
|
+
- "lib/warped/emails/components/**/*.rb"
|
36
|
+
|
25
37
|
Metrics/CyclomaticComplexity:
|
26
38
|
Exclude:
|
27
39
|
- "lib/warped/queries/filter.rb"
|
28
40
|
|
29
41
|
Metrics/MethodLength:
|
30
42
|
Max: 20
|
43
|
+
Exclude:
|
44
|
+
- lib/warped/queries/filter.rb
|
45
|
+
|
46
|
+
Style/OptionalArguments:
|
47
|
+
Exclude:
|
48
|
+
- lib/warped/emails/components/button.rb
|
49
|
+
- lib/warped/emails/components/link.rb
|
data/Gemfile
CHANGED
data/Gemfile.lock
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
PATH
|
2
2
|
remote: .
|
3
3
|
specs:
|
4
|
-
warped (0.
|
4
|
+
warped (0.2.0)
|
5
5
|
rails (>= 6.0, < 8.0)
|
6
6
|
zeitwerk (>= 2.4)
|
7
7
|
|
@@ -90,12 +90,8 @@ GEM
|
|
90
90
|
connection_pool (2.4.1)
|
91
91
|
crass (1.0.6)
|
92
92
|
date (3.3.4)
|
93
|
-
debug (1.9.1)
|
94
|
-
irb (~> 1.10)
|
95
|
-
reline (>= 0.3.8)
|
96
93
|
diff-lcs (1.5.1)
|
97
|
-
drb (2.2.
|
98
|
-
ruby2_keywords
|
94
|
+
drb (2.2.1)
|
99
95
|
erubi (1.12.0)
|
100
96
|
globalid (1.2.1)
|
101
97
|
activesupport (>= 6.1)
|
@@ -115,7 +111,7 @@ GEM
|
|
115
111
|
net-imap
|
116
112
|
net-pop
|
117
113
|
net-smtp
|
118
|
-
marcel (1.0.
|
114
|
+
marcel (1.0.4)
|
119
115
|
mini_mime (1.1.5)
|
120
116
|
minitest (5.22.2)
|
121
117
|
mutex_m (0.2.0)
|
@@ -129,8 +125,18 @@ GEM
|
|
129
125
|
net-smtp (0.4.0.1)
|
130
126
|
net-protocol
|
131
127
|
nio4r (2.7.0)
|
128
|
+
nokogiri (1.16.2-aarch64-linux)
|
129
|
+
racc (~> 1.4)
|
130
|
+
nokogiri (1.16.2-arm-linux)
|
131
|
+
racc (~> 1.4)
|
132
132
|
nokogiri (1.16.2-arm64-darwin)
|
133
133
|
racc (~> 1.4)
|
134
|
+
nokogiri (1.16.2-x86-linux)
|
135
|
+
racc (~> 1.4)
|
136
|
+
nokogiri (1.16.2-x86_64-darwin)
|
137
|
+
racc (~> 1.4)
|
138
|
+
nokogiri (1.16.2-x86_64-linux)
|
139
|
+
racc (~> 1.4)
|
134
140
|
parallel (1.24.0)
|
135
141
|
parser (3.3.0.5)
|
136
142
|
ast (~> 2.4.1)
|
@@ -180,7 +186,7 @@ GEM
|
|
180
186
|
rdoc (6.6.2)
|
181
187
|
psych (>= 4.0.0)
|
182
188
|
regexp_parser (2.9.0)
|
183
|
-
reline (0.4.
|
189
|
+
reline (0.4.3)
|
184
190
|
io-console (~> 0.5)
|
185
191
|
rexml (3.2.6)
|
186
192
|
rspec (3.13.0)
|
@@ -196,7 +202,7 @@ GEM
|
|
196
202
|
diff-lcs (>= 1.2.0, < 2.0)
|
197
203
|
rspec-support (~> 3.13.0)
|
198
204
|
rspec-support (3.13.1)
|
199
|
-
rubocop (1.
|
205
|
+
rubocop (1.61.0)
|
200
206
|
json (~> 2.3)
|
201
207
|
language_server-protocol (>= 3.17.0)
|
202
208
|
parallel (~> 1.10)
|
@@ -207,12 +213,11 @@ GEM
|
|
207
213
|
rubocop-ast (>= 1.30.0, < 2.0)
|
208
214
|
ruby-progressbar (~> 1.7)
|
209
215
|
unicode-display_width (>= 2.4.0, < 3.0)
|
210
|
-
rubocop-ast (1.
|
211
|
-
parser (>= 3.
|
216
|
+
rubocop-ast (1.31.1)
|
217
|
+
parser (>= 3.3.0.4)
|
212
218
|
ruby-progressbar (1.13.0)
|
213
|
-
ruby2_keywords (0.0.5)
|
214
219
|
stringio (3.1.0)
|
215
|
-
thor (1.3.
|
220
|
+
thor (1.3.1)
|
216
221
|
timeout (0.4.1)
|
217
222
|
tzinfo (2.0.6)
|
218
223
|
concurrent-ruby (~> 1.0)
|
@@ -224,17 +229,18 @@ GEM
|
|
224
229
|
zeitwerk (2.6.13)
|
225
230
|
|
226
231
|
PLATFORMS
|
227
|
-
|
228
|
-
|
229
|
-
arm64-darwin
|
232
|
+
aarch64-linux
|
233
|
+
arm-linux
|
234
|
+
arm64-darwin
|
235
|
+
x86-linux
|
236
|
+
x86_64-darwin
|
230
237
|
x86_64-linux
|
231
238
|
|
232
239
|
DEPENDENCIES
|
233
|
-
debug (~> 1.5)
|
234
240
|
rake (~> 13.0)
|
235
241
|
rspec (~> 3.0)
|
236
242
|
rubocop (~> 1.21)
|
237
243
|
warped!
|
238
244
|
|
239
245
|
BUNDLED WITH
|
240
|
-
2.
|
246
|
+
2.5.6
|
data/README.md
CHANGED
@@ -7,7 +7,7 @@ Develop rails applications at the speed of thought. Warped is a collection of to
|
|
7
7
|
|
8
8
|
Install the gem and add to the Rails application's Gemfile by executing:
|
9
9
|
|
10
|
-
$ bundle add warped
|
10
|
+
$ bundle add warped
|
11
11
|
|
12
12
|
Then run the generator to create the configuration file:
|
13
13
|
|
@@ -57,95 +57,7 @@ GET /users?email=john@example.com
|
|
57
57
|
GET /users?created_at=2021-01-01
|
58
58
|
```
|
59
59
|
|
60
|
-
|
61
|
-
|
62
|
-
The `filterable_by` method can also be used to reference fields in associated tables. For example, to filter the users by the name of the company they work for, the following can be done:
|
63
|
-
|
64
|
-
```ruby
|
65
|
-
class UsersController < ApplicationController
|
66
|
-
include Warped::Controllers::Filterable
|
67
|
-
|
68
|
-
filterable_by :name, :email, :created_at, 'companies.name'
|
69
|
-
|
70
|
-
def index
|
71
|
-
users = filter(User.joins(:company))
|
72
|
-
render json: users
|
73
|
-
end
|
74
|
-
end
|
75
|
-
```
|
76
|
-
|
77
|
-
Request examples:
|
78
|
-
```
|
79
|
-
GET /users?name=John
|
80
|
-
GET /users?companies.name=Acme
|
81
|
-
```
|
82
|
-
|
83
|
-
##### Renaming the filter query parameters
|
84
|
-
|
85
|
-
If you don't want to use the field name as the query parameter (as to not expose the database schema, or when joining the same table multiple times),
|
86
|
-
you can specify the query parameter to use for each field:
|
87
|
-
|
88
|
-
```ruby
|
89
|
-
class UsersController < ApplicationController
|
90
|
-
include Warped::Controllers::Filterable
|
91
|
-
|
92
|
-
filterable_by 'companies.name' => :company_name, 'users.name' => :user_name
|
93
|
-
|
94
|
-
def index
|
95
|
-
users = filter(User.join(:company))
|
96
|
-
render json: users
|
97
|
-
end
|
98
|
-
end
|
99
|
-
```
|
100
|
-
|
101
|
-
Request examples:
|
102
|
-
```
|
103
|
-
GET /users?user_name=John
|
104
|
-
GET /users?company_name=Acme
|
105
|
-
```
|
106
|
-
|
107
|
-
##### Using filters other than `eq`
|
108
|
-
|
109
|
-
By default, the `filter` method will use the `eq` filter method to filter the records. If you want to use a different filter method, you can specify the filter "relation" in the query parameter:
|
110
|
-
|
111
|
-
```ruby
|
112
|
-
class UsersController < ApplicationController
|
113
|
-
include Warped::Controllers::Filterable
|
114
|
-
|
115
|
-
filterable_by :name, :age
|
116
|
-
|
117
|
-
def index
|
118
|
-
users = filter(User.all)
|
119
|
-
render json: users
|
120
|
-
end
|
121
|
-
end
|
122
|
-
```
|
123
|
-
|
124
|
-
Request examples:
|
125
|
-
```
|
126
|
-
GET /users?name=John # returns users with name John
|
127
|
-
GET /users?name[]=John&name[]=Jane # returns users where the name is in ('John', 'Jane')
|
128
|
-
GET /users?age.rel=is_null # returns users where the age is null
|
129
|
-
GET /users?age.rel=is_not_null # returns users where the age is not null
|
130
|
-
GET /users?age.rel=between&age[]=18&age[]=30 # returns users with age between 18 and 30
|
131
|
-
GET /users?age.rel=%3E%0A&age=18 # returns users with age greater than 18, %3E%0A is url encoded for ">"
|
132
|
-
```
|
133
|
-
|
134
|
-
The full list of filter relations is:
|
135
|
-
- `=` (default) - equals
|
136
|
-
- `!=` - not equals
|
137
|
-
- `>` - greater than
|
138
|
-
- `>=` - greater than or equals
|
139
|
-
- `<` - less than
|
140
|
-
- `<=` - less than or equals
|
141
|
-
- `between` - between (requires two values)
|
142
|
-
- `in` - in (default when multiple values are provided)
|
143
|
-
- `not_in` - not in (requires multiple values)
|
144
|
-
- `starts_with` - starts with
|
145
|
-
- `ends_with` - ends with
|
146
|
-
- `contains` - contains
|
147
|
-
- `is_null` - is null (does not require a value)
|
148
|
-
- `is_not_null` - is not null (does not require a value)
|
60
|
+
[Complete documentation for Warped::Controllers::Filterable](docs/controllers/FILTERABLE.md).
|
149
61
|
|
150
62
|
#### Warped::Controllers::Searchable
|
151
63
|
|
@@ -181,67 +93,7 @@ GET /users?q=John
|
|
181
93
|
# calls #search(User.all, search_term: 'John', model_search_scope: :search) in the controller
|
182
94
|
```
|
183
95
|
|
184
|
-
|
185
|
-
|
186
|
-
You can customize the default query parameter by:
|
187
|
-
1. Passing fetching the fetch term from the params hash, and passing it directly to the search method:
|
188
|
-
|
189
|
-
```ruby
|
190
|
-
class UsersController < ApplicationController
|
191
|
-
include Warped::Controllers::Searchable
|
192
|
-
|
193
|
-
def index
|
194
|
-
# This will use the query parameter `term` instead of `q`
|
195
|
-
users = search(User.all, search_term: params[:term])
|
196
|
-
render json: users
|
197
|
-
end
|
198
|
-
end
|
199
|
-
```
|
200
|
-
|
201
|
-
2. Overriding the `search_param` method in the controller
|
202
|
-
|
203
|
-
```ruby
|
204
|
-
class UsersController < ApplicationController
|
205
|
-
include Warped::Controllers::Searchable
|
206
|
-
|
207
|
-
def index
|
208
|
-
# This will use the query parameter `term` instead of `q`
|
209
|
-
users = search(User.all)
|
210
|
-
render json: users
|
211
|
-
end
|
212
|
-
|
213
|
-
private
|
214
|
-
|
215
|
-
def search_param
|
216
|
-
:term
|
217
|
-
end
|
218
|
-
end
|
219
|
-
```
|
220
|
-
|
221
|
-
3. Calling #searchable_by in the controller and overriding the default query parameter
|
222
|
-
|
223
|
-
```ruby
|
224
|
-
# app/models/user.rb
|
225
|
-
class User < ApplicationRecord
|
226
|
-
include PgSearch::Model
|
227
|
-
pg_search_scope :search_by_word, against: :name, using: { tsearch: { any_word: true } }
|
228
|
-
end
|
229
|
-
|
230
|
-
|
231
|
-
# app/controllers/users_controller.rb
|
232
|
-
class UsersController < ApplicationController
|
233
|
-
include Warped::Controllers::Searchable
|
234
|
-
|
235
|
-
# This will use the query parameter `term` instead of `q`
|
236
|
-
# and the search scope `search_by_word` instead of the default
|
237
|
-
searchable_by :search_by_word, param: :term
|
238
|
-
|
239
|
-
def index
|
240
|
-
users = search(User.all)
|
241
|
-
render json: users
|
242
|
-
end
|
243
|
-
end
|
244
|
-
```
|
96
|
+
[Complete documentation for Warped::Controllers::Searchable](docs/controllers/SEARCHABLE.md).
|
245
97
|
|
246
98
|
#### Warped::Controllers::Sortable
|
247
99
|
|
@@ -291,52 +143,8 @@ Request examples:
|
|
291
143
|
```
|
292
144
|
GET /users # sort by id in descending order
|
293
145
|
```
|
294
|
-
##### Referencing tables in the sortable fields
|
295
146
|
|
296
|
-
|
297
|
-
|
298
|
-
```ruby
|
299
|
-
class UsersController < ApplicationController
|
300
|
-
include Warped::Controllers::Sortable
|
301
|
-
|
302
|
-
sortable_by :name, 'companies.name'
|
303
|
-
|
304
|
-
def index
|
305
|
-
users = sort(User.joins(:company))
|
306
|
-
render json: users
|
307
|
-
end
|
308
|
-
end
|
309
|
-
```
|
310
|
-
|
311
|
-
Request examples:
|
312
|
-
```
|
313
|
-
GET /users?sort_key=name # sort by name in descending order
|
314
|
-
GET /users?sort_key=companies.name&sort_direction=asc # sort by company name in ascending order
|
315
|
-
```
|
316
|
-
|
317
|
-
##### Renaming the sort query parameters
|
318
|
-
|
319
|
-
If you don't want to use the field name as the query parameter (as to not expose the database schema, or when joining the same table multiple times),
|
320
|
-
you can specify the query parameter to use for each field:
|
321
|
-
|
322
|
-
```ruby
|
323
|
-
class UsersController < ApplicationController
|
324
|
-
include Warped::Controllers::Sortable
|
325
|
-
|
326
|
-
sortable_by 'companies.name' => :company_name, 'users.name' => :user_name
|
327
|
-
|
328
|
-
def index
|
329
|
-
users = sort(User.join(:company))
|
330
|
-
render json: users
|
331
|
-
end
|
332
|
-
end
|
333
|
-
```
|
334
|
-
|
335
|
-
Request examples:
|
336
|
-
```
|
337
|
-
GET /users?sort_key=user_name # sort by name in descending order
|
338
|
-
GET /users?sort_key=company_name&sort_direction=asc # sort by company name in ascending order
|
339
|
-
```
|
147
|
+
[Complete documentation for Warped::Controllers::Sortable](docs/controllers/SORTABLE.md).
|
340
148
|
|
341
149
|
#### Warped::Controllers::Pageable
|
342
150
|
|
@@ -351,7 +159,7 @@ class UsersController < ApplicationController
|
|
351
159
|
|
352
160
|
def index
|
353
161
|
users = paginate(User.all)
|
354
|
-
render json: users, meta:
|
162
|
+
render json: users, meta: pagination
|
355
163
|
end
|
356
164
|
end
|
357
165
|
```
|
@@ -363,51 +171,7 @@ GET /users?per_page=25 # returns the first page of users with 25 records per pag
|
|
363
171
|
GET /users?page=2&per_page=25 # returns the second page of users with 25 records per page
|
364
172
|
```
|
365
173
|
|
366
|
-
|
367
|
-
|
368
|
-
The `page_info` method can be used to access the pagination information.
|
369
|
-
|
370
|
-
```ruby
|
371
|
-
class UsersController < ApplicationController
|
372
|
-
include Warped::Controllers::Pageable
|
373
|
-
|
374
|
-
def index
|
375
|
-
users = paginate(User.all)
|
376
|
-
render json: users, meta: page_info
|
377
|
-
end
|
378
|
-
end
|
379
|
-
```
|
380
|
-
|
381
|
-
`page_info` returns a hash with
|
382
|
-
- `page` - the current page
|
383
|
-
- `per_page` - the number of records per page
|
384
|
-
- `total_pages` - the total number of pages
|
385
|
-
- `total_count` - the number of records in the scope
|
386
|
-
- `next-page` - the next page number
|
387
|
-
- `prev-page` - the previous page number
|
388
|
-
|
389
|
-
|
390
|
-
##### Customizing the pagination behavior
|
391
|
-
|
392
|
-
By default, the `paginate` method will paginate the scope in pages of size 10, and will return the first page if the `page` query parameter is not provided.
|
393
|
-
|
394
|
-
Additionally, there's a limit of `100` records per page. So, if the `per_page` query parameter is greater than `100`, the pagination will use `100` as the page size.
|
395
|
-
|
396
|
-
You can customize the default page size and the default page number by overriding the `default_per_page` value in the controller.
|
397
|
-
|
398
|
-
```ruby
|
399
|
-
class UsersController < ApplicationController
|
400
|
-
include Warped::Controllers::Pageable
|
401
|
-
|
402
|
-
# This will set the default page size to 25 when the `per_page` query parameter is not provided
|
403
|
-
self.default_per_page = 25
|
404
|
-
|
405
|
-
def index
|
406
|
-
users = paginate(User.all)
|
407
|
-
render json: users, meta: page_info
|
408
|
-
end
|
409
|
-
end
|
410
|
-
```
|
174
|
+
[Complete documentation for Warped::Controllers::Pageable](docs/controllers/PAGEABLE.md).
|
411
175
|
|
412
176
|
#### Warped::Controllers::Tabulatable
|
413
177
|
|
@@ -425,7 +189,7 @@ class UsersController < ApplicationController
|
|
425
189
|
|
426
190
|
def index
|
427
191
|
users = tabulate(User.all)
|
428
|
-
render json: users, meta:
|
192
|
+
render json: users, meta: pagination
|
429
193
|
end
|
430
194
|
end
|
431
195
|
```
|
@@ -436,7 +200,9 @@ GET /users?age[]=18&age[]=30&age.rel=between&sort_key=name&sort_direction=asc&q=
|
|
436
200
|
# returns the second page of users with 10 records per page, where the age is between 18 and 30, sorted by name in ascending order, and searched by the term John
|
437
201
|
```
|
438
202
|
|
439
|
-
Just like `paginate`, when calling the `tabulate` method in the controller action, the `
|
203
|
+
Just like `paginate`, when calling the `tabulate` method in the controller action, the `pagination` method can be used to access the pagination information.
|
204
|
+
|
205
|
+
[Complete documentation for Warped::Controllers::Tabulatable](docs/controllers/TABULATABLE.md).
|
440
206
|
|
441
207
|
### Services
|
442
208
|
|
@@ -492,33 +258,7 @@ PrintService.call # Executes new.call, prints "Hello, John!"
|
|
492
258
|
PrintService.call('world') # Executes new('world').call, prints "Hello, world!"
|
493
259
|
```
|
494
260
|
|
495
|
-
|
496
|
-
|
497
|
-
The `Warped::Service::Base` class provides a class method `.enable_job!` that can be used to enable the service to be used as a job class.
|
498
|
-
|
499
|
-
```ruby
|
500
|
-
class PrintService < Warped::Service::Base
|
501
|
-
enable_job!
|
502
|
-
|
503
|
-
def call
|
504
|
-
puts 'Hello, world!'
|
505
|
-
end
|
506
|
-
end
|
507
|
-
```
|
508
|
-
|
509
|
-
The `enable_job!` method will define a `PrintService::Job` class that inherits from `Warped::Jobs::Base` and calls the `call` method on the service instance.
|
510
|
-
|
511
|
-
```ruby
|
512
|
-
PrintService.call_later # Executes PrintService::Job.perform_later
|
513
|
-
PrintService::Job.perform_later # Executes PrintService.new.call in the background
|
514
|
-
```
|
515
|
-
|
516
|
-
call_later and perform_later will pass the arguments to the `initialize` method of the service class, and then call the `call` method on the new instance.
|
517
|
-
|
518
|
-
```ruby
|
519
|
-
PrintService.call_later('world') # Executes PrintService::Job.perform_later('world')
|
520
|
-
PrintService::Job.perform_later('world') # Executes PrintService.new('world').call in the background
|
521
|
-
```
|
261
|
+
[Complete documentation for Warped::Services](docs/services/README.md).
|
522
262
|
|
523
263
|
### Jobs
|
524
264
|
|
@@ -543,6 +283,8 @@ Warped.configure do |config|
|
|
543
283
|
end
|
544
284
|
```
|
545
285
|
|
286
|
+
[Complete documentation for Warped::Jobs](docs/jobs/README.md).
|
287
|
+
|
546
288
|
|
547
289
|
## Development
|
548
290
|
|
@@ -0,0 +1,114 @@
|
|
1
|
+
# Warped::Controllers::Filterable
|
2
|
+
|
3
|
+
The `Filterable` concern provides a method to filter the records in a controller's action.
|
4
|
+
The method `filterable_by` is used to define the filterable fields and the filter method to use.
|
5
|
+
|
6
|
+
```ruby
|
7
|
+
class UsersController < ApplicationController
|
8
|
+
include Warped::Controllers::Filterable
|
9
|
+
|
10
|
+
filterable_by :name, :email, :created_at
|
11
|
+
|
12
|
+
def index
|
13
|
+
users = filter(User.all)
|
14
|
+
render json: users
|
15
|
+
end
|
16
|
+
end
|
17
|
+
```
|
18
|
+
The `filter` method will use the query parameters to filter the records. For example, to filter the users by name, email, and created_at, the following query parameters can be used:
|
19
|
+
|
20
|
+
```
|
21
|
+
GET /users?name=John
|
22
|
+
GET /users?email=john@example.com
|
23
|
+
GET /users?created_at=2021-01-01
|
24
|
+
```
|
25
|
+
|
26
|
+
## Referencing tables in the filterable fields
|
27
|
+
|
28
|
+
The `filterable_by` method can also be used to reference fields in associated tables. For example, to filter the users by the name of the company they work for, the following can be done:
|
29
|
+
|
30
|
+
```ruby
|
31
|
+
class UsersController < ApplicationController
|
32
|
+
include Warped::Controllers::Filterable
|
33
|
+
|
34
|
+
filterable_by :name, :email, :created_at, 'companies.name'
|
35
|
+
|
36
|
+
def index
|
37
|
+
users = filter(User.joins(:company))
|
38
|
+
render json: users
|
39
|
+
end
|
40
|
+
end
|
41
|
+
```
|
42
|
+
|
43
|
+
Request examples:
|
44
|
+
```
|
45
|
+
GET /users?name=John
|
46
|
+
GET /users?companies.name=Acme
|
47
|
+
```
|
48
|
+
|
49
|
+
## Renaming the filter query parameters
|
50
|
+
|
51
|
+
If you don't want to use the field name as the query parameter (as to not expose the database schema, or when joining the same table multiple times),
|
52
|
+
you can specify the query parameter to use for each field:
|
53
|
+
|
54
|
+
```ruby
|
55
|
+
class UsersController < ApplicationController
|
56
|
+
include Warped::Controllers::Filterable
|
57
|
+
|
58
|
+
filterable_by 'companies.name' => :company_name, 'users.name' => :user_name
|
59
|
+
|
60
|
+
def index
|
61
|
+
users = filter(User.join(:company))
|
62
|
+
render json: users
|
63
|
+
end
|
64
|
+
end
|
65
|
+
```
|
66
|
+
|
67
|
+
Request examples:
|
68
|
+
```
|
69
|
+
GET /users?user_name=John
|
70
|
+
GET /users?company_name=Acme
|
71
|
+
```
|
72
|
+
|
73
|
+
## Using filters other than `eq`
|
74
|
+
|
75
|
+
By default, the `filter` method will use the `eq` filter method to filter the records. If you want to use a different filter method, you can specify the filter "relation" in the query parameter:
|
76
|
+
|
77
|
+
```ruby
|
78
|
+
class UsersController < ApplicationController
|
79
|
+
include Warped::Controllers::Filterable
|
80
|
+
|
81
|
+
filterable_by :name, :age
|
82
|
+
|
83
|
+
def index
|
84
|
+
users = filter(User.all)
|
85
|
+
render json: users
|
86
|
+
end
|
87
|
+
end
|
88
|
+
```
|
89
|
+
|
90
|
+
Request examples:
|
91
|
+
```
|
92
|
+
GET /users?name=John # returns users with name John
|
93
|
+
GET /users?name[]=John&name[]=Jane # returns users where the name is in ('John', 'Jane')
|
94
|
+
GET /users?age.rel=is_null # returns users where the age is null
|
95
|
+
GET /users?age.rel=is_not_null # returns users where the age is not null
|
96
|
+
GET /users?age.rel=between&age[]=18&age[]=30 # returns users with age between 18 and 30
|
97
|
+
GET /users?age.rel=gt&age=18 # returns users with age greater than 18
|
98
|
+
```
|
99
|
+
|
100
|
+
The full list of filter relations is:
|
101
|
+
- `eq` (default) - equals
|
102
|
+
- `neq` - not equals
|
103
|
+
- `gt` - greater than
|
104
|
+
- `gte` - greater than or equals
|
105
|
+
- `lt` - less than
|
106
|
+
- `lte` - less than or equals
|
107
|
+
- `between` - between (requires two values)
|
108
|
+
- `in` - in (default when multiple values are provided)
|
109
|
+
- `not_in` - not in (requires multiple values)
|
110
|
+
- `starts_with` - starts with
|
111
|
+
- `ends_with` - ends with
|
112
|
+
- `contains` - contains
|
113
|
+
- `is_null` - is null (does not require a value)
|
114
|
+
- `is_not_null` - is not null (does not require a value)
|
@@ -0,0 +1,70 @@
|
|
1
|
+
# Warped::Controllers::Pageable
|
2
|
+
|
3
|
+
The `Pageable` concern provides a method to paginate the records in a controller's action.
|
4
|
+
|
5
|
+
The method `paginate` is used to paginate the records.
|
6
|
+
It will use the query parameters `page` and `per_page` to paginate the records.
|
7
|
+
|
8
|
+
```ruby
|
9
|
+
class UsersController < ApplicationController
|
10
|
+
include Warped::Controllers::Pageable
|
11
|
+
|
12
|
+
def index
|
13
|
+
users = paginate(User.all)
|
14
|
+
render json: users, meta: pagination
|
15
|
+
end
|
16
|
+
end
|
17
|
+
```
|
18
|
+
|
19
|
+
Request examples:
|
20
|
+
```
|
21
|
+
GET /users?page=1&per_page=10 # returns the first page of users with 10 records per page
|
22
|
+
GET /users?per_page=25 # returns the first page of users with 25 records per page
|
23
|
+
GET /users?page=2&per_page=25 # returns the second page of users with 25 records per page
|
24
|
+
```
|
25
|
+
|
26
|
+
## Accessing the pagination information
|
27
|
+
|
28
|
+
The `pagination` method can be used to access the pagination information.
|
29
|
+
|
30
|
+
```ruby
|
31
|
+
class UsersController < ApplicationController
|
32
|
+
include Warped::Controllers::Pageable
|
33
|
+
|
34
|
+
def index
|
35
|
+
users = paginate(User.all)
|
36
|
+
render json: users, meta: pagination
|
37
|
+
end
|
38
|
+
end
|
39
|
+
```
|
40
|
+
|
41
|
+
`pagination` returns a hash with
|
42
|
+
- `page` - the current page
|
43
|
+
- `per_page` - the number of records per page
|
44
|
+
- `total_pages` - the total number of pages
|
45
|
+
- `total_count` - the number of records in the scope
|
46
|
+
- `next-page` - the next page number
|
47
|
+
- `prev-page` - the previous page number
|
48
|
+
|
49
|
+
|
50
|
+
## Customizing the pagination behavior
|
51
|
+
|
52
|
+
By default, the `paginate` method will paginate the scope in pages of size 10, and will return the first page if the `page` query parameter is not provided.
|
53
|
+
|
54
|
+
Additionally, there's a limit of `100` records per page. So, if the `per_page` query parameter is greater than `100`, the pagination will use `100` as the page size.
|
55
|
+
|
56
|
+
You can customize the default page size and the default page number by overriding the `default_per_page` value in the controller.
|
57
|
+
|
58
|
+
```ruby
|
59
|
+
class UsersController < ApplicationController
|
60
|
+
include Warped::Controllers::Pageable
|
61
|
+
|
62
|
+
# This will set the default page size to 25 when the `per_page` query parameter is not provided
|
63
|
+
self.default_per_page = 25
|
64
|
+
|
65
|
+
def index
|
66
|
+
users = paginate(User.all)
|
67
|
+
render json: users, meta: pagination
|
68
|
+
end
|
69
|
+
end
|
70
|
+
```
|
@@ -0,0 +1,8 @@
|
|
1
|
+
# Warped::Controllers
|
2
|
+
|
3
|
+
The `Warped::Controllers` module defines five concerns that can be included in a controller to provide additional functionality:
|
4
|
+
- [Warped::Controllers::Filterable](FILTERABLE.md)
|
5
|
+
- [Warped::Controllers::Searchable](SEARCHABLE.md)
|
6
|
+
- [Warped::Controllers::Sortable](SORTABLE.md)
|
7
|
+
- [Warped::Controllers::Pageable](PAGEABLE.md)
|
8
|
+
- [Warped::Controllers::Tabulatable](TABULATABLE.md)
|