Class: ViewComponent::Base
- Inherits:
-
ActionView::Base
- Object
- ActionView::Base
- ViewComponent::Base
- Includes:
- ActiveSupport::Configurable, ContentAreas, PolymorphicSlots, Previewable, SlotableV2, Translatable, WithContentHelper
- Defined in:
- lib/view_component/base.rb
Direct Known Subclasses
Constant Summary collapse
- ViewContextCalledBeforeRenderError =
Class.new(StandardError)
- RESERVED_PARAMETER =
:content
Constants included from Translatable
Translatable::HTML_SAFE_TRANSLATION_KEY
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.
-
.strip_trailing_whitespace(value = true) ⇒ Object
Strips trailing whitespace from templates before compiling them.
-
.strip_trailing_whitespace? ⇒ Boolean
Whether trailing whitespace will be stripped before compilation.
-
.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.
-
#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_parent ⇒ Object
Subclass components that call ‘super` inside their template code will cause a double render if they emit the result:.
-
#request ⇒ ActionDispatch::Request
The current request.
-
#set_original_view_context(view_context) ⇒ void
Components render in their own view context.
-
#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 Translatable
#html_safe_translation, #i18n_scope, #translate
Methods included from SlotableV2
Methods included from PolymorphicSlots
Methods included from ContentAreas
Constructor Details
#initialize ⇒ Base
Returns a new instance of Base.
183 184 |
# File 'lib/view_component/base.rb', line 183 def initialize(*) end |
Class Attribute Details
.source_location ⇒ Object
404 405 406 |
# File 'lib/view_component/base.rb', line 404 def source_location @source_location end |
.virtual_path ⇒ Object
404 405 406 |
# File 'lib/view_component/base.rb', line 404 def virtual_path @virtual_path end |
Instance Attribute Details
#__vc_original_view_context ⇒ Object
Returns the value of attribute __vc_original_view_context.
39 40 41 |
# File 'lib/view_component/base.rb', line 39 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.
59 60 61 |
# File 'lib/view_component/base.rb', line 59 def self._after_compile # noop end |
._deprecated_generate_mattr_accessor(name) ⇒ Object
66 67 68 69 70 71 72 73 |
# File 'lib/view_component/base.rb', line 66 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.
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 |
# File 'lib/view_component/base.rb', line 414 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
629 630 631 |
# File 'lib/view_component/base.rb', line 629 def collection_counter_parameter "#{collection_parameter}_counter".to_sym end |
.collection_iteration_parameter ⇒ Object
639 640 641 |
# File 'lib/view_component/base.rb', line 639 def collection_iteration_parameter "#{collection_parameter}_iteration".to_sym end |
.collection_parameter ⇒ Object
624 625 626 |
# File 'lib/view_component/base.rb', line 624 def collection_parameter provided_collection_parameter || name && name.demodulize.underscore.chomp("_component").to_sym 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.
522 523 524 |
# File 'lib/view_component/base.rb', line 522 def compile(raise_errors: false, force: false) compiler.compile(raise_errors: raise_errors, force: force) end |
.compiled? ⇒ Boolean
513 514 515 |
# File 'lib/view_component/base.rb', line 513 def compiled? compiler.compiled? end |
.compiler ⇒ Object
527 528 529 |
# File 'lib/view_component/base.rb', line 527 def compiler @__vc_compiler ||= Compiler.new(self) end |
.counter_argument_present? ⇒ Boolean
634 635 636 |
# File 'lib/view_component/base.rb', line 634 def counter_argument_present? initialize_parameter_names.include?(collection_counter_parameter) end |
.format ⇒ Object
538 539 540 |
# File 'lib/view_component/base.rb', line 538 def format :html end |
.identifier ⇒ Object
543 544 545 |
# File 'lib/view_component/base.rb', line 543 def identifier source_location end |
.inherited(child) ⇒ Object
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 |
# File 'lib/view_component/base.rb', line 469 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
644 645 646 |
# File 'lib/view_component/base.rb', line 644 def iteration_argument_present? initialize_parameter_names.include?(collection_iteration_parameter) end |
.short_identifier ⇒ Object
Provide identifier for ActionView template annotations
464 465 466 |
# File 'lib/view_component/base.rb', line 464 def short_identifier @short_identifier ||= defined?(Rails.root) ? source_location.sub("#{Rails.root}/", "") : source_location end |
.strip_trailing_whitespace(value = true) ⇒ Object
Strips trailing whitespace from templates before compiling them.
“‘ruby class MyComponent < ViewComponent::Base
strip_trailing_whitespace
end “‘
567 568 569 |
# File 'lib/view_component/base.rb', line 567 def strip_trailing_whitespace(value = true) self.__vc_strip_trailing_whitespace = value end |
.strip_trailing_whitespace? ⇒ Boolean
Whether trailing whitespace will be stripped before compilation.
574 575 576 |
# File 'lib/view_component/base.rb', line 574 def strip_trailing_whitespace? __vc_strip_trailing_whitespace end |
.type ⇒ Object
we’ll eventually want to update this to support other types
533 534 535 |
# File 'lib/view_component/base.rb', line 533 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.
584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 |
# File 'lib/view_component/base.rb', line 584 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.
614 615 616 617 618 619 620 621 |
# File 'lib/view_component/base.rb', line 614 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)):
“‘ruby render(ProductsComponent.with_collection(@products, foo: :bar)) “`
457 458 459 |
# File 'lib/view_component/base.rb', line 457 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)):
“‘ruby with_collection_parameter :item “`
554 555 556 |
# File 'lib/view_component/base.rb', line 554 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.
155 156 157 |
# File 'lib/view_component/base.rb', line 155 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.
163 164 165 |
# File 'lib/view_component/base.rb', line 163 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.
171 172 173 |
# File 'lib/view_component/base.rb', line 171 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.
206 207 208 209 210 211 212 213 214 215 216 217 218 219 |
# File 'lib/view_component/base.rb', line 206 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
263 264 265 266 267 268 |
# File 'lib/view_component/base.rb', line 263 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.
75 |
# File 'lib/view_component/base.rb', line 75 _deprecated_generate_mattr_accessor :distinct_locale_files |
#generate_locale ⇒ Object
Use ‘#generate.locale` instead. Will be removed in v3.0.0.
76 |
# File 'lib/view_component/base.rb', line 76 _deprecated_generate_mattr_accessor :locale |
#generate_sidecar ⇒ Object
Use ‘#generate.sidecar` instead. Will be removed in v3.0.0.
77 |
# File 'lib/view_component/base.rb', line 77 _deprecated_generate_mattr_accessor :sidecar |
#generate_stimulus_controller ⇒ Object
Use ‘#generate.stimulus_controller` instead. Will be removed in v3.0.0.
78 |
# File 'lib/view_component/base.rb', line 78 _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.
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 |
# File 'lib/view_component/base.rb', line 225 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 |
#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`.
193 194 195 196 197 198 199 200 |
# File 'lib/view_component/base.rb', line 193 def render( = {}, args = {}, &block) if .respond_to?(:set_original_view_context) .set_original_view_context(self.__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.
178 179 180 |
# File 'lib/view_component/base.rb', line 178 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.
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 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 |
# File 'lib/view_component/base.rb', line 88 def render_in(view_context, &block) self.class.compile(raise_errors: true) @view_context = view_context self.__vc_original_view_context ||= view_context @output_buffer = ActionView::OutputBuffer.new @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? render_template_for(@__vc_variant).to_s + _output_postamble else "" end ensure @current_template = old_current_template end |
#render_parent ⇒ Object
Subclass components that call ‘super` inside their template code will cause a double render if they emit the result:
“‘erb <%= super %> # double-renders <% super %> # does not double-render “`
Calls ‘super`, returning `nil` to avoid rendering the result twice.
146 147 148 149 150 |
# File 'lib/view_component/base.rb', line 146 def render_parent mtd = @__vc_variant ? "call_#{@__vc_variant}" : "call" method(mtd).super_method.call nil end |
#request ⇒ ActionDispatch::Request
The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
286 287 288 |
# File 'lib/view_component/base.rb', line 286 def request @request ||= controller.request if controller.respond_to?(:request) end |
#set_original_view_context(view_context) ⇒ void
This method returns an undefined value.
Components render in their own view context. Helpers and other functionality require a reference to the original Rails view context, an instance of ‘ActionView::Base`. Use this method to set a reference to the original view context. Objects that implement this method will render in the component’s view context, while objects that don’t will render in the original view context so helpers, etc work as expected.
50 51 52 |
# File 'lib/view_component/base.rb', line 50 def set_original_view_context(view_context) self.__vc_original_view_context = view_context end |
#view_cache_dependencies ⇒ Object
For caching, such as #cache_if
256 257 258 |
# File 'lib/view_component/base.rb', line 256 def view_cache_dependencies [] end |
#virtual_path ⇒ Object
Exposes .virtual_path as an instance method
250 251 252 |
# File 'lib/view_component/base.rb', line 250 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.
275 276 277 278 279 |
# File 'lib/view_component/base.rb', line 275 def with_variant(variant) @__vc_variant = variant self end |