Background
GitHub has recently posted an article about view_component:
https://github.blog/2020-12-15-encapsulating-ruby-on-rails-views/
Before it gets too popular I think I should share my experience with cells
So that developers can have another chance to re-think and pick what to use for "encapsulated view components".
Scope of this post
(1) Only "concept cells", not view_component style cells.
The "default"/view_component naming style makes it difficult to just copy & rename a folder to bootstrap a new view component
(2) File Structure, Inputs, Rendering, View Inheritance & Caching
Testing - I am too lazy to do it (rarely beneficial for me)
Layout - Never used it.
File Structure
(Modified from cells old README)
(Remember this is for concept cells)
app
├── concepts
│ ├── copyable_url_box
│ │ ├── cell.rb
│ │ ├── views
│ │ │ ├── show.haml
File content
class CopyableUrlBox::Cell < Cell::Concept
# ..
end
If you want to put these files into a non-default folder like app/resources
You need to update the view_paths
class CopyableUrlBox::Cell < Cell::Concept
self.view_paths = Array("app/resources") + view_paths
# ..
end
Inputs
The official doc suggests using this:
concept("comment/cell", @comment) #=> return a cell
This gives you access to an attribute model (which is @comment) inside the cell object by default
But I prefer passing a hash so I do this:
class ApplicationConceptCell < Cell::Concept
module Cells3HashInputBehaviourReplication
# Since in cells 3.x
# When a hash is passed in
# Everything in hash is injected as ivars
# So we want to replicate the behaviour here
#
# This override works on cells 4.1.5
def initialize(model, options={})
if model.is_a?(::Hash)
model.each_pair do |key, value|
instance_variable_set("@#{key}", value)
end
# To avoid ivar `@model` being set in super with the Hash
# We need to fetch value from hash and put it into `super`
# Even usually it's `nil`
super(model.fetch(:model) { nil }, options)
else
super
end
end
end
prepend Cells3HashInputBehaviourReplication
end
# Remember you have to inherit from the right cell!
class CopyableUrlBox::Cell < ApplicationConceptCell
private
# region Inputs
# Contract Something
# attr_reader :input_name
Contract And[::String, Send[:present?]]
attr_reader :url
# endregion Inputs
end
This gives me access to input values as long as I defined them via attr_reader.
Oh what's the Contract XXX above attr_reader?
They are from contracts.ruby and completely optional and won't be explained in this post.
You can safely ignore those and maybe study that gem later.
I am also using another way to handle inputs which is to put input values into inputs attribute via a value object.
require "contracted_value"
class ApplicationConceptCell2222 < Cell::Concept
module HashInputsAsImmutableInputs
def initialize(model, options={})
if model.is_a?(::Hash)
@inputs = self.class.inputs_class.new(model)
# To avoid ivar `@model` being set in super with the Hash
# We need to fetch value from hash and put it into `super`
# Even usually it's `nil`
super(model.fetch(:model) { nil }, options)
else
super
end
end
private
attr_reader :inputs
end
prepend HashInputsAsImmutableInputs
class_attribute(
:inputs_class,
instance_reader: false,
instance_writer: false,
)
class << self
def define_inputs(&block)
new_inputs_class = Class.new(::ContractedValue::Value)
new_inputs_class.include(::Contracts::Core)
new_inputs_class.include(::Contracts::Builtin)
new_inputs_class.class_eval(&block)
self.inputs_class = new_inputs_class
end
end
end
# Remember you have to inherit from the right cell!
class CopyableUrlBox2222::Cell < ApplicationConceptCell2222
private
# region Inputs
define_inputs do
attribute(
:url,
contract: And[::String, Send[:present?]],
)
end
# endregion Inputs
end
Above implemented via my own gem contracted_value and feel free to swap it with any other value object implementation which can be gems or your own code.
Rendering
To use a cell, by default just invoke #call
And you can do it by:
- Get result string directly
- Create a cell, do something in the middle, get result string later (no need to invoke
#callright after cell creation, and feel free to add new public methods as your own API)
# controller
render(
html: concept("copyable_url_box/cell, url: "...").call
)
Since I use cells-rails, #call returns HTML safe string.
If you don't use cells-rails you might need to do extra work or include extra module to make that happen (check doc yourself).
In cell class, it looks like this:
class CopyableUrlBox::Cell < ApplicationConceptCell
# This is actually optional if you use >= 4.1
# BUT you can make this return something else
def show
render
end
# inputs and other stuff...
end
Why #show? If you read the doc you will know that
concept_cell.call == concept_cell.call(:show)
You are free to use other names but not recommended.
The templates can access anything inside the cell.
Yes this includes
- the inputs (yes even they are private attributes)
- any public/protected/private methods
- Some helper methods are delegated to controller if
cells-railsis used - Extra helper methods from helper modules included into the cell
No more "locals" when rendering. What you see (in cell objects) is what you get (in templates).
Having template file(s) is optional.
Returning a tag directly in #show also works.
class WebsiteLogo::Cell < ApplicationConceptCell
def show
image_tag(
website_logo_image_path,
alt: "Logo",
class: "...",
)
end
private
def website_logo_image_path
case inputs.variant
when :small
"..."
else
"..."
end
end
# inputs and other stuff...
end
View Inheritance
I generally prefer composition over inheritance (using a group of other cells instead a cell) but sometimes being able to use templates from parent cell class is more convenient.
I use it when I have several cells for page content of several page types but the layout is similar (same number of sections but different content).
Just read the view inheritance document yourself.
Caching
Best part comes last.
Caching is easy, cache invalidation is not.
But let's talk about how to enable caching first.
Enabling caching is quite easy according to caching doc:
class CopyableUrlBox::Cell < ApplicationConceptCell
cache :show
end
Yup. The end.
Except when you pass different inputs into it, the cell will give you the same (cached) output. Which is why cache invalidation is the hard part.
First get some basic concept by looking at the caching doc
cache :show, expires_in: 10.minutes
This is just making the cached content expires after some time, nope not what we want.
cache :show { |model, options| "comment/#{model.id}/#{model.updated_at}" }
cache :show, :if => lambda { |*| has_changed? }
cache :show, :tags: lambda { |model, options| "comment-#{model.id}" }
Looks messy? Let me give you my version
cache(
:show,
:cache_key,
expires_in: :cache_valid_time_period_length,
if: :can_be_cached?,
)
def can_be_cached?
# Use following code when child cell(s) is/are used
# [
# child_cell_1,
# ].all?(&:can_be_cached?)
true
end
def cache_valid_time_period_length
# Use following code when child cell(s) is/are used
# [
# child_cell_1,
# ].map(&:cache_valid_time_period_length).min
# Long time
100.years
end
def cache_key
{
current_locale: ::I18n.config.locale,
url: Digest::MD5.hexdigest(url),
}
end
If language changed (::I18n.config.locale) or input value different (url), a different cache key would be used and the render result (cached or not) would be different
But hold on, what if I updated the logic/template and now I want it to return a result rendered with latest logic?
This is what I did:
class ApplicationConceptCell < Cell::Concept
DEFAULT_CLASS_LEVEL_CACHE_KEY = {
# ONLY change this when there are too many cells caching needs updated
# Also only affects cells that has `#cache_key` binding to `super`
# Yes I use cells since 2015
design: :v2015_12_22_1001,
}.freeze
private_constant :DEFAULT_CLASS_LEVEL_CACHE_KEY
def self.cache_key
DEFAULT_CLASS_LEVEL_CACHE_KEY
end
def cache_key
self.class.cache_key
end
end
class CopyableUrlBox::Cell < ApplicationConceptCell
cache(
:show,
:cache_key,
expires_in: :cache_valid_time_period_length,
if: :can_be_cached?,
)
def can_be_cached?
# Use following code when child cell(s) is/are used
# [
# child_cell_1,
# ].all?(&:can_be_cached?)
true
end
def cache_valid_time_period_length
# Use following code when child cell(s) is/are used
# [
# child_cell_1,
# ].map(&:cache_valid_time_period_length).min
# Long time
100.years
end
def self.cache_key
super.merge(
logic: :v2020_12_18_1727,
)
end
def cache_key
super.merge(
current_locale: ::I18n.config.locale,
url: Digest::MD5.hexdigest(url),
)
end
end
Notice that the above code all use cache_key.
But Rails 5.2 introduced cache versioning and we should use that too.
Caching - With Cache Versioning
The following code enable cache versioning
class ApplicationConceptCell < Cell::Concept
DEFAULT_CLASS_LEVEL_CACHE_KEY = {
# Empty
}.freeze
private_constant :DEFAULT_CLASS_LEVEL_CACHE_KEY
DEFAULT_CLASS_LEVEL_CACHE_VERSION = {
# ONLY change this when there are too many cells caching needs updated
# Also only affects cells that has `#cache_key` binding to `super`
# Yes I use cells since 2015
design: :v2015_12_22_1001,
}.freeze
private_constant :DEFAULT_CLASS_LEVEL_CACHE_VERSION
def self.cache_key
DEFAULT_CLASS_LEVEL_CACHE_KEY
end
def cache_key
self.class.cache_key
end
def self.cache_version
DEFAULT_CLASS_LEVEL_CACHE_VERSION
end
def cache_version
self.class.cache_key
end
end
class ProductCardWide::Cell < ApplicationConceptCell
cache(
:show,
:cache_key,
expires_in: :cache_valid_time_period_length,
if: :can_be_cached?,
version: :cache_version,
)
def can_be_cached?
# Use following code when child cell(s) is/are used
# [
# child_cell_1,
# ].all?(&:can_be_cached?)
true
end
def cache_valid_time_period_length
# Use following code when child cell(s) is/are used
# [
# child_cell_1,
# ].map(&:cache_valid_time_period_length).min
# Long time
100.years
end
# def self.cache_key
# super
# end
def cache_key
super.merge(
current_locale: ::I18n.config.locale,
# Assume product is an active record object
product: product.id,
)
end
def self.cache_version
super.merge(
logic: :v2017_12_22_1124,
)
end
def cache_version
super.merge(
# Assume product is an active record object
product: product.updated_at,
)
end
end
Point is when calling .cache in class, add option version.
Logic/Template/Translation/Images updated?
You can of course manually update the class level cache key/version.
But let's see how I make them auto update themselves.
Caching - Class Level Cache Key/Version Auto Update
1. Template Updates
This assumes every template update should cause cache invalidation (so even a refactor would invalidate the cache).
class Some::Cell < ApplicationConceptCell
def self.cache_version
super.merge(
template: TEMPLATE_FILES_CONTENT_CACHE_KEY,
)
end
# This generates the cache key/version from the content of all direct templates for this cell (templates from parent cells or custom paths NOT included)
# Any change (even a refactor) would cause the value to change
TEMPLATE_FILES_CONTENT_CACHE_KEY = begin
view_folder_path = File.expand_path("views", __dir__)
file_paths = Dir.glob(File.join(view_folder_path, "**", "*"))
file_digests = file_paths.map do |file_path|
::Digest::MD5.hexdigest(File.read(file_path))
end
::Digest::MD5.hexdigest(file_digests.join(""))
end
private_constant :TEMPLATE_FILES_CONTENT_CACHE_KEY
end
2. Translation Updates
This requires you to have separate folders of translation files for different components.
class Some::Cell < ApplicationConceptCell
def self.cache_version
super.merge(
translations: TRANSLATION_FILES_CONTENT_CACHE_KEY,
)
end
# This generates the cache key/version from the content of all specified folder's files
# Any change (even a refactor) would cause the value to change
TRANSLATION_FILES_CONTENT_CACHE_KEY = begin
folder_path = ::Rails.root.join(
"config/locales/your/cell/translation/folder/path",
)
file_paths = Dir.glob(File.join(folder_path, "**", "*"))
file_digests = file_paths.map do |file_path|
next nil unless File.file?(file_path)
::Digest::MD5.hexdigest(File.read(file_path))
end
::Digest::MD5.hexdigest(file_digests.join(""))
end
private_constant :TRANSLATION_FILES_CONTENT_CACHE_KEY
end
3. Image Updates
class Some::Cell < ApplicationConceptCell
def self.cache_version
super.merge(
images: IMAGE_FILES_CONTENT_CACHE_KEY,
)
end
# This generates the cache key/version from the content of all specified folder's files
# Any change (even a refactor) would cause the value to change
IMAGE_FILES_CONTENT_CACHE_KEY = begin
folder_paths = [
# "app/assets/images/path/to/images",
]
asset_logical_paths = [
# "app/assets/images/path/to/images.jpg",
].map do |asset_logical_path|
::Rails.root.join(asset_logical_path)
end
file_paths = folder_paths.inject([]) do |paths, folder_path|
paths + ::Dir.glob(::File.join(::Rails.root.join(folder_path), "**", "*"))
end + asset_logical_paths
file_digests = file_paths.map do |file_path|
next nil unless File.file?(file_path)
::Digest::MD5.hexdigest(File.read(file_path))
end
::Digest::MD5.hexdigest(file_digests.join(""))
end
private_constant :ASSET_FILES_CONTENT_CACHE_KEY
end
4. Cell Logic Updates
Nope. You have to update cache key/version manually for this kind of updates.
The End
I still got some more to share about caching but let's save it for another post. (This post is for "beginners")
The code above is extracted from an existing project so let me know if there is any mistake.
Took me almost 3 months to finish this article (o.0)
Top comments (0)