An experiment on finding a way to create a base controller to inherit from when dealing mostly with CRUD operations.
22 |
23 | Have you noticed that if you are working on an app, and need to create an admin interface for it, most of the work to be performed is your typical create, update, destroy and list actions?
24 |
25 | In my “day-to-day work” in Rails-based applications, this is typically the case. I bet the same case presents to you as well, and though I am aware of sound solutions like the ActiveAdmin and RailsAdmin gems, in some edge cases the queries returned by their default implementations always leave something to be desired.
26 |
27 | Now, let’s not confuse this with an attachment to the NIH (Not Invented Here) syndrome, but sometimes, having an in-house and flexible implementation is more than sufficient to achieve “Just the Right FeatureTM”.
28 |
29 | Getting back to day-to-day cases in controllers, specially in a Rails application, you can easily find a pattern:
30 |
31 |
32 | - you need to retrieve a record to display it
33 | - you need to retrieve a record to edit/update it
34 | - you need to delete a record
35 | - you need to create a new record
36 | - you need to list all existing records
37 |
38 |
39 |
40 | Though one of Rails tenets is DRY (Don’t Repeat Yourself), you find yourself adding similar actions across multiple controller files, only changing model and routes specific details.
41 |
42 | Let’s see an example
43 |
44 | Suppose you’re working in a Rails app that deals with a Books and Movies catalog (among other things). You will obviously need an interface to perform CRUD operations on these resources, so you start working your way through the first controller.
45 |
46 | ```ruby
47 |
48 | app/controllers/admin/books_controller.rb
49 |
50 | class Admin::BooksController < ApplicationController
51 | def index
52 |
53 | # code to list all books
54 | # could include logic for ordering, pagination, etc.
55 |
56 |
57 | end
58 |
59 | def show
60 |
61 | # code to retrieve a single book
62 |
63 |
64 | end
65 |
66 | def new
67 |
68 | # code to instantiate a new book
69 |
70 |
71 | end
72 |
73 | def create
74 |
75 | # code to instantiate and persist a new book
76 |
77 |
78 | end
79 |
80 | def edit
81 |
82 | # code to retrieve a single book
83 |
84 |
85 | end
86 |
87 | def update
88 |
89 | # code to retrieve a single book
90 | # and persist updated info
91 |
92 |
93 | end
94 |
95 | def destroy
96 |
97 | # code to delete a single book
98 |
99 |
100 | end
101 |
102 | private
103 |
104 | def books_params
105 |
106 | # rules for accepted params to pass to a book instance
107 |
108 |
109 | end
110 | end
111 | ```
112 |
113 | Then, comes the time to work on the next controller and you come up with this:
114 |
115 | ```ruby
116 |
117 | app/controllers/admin/movies_controller.rb
118 |
119 | class Admin::MoviesController < ApplicationController
120 | def index
121 |
122 | # code to list all movies
123 | # could include logic for ordering, pagination, etc.
124 |
125 |
126 | end
127 |
128 | def show
129 |
130 | # code to retrieve a single movie
131 |
132 |
133 | end
134 |
135 | def new
136 |
137 | # code to instantiate a new movie
138 |
139 |
140 | end
141 |
142 | def create
143 |
144 | # code to instantiate and persist a new movie
145 |
146 |
147 | end
148 |
149 | def edit
150 |
151 | # code to retrieve a single movie
152 |
153 |
154 | end
155 |
156 | def update
157 |
158 | # code to retrieve a single movie
159 | # and persist updated info
160 |
161 |
162 | end
163 |
164 | def destroy
165 |
166 | # code to delete a single movie
167 |
168 |
169 | end
170 |
171 | private
172 |
173 | def movies_params
174 |
175 | # rules for accepted params to pass to a movie instance
176 |
177 |
178 | end
179 | end
180 | ```
181 |
182 | Then comes the time to work on another controller, and another, and another, and yet another controller… and if you pause for a moment and look at the big picture… you basically have only one controller repeated N times your models count.
183 |
184 | How could we refactor these controllers into a flexible base use case?
Well, I recently had some time to read Growing Rails Applications in Practice and pretty much liked the suggestion on the “Beautiful controllers” chapter and decided to take it as a base to build upon… after practicing in an app I was developing at that moment, I came up with:
185 |
186 | A small step in refactoring
187 |
188 | Going back to our example… Let’s declare a base controller and a mixable methods module:
189 |
190 | ```ruby
191 |
192 | app/controllers/admin/crud_methods.rb
193 |
194 | module Admin
195 | module CRUDMethods
196 |
197 | def list_resources
198 | @resources = model.load
199 | end
200 |
201 | def build_resource(attrs = {})
202 | @resource = model.new(attrs)
203 | end
204 |
205 | def load_resource(id)
206 | @resource = model.find(id)
207 | end
208 |
209 | def save_resource
210 | if @resource.save
211 | success_action('Successfully created resource.')
212 | else
213 | error_action(@resource, :new)
214 | end
215 | end
216 |
217 | def update_resource(attrs)
218 | if @resource.update_attributes(attrs)
219 | success_action('Successfully updated resource.')
220 | else
221 | error_action(@resource, :edit)
222 | end
223 | end
224 |
225 | def delete_resource(id)
226 | load_resource(id)
227 | @resource.destroy
228 | destroy_success_action
229 | end
230 |
231 |
232 | end
233 | end
234 |
235 | app/controllers/admin/base.rb
236 |
237 | class Admin::BaseController
238 | include Admin::CRUDMethods
239 |
240 | class NotImplementedError < StandardError; end
241 |
242 | def index
243 |
244 | list_resources
245 |
246 |
247 | end
248 |
249 | def new
250 |
251 | build_resource
252 |
253 |
254 | end
255 |
256 | def create
257 |
258 | build_resource(accepted_params)
259 | save_resource
260 |
261 |
262 | end
263 |
264 | def show
265 |
266 | load_resource(id_key)
267 |
268 |
269 | end
270 |
271 | def edit
272 |
273 | load_resource(id_key)
274 |
275 |
276 | end
277 |
278 | def update
279 |
280 | load_resource(id_key)
281 | update_resource(accepted_params)
282 |
283 |
284 | end
285 |
286 | def destroy
287 |
288 | delete_resource(id_key)
289 |
290 |
291 | end
292 |
293 | private
294 |
295 | def model
296 |
297 | fail(
298 | NotImplementedError,
299 | 'Configure main ActiveRecord class to manage in this controller.'
300 | )
301 |
302 |
303 | end
304 |
305 | def id_key
306 |
307 | fail(
308 | NotImplementedError,
309 | 'Configure params[:key] needed to retrieve a record for this controller.'
310 | )
311 |
312 |
313 | end
314 |
315 | def accepted_params
316 |
317 | fail(
318 | NotImplementedError,
319 | 'Configure the required key and accepted params for a record in this controller'
320 | )
321 |
322 |
323 | end
324 |
325 | def success_action
326 |
327 | fail(
328 | NotImplementedError,
329 | 'Configure what to do when saving/updating a record succeeds.'
330 | )
331 |
332 |
333 | end
334 |
335 | def error_action(resource, view)
336 |
337 | @resource = resource
338 | flash[:error] = 'Something went wrong.'
339 | render view
340 |
341 |
342 | end
343 |
344 | def destroy_success_action
345 |
346 | fail(
347 | NotImplementedError,
348 | 'Configure what to do when deleting a record succeeds.'
349 | )
350 |
351 |
352 | end
353 | end
354 | ```
355 |
356 | I know, I know… this looks like an awful lot of boilerplate… but bear with me for a second while I show you how the Books and Movies controllers will look like now that we have this base class in place.
357 |
358 | ```ruby
359 |
360 | app/controller/admin/books_controller.rb
361 |
362 | class Admin::BooksController < Admin::BaseController
363 | private
364 |
365 | def model
366 |
367 | Book
368 |
369 |
370 | end
371 |
372 | def id_key
373 |
374 | params[:id]
375 |
376 |
377 | end
378 |
379 | def accepted_params
380 |
381 | params.require(:book).permit(
382 | :title, :author, :isbn, :page_count, :price, :category, :etc
383 | )
384 |
385 |
386 | end
387 |
388 | def success_action(message)
389 |
390 | redirect_to admin_book_path(@resource), notice: message
391 |
392 |
393 | end
394 |
395 | def destroy_success_action(message)
396 |
397 | redirect_to admin_books_path, notice: message
398 |
399 |
400 | end
401 | end
402 |
403 | app/controllers/admin/movies_controller.rb
404 |
405 | class Admin::MoviesController < Admin::BaseController
406 | private
407 |
408 | def model
409 |
410 | Movie
411 |
412 |
413 | end
414 |
415 | def id_key
416 |
417 | params[:id]
418 |
419 |
420 | end
421 |
422 | def accepted_params
423 |
424 | params.require(:movie).permit(
425 | :title, :director, :upc_code, :duration, :price, :category, :etc
426 | )
427 |
428 |
429 | end
430 |
431 | def success_action(message)
432 |
433 | redirect_to admin_movie_path(@resource), notice: message
434 |
435 |
436 | end
437 |
438 | def destroy_success_action(message)
439 |
440 | redirect_to admin_movies_path, notice: message
441 |
442 |
443 | end
444 | end
445 | ```
446 | If you take a look at the resulting controllers, you’ll notice we have separated the things that change (params, model, routes, etc. on each derivative controller), from those that don’t (the base CRUD methods). I bet there’s even a pattern name for this ; )
447 |
448 | Now, suppose you need to work on building CRUD actions for a MusicAlbum controller… guess what that would look like? And the next controller you need to implement the same actions all over again?
449 |
450 | Exactly… now that we have ourselves a base platform, we can re-use and override at will; do you need a more complicated logic in any of the actions? do you need to ensure your queries are database optimized when retrieving a collection or a single record and its associations?
Not a problem, simply override the method you need, be it the main CRUD-based action in the controller (index, show, update, etc.), or the abstract methods provided by the base controller or the mixable module (load_resource, update_resource, etc.) and voilá! you can have just the flexibility you need while keeping your eyes in the big picture.
451 |
452 | While this is not a silver bullet design, I pretty much like what it provides so far. Let’s not forget that we don’t need all our controllers to inherit from this base controller; we need to evaluate the corresponding use case, but if CRUD operations is what you need repeated ad-infinitum in a uniform approach, why not take this approach for a spin?
453 |
454 | Do you like what we’ve done here? Do you have a different opinion or approach? I’d love to know your comments on this topic. You can tweet or email me and start a conversation.
455 | ]]>
456 |