Class: ViewComponent::Base
- Inherits:
-
ActionView::Base
- Object
- ActionView::Base
- ViewComponent::Base
- Includes:
- ActiveSupport::Configurable, ContentAreas, Previewable, SlotableV2, WithContentHelper
- Defined in:
- lib/view_component/base.rb
Direct Known Subclasses
Constant Summary collapse
- ViewContextCalledBeforeRenderError =
Class.new(StandardError)
- RESERVED_PARAMETER =
:content
Constants included from SlotableV2
Class Attribute Summary collapse
Instance Attribute Summary collapse
-
#__vc_original_view_context ⇒ Object
Returns the value of attribute __vc_original_view_context.
Class Method Summary collapse
-
._after_compile ⇒ Object
EXPERIMENTAL: This API is experimental and may be removed at any time.
- ._deprecated_generate_mattr_accessor(name) ⇒ Object
-
._sidecar_files(extensions) ⇒ Object
EXPERIMENTAL: This API is experimental and may be removed at any time.
- .collection_counter_parameter ⇒ Object
- .collection_iteration_parameter ⇒ Object
- .collection_parameter ⇒ Object
-
.compile(raise_errors: false, force: false) ⇒ Object
Compile templates to instance methods, assuming they haven’t been compiled already.
- .compiled? ⇒ Boolean
- .compiler ⇒ Object
- .counter_argument_present? ⇒ Boolean
- .format ⇒ Object
- .identifier ⇒ Object
- .inherited(child) ⇒ Object
- .iteration_argument_present? ⇒ Boolean
-
.short_identifier ⇒ Object
Provide identifier for ActionView template annotations.
-
.type ⇒ Object
we’ll eventually want to update this to support other types.
-
.validate_collection_parameter!(validate_default: false) ⇒ Object
Ensure the component initializer accepts the collection parameter.
-
.validate_initialization_parameters! ⇒ Object
Ensure the component initializer doesn’t define invalid parameters that could override the framework’s methods.
-
.with_collection(collection, **args) ⇒ Object
Render a component for each element in a collection ([documentation](/guide/collections)):.
-
.with_collection_parameter(parameter) ⇒ Object
Set the parameter name used when rendering elements of a collection ([documentation](/guide/collections)):.
Instance Method Summary collapse
-
#_output_postamble ⇒ String
EXPERIMENTAL: Optional content to be returned after the rendered template.
-
#before_render ⇒ void
Called before rendering the component.
-
#before_render_check ⇒ void
deprecated
Deprecated.
Use ‘#before_render` instead. Will be removed in v3.0.0.
-
#controller ⇒ ActionController::Base
The current controller.
-
#format ⇒ Object
For caching, such as #cache_if.
-
#generate_distinct_locale_files ⇒ Object
deprecated
Deprecated.
Use ‘#generate.distinct_locale_files` instead. Will be removed in v3.0.0.
-
#generate_locale ⇒ Object
deprecated
Deprecated.
Use ‘#generate.locale` instead. Will be removed in v3.0.0.
-
#generate_sidecar ⇒ Object
deprecated
Deprecated.
Use ‘#generate.sidecar` instead. Will be removed in v3.0.0.
-
#generate_stimulus_controller ⇒ Object
deprecated
Deprecated.
Use ‘#generate.stimulus_controller` instead. Will be removed in v3.0.0.
-
#helpers ⇒ ActionView::Base
A proxy through which to access helpers.
-
#initialize ⇒ Base
constructor
A new instance of Base.
- #perform_render ⇒ Object
-
#render(options = {}, args = {}, &block) ⇒ Object
Re-use original view_context if we’re not rendering a component.
-
#render? ⇒ Boolean
Override to determine whether the ViewComponent should render.
-
#render_in(view_context, &block) ⇒ String
Entrypoint for rendering components.
-
#render_template_for(variant = nil) ⇒ Object
:nocov:.
-
#request ⇒ ActionDispatch::Request
The current request.
-
#view_cache_dependencies ⇒ Object
For caching, such as #cache_if.
-
#virtual_path ⇒ Object
Exposes .virtual_path as an instance method.
-
#with_variant(variant) ⇒ self
deprecated
Deprecated.
Will be removed in v3.0.0.
Methods included from WithContentHelper
Methods included from SlotableV2
Methods included from ContentAreas
Constructor Details
#initialize ⇒ Base
Returns a new instance of Base.
160 |
# File 'lib/view_component/base.rb', line 160 def initialize(*); end |
Class Attribute Details
.source_location ⇒ Object
362 363 364 |
# File 'lib/view_component/base.rb', line 362 def source_location @source_location end |
.virtual_path ⇒ Object
362 363 364 |
# File 'lib/view_component/base.rb', line 362 def virtual_path @virtual_path end |
Instance Attribute Details
#__vc_original_view_context ⇒ Object
Returns the value of attribute __vc_original_view_context.
32 33 34 |
# File 'lib/view_component/base.rb', line 32 def __vc_original_view_context @__vc_original_view_context end |
Class Method Details
._after_compile ⇒ Object
EXPERIMENTAL: This API is experimental and may be removed at any time. Hook for allowing components to do work as part of the compilation process.
For example, one might compile component-specific assets at this point.
39 40 41 |
# File 'lib/view_component/base.rb', line 39 def self._after_compile # noop end |
._deprecated_generate_mattr_accessor(name) ⇒ Object
46 47 48 49 50 51 52 53 |
# File 'lib/view_component/base.rb', line 46 def self._deprecated_generate_mattr_accessor(name) define_singleton_method("generate_#{name}".to_sym) do generate.public_send(name) end define_singleton_method("generate_#{name}=".to_sym) do |value| generate.public_send("#{name}=".to_sym, value) end end |
._sidecar_files(extensions) ⇒ Object
EXPERIMENTAL: This API is experimental and may be removed at any time. Find sidecar files for the given extensions.
The provided array of extensions is expected to contain strings starting without the “dot”, example: ‘[“erb”, “haml”]`.
For example, one might collect sidecar CSS files that need to be compiled.
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 |
# File 'lib/view_component/base.rb', line 372 def _sidecar_files(extensions) return [] unless source_location extensions = extensions.join(",") # view files in a directory named like the component directory = File.dirname(source_location) filename = File.basename(source_location, ".rb") component_name = name.demodulize.underscore # Add support for nested components defined in the same file. # # for example # # class MyComponent < ViewComponent::Base # class MyOtherComponent < ViewComponent::Base # end # end # # Without this, `MyOtherComponent` will not look for `my_component/my_other_component.html.erb` nested_component_files = if name.include?("::") && component_name != filename Dir["#{directory}/#{filename}/#{component_name}.*{#{extensions}}"] else [] end # view files in the same directory as the component sidecar_files = Dir["#{directory}/#{component_name}.*{#{extensions}}"] sidecar_directory_files = Dir["#{directory}/#{component_name}/#{filename}.*{#{extensions}}"] (sidecar_files - [source_location] + sidecar_directory_files + nested_component_files).uniq end |
.collection_counter_parameter ⇒ Object
567 568 569 |
# File 'lib/view_component/base.rb', line 567 def collection_counter_parameter "#{collection_parameter}_counter".to_sym end |
.collection_iteration_parameter ⇒ Object
577 578 579 |
# File 'lib/view_component/base.rb', line 577 def collection_iteration_parameter "#{collection_parameter}_iteration".to_sym end |
.collection_parameter ⇒ Object
558 559 560 561 562 563 564 |
# File 'lib/view_component/base.rb', line 558 def collection_parameter if provided_collection_parameter provided_collection_parameter else name && name.demodulize.underscore.chomp("_component").to_sym end end |
.compile(raise_errors: false, force: false) ⇒ Object
Compile templates to instance methods, assuming they haven’t been compiled already.
Do as much work as possible in this step, as doing so reduces the amount of work done each time a component is rendered.
478 479 480 |
# File 'lib/view_component/base.rb', line 478 def compile(raise_errors: false, force: false) compiler.compile(raise_errors: raise_errors, force: force) end |
.compiled? ⇒ Boolean
469 470 471 |
# File 'lib/view_component/base.rb', line 469 def compiled? compiler.compiled? end |
.compiler ⇒ Object
483 484 485 |
# File 'lib/view_component/base.rb', line 483 def compiler @__vc_compiler ||= Compiler.new(self) end |
.counter_argument_present? ⇒ Boolean
572 573 574 |
# File 'lib/view_component/base.rb', line 572 def counter_argument_present? initialize_parameter_names.include?(collection_counter_parameter) end |
.format ⇒ Object
494 495 496 |
# File 'lib/view_component/base.rb', line 494 def format :html end |
.identifier ⇒ Object
499 500 501 |
# File 'lib/view_component/base.rb', line 499 def identifier source_location end |
.inherited(child) ⇒ Object
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 |
# File 'lib/view_component/base.rb', line 425 def inherited(child) # Compile so child will inherit compiled `call_*` template methods that # `compile` defines compile # Give the child its own personal #render_template_for to protect against the case when # eager loading is disabled and the parent component is rendered before the child. In # such a scenario, the parent will override ViewComponent::Base#render_template_for, # meaning it will not be called for any children and thus not compile their templates. if !child.instance_methods(false).include?(:render_template_for) && !child.compiled? child.class_eval <<~RUBY, __FILE__, __LINE__ + 1 def render_template_for(variant = nil) # Force compilation here so the compiler always redefines render_template_for. # This is mostly a safeguard to prevent infinite recursion. self.class.compile(raise_errors: true, force: true) # .compile replaces this method; call the new one render_template_for(variant) end RUBY end # If Rails application is loaded, add application url_helpers to the component context # we need to check this to use this gem as a dependency if defined?(Rails) && Rails.application child.include Rails.application.routes.url_helpers unless child < Rails.application.routes.url_helpers end # Derive the source location of the component Ruby file from the call stack. # We need to ignore `inherited` frames here as they indicate that `inherited` # has been re-defined by the consuming application, likely in ApplicationComponent. child.source_location = caller_locations(1, 10).reject { |l| l.label == "inherited" }[0].path # Removes the first part of the path and the extension. child.virtual_path = child.source_location.gsub( %r{(.*#{Regexp.quote(ViewComponent::Base.view_component_path)})|(\.rb)}, "" ) # Set collection parameter to the extended component child.with_collection_parameter provided_collection_parameter super end |
.iteration_argument_present? ⇒ Boolean
582 583 584 |
# File 'lib/view_component/base.rb', line 582 def iteration_argument_present? initialize_parameter_names.include?(collection_iteration_parameter) end |
.short_identifier ⇒ Object
Provide identifier for ActionView template annotations
420 421 422 |
# File 'lib/view_component/base.rb', line 420 def short_identifier @short_identifier ||= defined?(Rails.root) ? source_location.sub("#{Rails.root}/", "") : source_location end |
.type ⇒ Object
we’ll eventually want to update this to support other types
489 490 491 |
# File 'lib/view_component/base.rb', line 489 def type "text/html" end |
.validate_collection_parameter!(validate_default: false) ⇒ Object
Ensure the component initializer accepts the collection parameter. By default, we don’t validate that the default parameter name is accepted, as support for collection rendering is optional.
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 |
# File 'lib/view_component/base.rb', line 518 def validate_collection_parameter!(validate_default: false) parameter = validate_default ? collection_parameter : provided_collection_parameter return unless parameter return if initialize_parameter_names.include?(parameter) # If Ruby can't parse the component class, then the initalize # parameters will be empty and ViewComponent will not be able to render # the component. if initialize_parameters.empty? raise ArgumentError.new( "The #{self} initializer is empty or invalid." \ "It must accept the parameter `#{parameter}` to render it as a collection.\n\n" \ "To fix this issue, update the initializer to accept `#{parameter}`.\n\n" \ "See https://viewcomponent.org/guide/collections.html for more information on rendering collections." ) end raise ArgumentError.new( "The initializer for #{self} doesn't accept the parameter `#{parameter}`, " \ "which is required in order to render it as a collection.\n\n" \ "To fix this issue, update the initializer to accept `#{parameter}`.\n\n" \ "See https://viewcomponent.org/guide/collections.html for more information on rendering collections." ) end |
.validate_initialization_parameters! ⇒ Object
Ensure the component initializer doesn’t define invalid parameters that could override the framework’s methods.
548 549 550 551 552 553 554 555 |
# File 'lib/view_component/base.rb', line 548 def validate_initialization_parameters! return unless initialize_parameter_names.include?(RESERVED_PARAMETER) raise ViewComponent::ComponentError.new( "#{self} initializer can't accept the parameter `#{RESERVED_PARAMETER}`, as it will override a " \ "public ViewComponent method. To fix this issue, rename the parameter." ) end |
.with_collection(collection, **args) ⇒ Object
Render a component for each element in a collection ([documentation](/guide/collections)):
render(ProductsComponent.with_collection(@products, foo: :bar))
413 414 415 |
# File 'lib/view_component/base.rb', line 413 def with_collection(collection, **args) Collection.new(self, collection, **args) end |
.with_collection_parameter(parameter) ⇒ Object
Set the parameter name used when rendering elements of a collection ([documentation](/guide/collections)):
with_collection_parameter :item
508 509 510 |
# File 'lib/view_component/base.rb', line 508 def with_collection_parameter(parameter) @provided_collection_parameter = parameter end |
Instance Method Details
#_output_postamble ⇒ String
EXPERIMENTAL: Optional content to be returned after the rendered template.
132 133 134 |
# File 'lib/view_component/base.rb', line 132 def _output_postamble "" end |
#before_render ⇒ void
This method returns an undefined value.
Called before rendering the component. Override to perform operations that depend on having access to the view context, such as helpers.
140 141 142 |
# File 'lib/view_component/base.rb', line 140 def before_render before_render_check end |
#before_render_check ⇒ void
Use ‘#before_render` instead. Will be removed in v3.0.0.
This method returns an undefined value.
Called after rendering the component.
148 149 150 |
# File 'lib/view_component/base.rb', line 148 def before_render_check # noop end |
#controller ⇒ ActionController::Base
The current controller. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
182 183 184 185 186 187 188 189 190 191 192 193 194 195 |
# File 'lib/view_component/base.rb', line 182 def controller if view_context.nil? raise( ViewContextCalledBeforeRenderError, "`#controller` can't be used during initialization, as it depends " \ "on the view context that only exists once a ViewComponent is passed to " \ "the Rails render pipeline.\n\n" \ "It's sometimes possible to fix this issue by moving code dependent on " \ "`#controller` to a `#before_render` method: https://viewcomponent.org/api.html#before_render--void." ) end @__vc_controller ||= view_context.controller end |
#format ⇒ Object
For caching, such as #cache_if
239 240 241 242 243 244 |
# File 'lib/view_component/base.rb', line 239 def format # Ruby 2.6 throws a warning without checking `defined?`, 2.7 doesn't if defined?(@__vc_variant) @__vc_variant end end |
#generate_distinct_locale_files ⇒ Object
Use ‘#generate.distinct_locale_files` instead. Will be removed in v3.0.0.
55 |
# File 'lib/view_component/base.rb', line 55 _deprecated_generate_mattr_accessor :distinct_locale_files |
#generate_locale ⇒ Object
Use ‘#generate.locale` instead. Will be removed in v3.0.0.
56 |
# File 'lib/view_component/base.rb', line 56 _deprecated_generate_mattr_accessor :locale |
#generate_sidecar ⇒ Object
Use ‘#generate.sidecar` instead. Will be removed in v3.0.0.
57 |
# File 'lib/view_component/base.rb', line 57 _deprecated_generate_mattr_accessor :sidecar |
#generate_stimulus_controller ⇒ Object
Use ‘#generate.stimulus_controller` instead. Will be removed in v3.0.0.
58 |
# File 'lib/view_component/base.rb', line 58 _deprecated_generate_mattr_accessor :stimulus_controller |
#helpers ⇒ ActionView::Base
A proxy through which to access helpers. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 |
# File 'lib/view_component/base.rb', line 201 def helpers if view_context.nil? raise( ViewContextCalledBeforeRenderError, "`#helpers` can't be used during initialization, as it depends " \ "on the view context that only exists once a ViewComponent is passed to " \ "the Rails render pipeline.\n\n" \ "It's sometimes possible to fix this issue by moving code dependent on " \ "`#helpers` to a `#before_render` method: https://viewcomponent.org/api.html#before_render--void." ) end # Attempt to re-use the original view_context passed to the first # component rendered in the rendering pipeline. This prevents the # instantiation of a new view_context via `controller.view_context` which # always returns a new instance of the view context class. # # This allows ivars to remain persisted when using the same helper via # `helpers` across multiple components and partials. @__vc_helpers ||= __vc_original_view_context || controller.view_context end |
#perform_render ⇒ Object
115 116 117 |
# File 'lib/view_component/base.rb', line 115 def perform_render render_template_for(@__vc_variant).to_s + _output_postamble end |
#render(options = {}, args = {}, &block) ⇒ Object
Re-use original view_context if we’re not rendering a component.
This prevents an exception when rendering a partial inside of a component that has also been rendered outside of the component. This is due to the partials compiled template method existing in the parent ‘view_context`,
and not the component's `view_context`.
169 170 171 172 173 174 175 176 |
# File 'lib/view_component/base.rb', line 169 def render( = {}, args = {}, &block) if .is_a? ViewComponent::Base .__vc_original_view_context = __vc_original_view_context super else __vc_original_view_context.render(, args, &block) end end |
#render? ⇒ Boolean
Override to determine whether the ViewComponent should render.
155 156 157 |
# File 'lib/view_component/base.rb', line 155 def render? true end |
#render_in(view_context, &block) ⇒ String
Entrypoint for rendering components.
-
‘view_context`: ActionView context from calling view
-
‘block`: optional block to be captured within the view context
Returns HTML that has been escaped by the respective template handler.
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
# File 'lib/view_component/base.rb', line 68 def render_in(view_context, &block) @view_context = view_context self.__vc_original_view_context ||= view_context @output_buffer = ActionView::OutputBuffer.new unless @global_buffer_in_use @lookup_context ||= view_context.lookup_context # required for path helpers in older Rails versions @view_renderer ||= view_context.view_renderer # For content_for @view_flow ||= view_context.view_flow # For i18n @virtual_path ||= virtual_path # For template variants (+phone, +desktop, etc.) @__vc_variant ||= @lookup_context.variants.first # For caching, such as #cache_if @current_template = nil unless defined?(@current_template) old_current_template = @current_template @current_template = self if block && defined?(@__vc_content_set_by_with_content) raise ArgumentError.new( "It looks like a block was provided after calling `with_content` on #{self.class.name}, " \ "which means that ViewComponent doesn't know which content to use.\n\n" \ "To fix this issue, use either `with_content` or a block." ) end @__vc_content_evaluated = false @__vc_render_in_block = block before_render if render? perform_render else "" end ensure @current_template = old_current_template end |
#render_template_for(variant = nil) ⇒ Object
:nocov:
120 121 122 123 124 125 126 |
# File 'lib/view_component/base.rb', line 120 def render_template_for(variant = nil) # Force compilation here so the compiler always redefines render_template_for. # This is mostly a safeguard to prevent infinite recursion. self.class.compile(raise_errors: true, force: true) # .compile replaces this method; call the new one render_template_for(variant) end |
#request ⇒ ActionDispatch::Request
The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
262 263 264 |
# File 'lib/view_component/base.rb', line 262 def request @request ||= controller.request if controller.respond_to?(:request) end |
#view_cache_dependencies ⇒ Object
For caching, such as #cache_if
232 233 234 |
# File 'lib/view_component/base.rb', line 232 def view_cache_dependencies [] end |
#virtual_path ⇒ Object
Exposes .virtual_path as an instance method
226 227 228 |
# File 'lib/view_component/base.rb', line 226 def virtual_path self.class.virtual_path end |
#with_variant(variant) ⇒ self
Will be removed in v3.0.0.
Use the provided variant instead of the one determined by the current request.
251 252 253 254 255 |
# File 'lib/view_component/base.rb', line 251 def with_variant(variant) @__vc_variant = variant self end |