Instance variables vs methods. When to use each?

[pinzonjulian]

I've been using ViewComponent for a while now and just now I realized I can define instance methods that are available to my view just like instance variables. I'm confused because I don't know wether I should always use one or the other or even a mix of both.

As an example I have an OnboardingChecklistComponent which shows a ChecklistItemComponent, per item.

class OnboardingChecklistComponent < ViewComponent::Base

  def initialize(user:)
    @user = user
    @work_preference = user.work_preference
  end

  def work_preference_state
    state_for(work_preference) # lets assume state can be :empty, :incomplete, :complete
  end

I then call in onboarding_checklist_component.html.erb the reference to another component with some of the "calculations" I performed here.

render Seeker::ChecklistItemComponent.new(state: work_preference_state, label: 'Your working preferences', path: edit_work_preference_path)

In this example, I definitely won't be using @work_preference in my view but I need it to calculate the state of the work preference progress. In my view I do need the state.

My concrete questions with this example (which in real life is far more complex) are:

1. Should @work_preference, which is not used in the view, be set as an instance variable or as an instance method?
2. Should work_preference_state, which IS used in the view, be set as an instance variable or a an instance method?

My take on this:

It's a bit confusing that we can do both. In typical rails fashion, the only things available to the view are instance variables set on the controller.
There are pros and cons though.

PROs:
I see great value in being able to declare methods of my component instance and use it in my instance's view. Specially for boolean methods that allow me to use question marks at the end (something I can't do with instance variables).

CONs:
This can lead to the view performing logic which should have been declared in the ruby file.

My guess is there should be a convention around this or probably even a top level decision to not allow instance methods to be used in views.

What do you think?

[joelhawksley]

@pinzonjulian generally, I think both are fine!

For simply making a value passed into the component initializer available in the template, instance variables are simple and lightweight.

But it's often nice to write instance methods on component classes to express a certain behavior, such as changing the text of a label, in a Ruby method.

We use both in our components at GitHub, generally in this fashion.

[pinzonjulian]

(Sorry for the long response but I'd like to make a point through example. Buckle up 😂🛫)

I see great value in having both but I think it's a bit confusing. For me it's hard to tell where the line is drawn between the two.

Seeing components as ruby objects, I would expect to define my component's attributes with attr_reader to be able to read their properties with reader methods. Making the decision to call them "attributes" instantly gives me peace of mind 🧘🏽‍♂️🙂.

Sadly for my inner yogi, in the docs there's only one reference to that in the sidecar assets section. I know reader methods are just methods that call the instance variable set (usually) on the initializer but it feels much more idiomatic to define an attr_reader than defining an arbitrary method.

class JobComponent
  attr_reader :job, :title, :distance_from_office

  def initialize(job: )
    @job = job
    @title = @job.title || 'Standard Job' # simple initialization
    @distance_from_office = calculate_distance_from_office # complex initialization
  end

  private

  def calculate_distance_from_office
    # Some complex logic using something like  @job.latitude @job.longitude for example
  end
end

With this syntax I find it much more explicit that in my template I'm calling an attribute of an instance of my JobComponent.

<div class"job">
  <div class"job__title"><%= title %></div>
  <div class"job__label"><%= distance_from_office %></div
</div>

As an example, I'd like to add a class to my job title depending on it's length

Option 1

Declare it as an attribute of the object.

class JobComponent
  attr_reader :job, :title, :distance_from_office, :job_modifier_class

  def initialize(job: )
    @job = job
    # ...
    @job_modifier_class = job_modifier_class
  end

  private

  def job_modifier_class
    @title.length < 50 ? 'job__title--small' : 'job__title-base'
  end
end

<div class"job">
  <div class"job__title <%= job_modifier_class%>"><%= title %></div>
  <div class"job__label"><%= distance_from_office %></div
</div>

Option 2

Declare it as a method of the object.

class JobComponent
  attr_reader :job, :title, :distance_from_office # notice the missing reader here

  def initialize(job: )
    @job = job
    # ... notice it's not initialized as an attribute for the object
  end

  def job_modifier_class
    title.length < 50 ? 'job__title--small' : 'job__title-base'
  end
end

<div class"job">
  <div class"job__title <%= job_modifier_class%>"><%= title %></div>
  <div class"job__label"><%= distance_from_office %></div
</div>

It's not bad, however I miss the concept of this being a core attribute of my instance. Attributes and the initialize method serve as documentation of the the characteristics that define my object.

Option 3

Declare a sort of "helper" method and call it in the view

class JobComponent
  attr_reader :job, :title, :distance_from_office # notice the missing reader here

  def initialize(job: )
    @job = job
    # ... notice it's not initialized as an attribute for the object
  end

  def job_modifier_class(string)
    string.length < 50 ? 'job__title--small' : 'job__title-base'
  end
end

<div class"job">
  <div class"job__title <%= job_modifier_class(title)%>"><%= title %></div>
  <div class"job__label"><%= distance_from_office %></div
</div>

I feel this third option is a bit too much. I don't like going back and forth between the view and the object to understand what's going on.

Final thoughts

I'm still trying to wrap my head around your talk at Railsconf 2020 where you said that templates in rails are just method calls (I really hope I'm getting this right 🙈). In that sense it's natural to have the view access any method of the instance because it is in fact one more method.

However, when thinking about components I think of the template and the ruby file as 2 separate entities where the ruby file provides a well defined set of things to the view (the attr_reader in opiton 1).

My preference

I like option 1 as I feel it's the most explicit of all. I'd stay away from 3 because why go back and forth between view and object? 2 is ok but it's a bit less organised than 1 in my opinion.

In the end, it might be a style thing and teams might have different preferences. However I'd love for the gem to provide a best practice in this regard, or at least a menu of options for people to understand how to tackle this.

[joelhawksley]

@pinzonjulian thank you for providing the detailed examples here. Some thoughts:

ViewComponent templates are compiled into instance methods on the component Ruby file. In that regard, the component and the template are the same entity. I have it on my to-do list to write up an explanation of this concept as part of the README, but here's an example:

class JobComponent
  attr_reader :job, :title, :distance_from_office

  def initialize(job: )
    @job = job
    @title = @job.title || 'Standard Job' # simple initialization
    @distance_from_office = calculate_distance_from_office # complex initialization
  end

  def calculate_distance_from_office
    # Some complex logic using something like  @job.latitude @job.longitude for example
  end
end

and

<div class"job">
  <div class"job__title"><%= title %></div>
  <div class"job__label"><%= distance_from_office %></div
</div>

Are compiled (on every page load in development, or at boot time in test/production) into:

class JobComponent
  attr_reader :job, :title, :distance_from_office

  def initialize(job: )
    @job = job
    @title = @job.title || 'Standard Job' # simple initialization
    @distance_from_office = calculate_distance_from_office # complex initialization
  end

  def calculate_distance_from_office
    # Some complex logic using something like  @job.latitude @job.longitude for example
  end

  def call
    @output_buffer.safe_append "<div class"job__title">"
    @output_buffer.safe_append title 
    @output_buffer.safe_append "</div>"
    ...
  end
end

When the component is rendered by Rails, it is initialized and then call is called.

This is an oversimplification of the ViewComponent lifecycle, but I hope this explanation is helpful. You're right to express concern that the abstraction is difficult to reason about, especially in its current form. I'd love to hear other people's thoughts on how we can make ViewComponent easier to understand ❤️