Looking up options for Rails helpers
“Rails Magic” is one of the terms I have heard a lot. Rails indeed is a magical framework as it does a lot under the hood. Yet, it can feel “too magical” for a new Rails dev.
Often I looked at a Rails helper and was confused because I didn’t know how to use it, especially when the method signature has (options) as one of the parameters. I know there are options, but what are the options?
Here I summarised three approaches I use now to learn about the optional parameters a Rails helper method accepts. This is one of the many pieces of puzzle in my dev journey that seem obvious once I became aware of them, yet I didn’t know until someone somewhere sheds the light for me.
Learn from examples in the code base I’m working on (#3) and erractically googling were my only approaches at the beginning, these approaches are limited because it was difficult to reverse engineer how the methods work. It was then I discovered #1 and #2 (I learnt from my work mentor and my first #rubyfriend mentor). Somehow when I first started I’d read all the other resources I could found but not the officail Ruby on Rails doc (#1) and the source code (#2). I think it was because I was convinced that “I wouldn’t be able to understand them because they are the official docs and full of advanced level talks”. And that cannot be more untrue! The Rails doc and source code are super reader friendly even for new devs.
1. Read the Doc
The official Ruby on Rails Doc is where I always start with.
Whenever I want to use a method I haven’t fully understood yet, I would first go to the doc and get a basic understanding of the what why how. This overview helps me to sketch a mental model in my mind I can develop upon later when I continue.
Bonus, by reading the official descriptions, I learn the lingo to describe them. And next time when I work on a similar problem, or work with someone else, I know how to describe it.
I sometimes do the same even if I had used the method before, and more often than not, I’d found myself overlooked some nuance and hence always picking up something new by re-reading the doc.
Some methods are explained comprehensively in the doc, while some aren’t. And that’s when the source code comes in handy.
2. Inspect the Method signature in the source code
Read the source code where it is def. Wait what? I can do that?
One of the perks of using an open-source framework is that we can learn what’s happening under the hood by going directly to the source code. Again, this did not cross my mind when I first started.
This is particularly useful for methods used less frequent than something like the form helper. It might be difficult to find examples. I simply cannot find much example or explaination elsewhere, even in the Rails doc!
Rails source code is actually a pleasure to read as the Rails Team are super considerate in leaving examples as comment right on top of the method. What a treasure!
Picking an example from a helper method I had not used before, like ActionView::Helpers::TextHelper#truncate. If I go to the source code on github
I will see that there is a comprehensive list of examples right above the method along with the explaintion.
To illustrate the point, here is an excerpt of the examples comment on top of this specific method signature:
# truncate("Once upon a time in a world far far away")
# # => "Once upon a time in a world..."
#
# truncate("Once upon a time in a world far far away", length: 17)
# # => "Once upon a ti..."
#
# truncate("Once upon a time in a world far far away", length: 17, separator: ' ')
# # => "Once upon a..."
#
# truncate("And they found that many people were sleeping better.", length: 25, omission: '... (continued)')
# # => "And they f... (continued)"
#
# truncate("<p>Once upon a time in a world far far away</p>")
# # => "<p>Once upon a time in a wo..."
#
# truncate("<p>Once upon a time in a world far far away</p>", escape: false)
# # => "<p>Once upon a time in a wo..."
#
# truncate("Once upon a time in a world far far away") { link_to "Continue", "#" }
# # => "Once upon a time in a wo...<a href="#">Continue</a>"
3. Look for examples in the code base
Learn by imitation.
I think one of the biggest perks of working on a Rails application as a dev is that I have a gold treasure at my fingers tips. Reading method application in the same codebase by other dev gives me a good ideas of how it’s commonly applied and some of the varieties. Sometimes it also shines a new light on the method in way I didn’t yet think about. It also shows me nuances related to the specific code base I’m working on I might have missed by only reading the Rails doc or source code. It could be something like how the method is used with another one, how a data object is usually passed as a parameter etc.
When I cannot find example in the Rails application code I work on day-to-day, I find looking at the source code of some open-source Rails app is particularly useful. I like to refer to something I know quite well, like the Odin Project.
tl;dr
As a new Rails dev, there are 3 ways (or more) to leverage the power of Rails helpers.
- Read the official Rails doc
- Read the source code where the method is defined
- Learn by imitating examples
When all resources are exhausted and I have spent more than enough time trying to find answer myself. I’d ask someone for help!
See you next time 👋
Julia