Class: ViewComponent::Base
- Inherits:
-
ActionView::Base
- Object
- ActionView::Base
- ViewComponent::Base
- Includes:
- InlineTemplate, Slotable, Translatable, UseHelpers, WithContentHelper
- Defined in:
- lib/view_component/base.rb
Direct Known Subclasses
DocsBuilderComponent, DocsBuilderComponent::ErrorKlassDoc, DocsBuilderComponent::MethodDoc
Constant Summary collapse
- RESERVED_PARAMETER =
:content
- VC_INTERNAL_DEFAULT_FORMAT =
:html
Constants included from Translatable
Translatable::HTML_SAFE_TRANSLATION_KEY, Translatable::TRANSLATION_EXTENSIONS
Constants included from Slotable
Class Attribute Summary collapse
-
.identifier ⇒ String
The file path of the component Ruby file.
- .virtual_path ⇒ Object
Instance Attribute Summary collapse
-
#__vc_original_view_context ⇒ Object
Returns the value of attribute __vc_original_view_context.
Class Method Summary collapse
- .collection_counter_parameter ⇒ Object
- .collection_iteration_parameter ⇒ Object
- .collection_parameter ⇒ Object
- .compile(raise_errors: false, force: false) ⇒ Object
- .compiled? ⇒ Boolean
- .compiler ⇒ Object
-
.config ⇒ ActiveSupport::OrderedOptions
Returns the current config.
- .counter_argument_present? ⇒ Boolean
- .ensure_compiled ⇒ Object
- .inherited(child) ⇒ Object
- .iteration_argument_present? ⇒ Boolean
-
.sidecar_files(extensions) ⇒ Object
Find sidecar files for the given extensions.
-
.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.
-
.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, spacer_component: nil, **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
-
#__vc_request ⇒ Object
Enables consumers to override request/@request.
-
#before_render ⇒ void
Called before rendering the component.
-
#content ⇒ String
The content passed to the component instance as a block.
-
#content? ⇒ Boolean
Whether ‘content` has been passed to the component.
-
#controller ⇒ ActionController::Base
The current controller.
-
#format ⇒ Object
For caching, such as #cache_if.
-
#helpers ⇒ ActionView::Base
A proxy through which to access helpers.
-
#initialize ⇒ Base
constructor
A new instance of Base.
- #method_missing(method_name, *args) ⇒ Object
-
#output_postamble ⇒ String
Optional content to be returned after the rendered template.
-
#output_preamble ⇒ String
Optional content to be returned before the rendered template.
-
#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.
-
#render_parent_to_string ⇒ Object
Renders the parent component to a string and returns it.
-
#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.
Methods included from WithContentHelper
Methods included from Translatable
Methods included from Slotable
#get_slot, #set_polymorphic_slot, #set_slot
Constructor Details
#initialize ⇒ Base
Returns a new instance of Base.
195 196 |
# File 'lib/view_component/base.rb', line 195 def initialize(*) end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method_name, *args) ⇒ Object
243 244 245 246 247 248 249 250 251 252 253 254 |
# File 'lib/view_component/base.rb', line 243 def method_missing(method_name, *args) # rubocop:disable Style/MissingRespondToMissing super rescue => e # rubocop:disable Style/RescueStandardError e.set_backtrace e.backtrace.tap(&:shift) raise e, <<~MESSAGE.chomp if view_context && e.is_a?(NameError) && helpers.respond_to?(method_name) #{e.} You may be trying to call a method provided as a view helper. Did you mean `helpers.#{method_name}'? MESSAGE raise end |
Class Attribute Details
.identifier ⇒ String
The file path of the component Ruby file.
452 453 454 |
# File 'lib/view_component/base.rb', line 452 def identifier @identifier end |
.virtual_path ⇒ Object
458 459 460 |
# File 'lib/view_component/base.rb', line 458 def virtual_path @virtual_path end |
Instance Attribute Details
#__vc_original_view_context ⇒ Object
Returns the value of attribute __vc_original_view_context.
51 52 53 |
# File 'lib/view_component/base.rb', line 51 def __vc_original_view_context @__vc_original_view_context end |
Class Method Details
.collection_counter_parameter ⇒ Object
660 661 662 |
# File 'lib/view_component/base.rb', line 660 def collection_counter_parameter :"#{collection_parameter}_counter" end |
.collection_iteration_parameter ⇒ Object
670 671 672 |
# File 'lib/view_component/base.rb', line 670 def collection_iteration_parameter :"#{collection_parameter}_iteration" end |
.collection_parameter ⇒ Object
655 656 657 |
# File 'lib/view_component/base.rb', line 655 def collection_parameter provided_collection_parameter || name && name.demodulize.underscore.chomp("_component").to_sym end |
.compile(raise_errors: false, force: false) ⇒ Object
581 582 583 |
# File 'lib/view_component/base.rb', line 581 def compile(raise_errors: false, force: false) compiler.compile(raise_errors: raise_errors, force: force) end |
.compiled? ⇒ Boolean
571 572 573 |
# File 'lib/view_component/base.rb', line 571 def compiled? compiler.compiled? end |
.compiler ⇒ Object
586 587 588 |
# File 'lib/view_component/base.rb', line 586 def compiler @__vc_compiler ||= Compiler.new(self) end |
.config ⇒ ActiveSupport::OrderedOptions
Returns the current config.
27 28 29 |
# File 'lib/view_component/base.rb', line 27 def config ViewComponent::Config.current end |
.counter_argument_present? ⇒ Boolean
665 666 667 |
# File 'lib/view_component/base.rb', line 665 def counter_argument_present? initialize_parameter_names.include?(collection_counter_parameter) end |
.ensure_compiled ⇒ Object
576 577 578 |
# File 'lib/view_component/base.rb', line 576 def ensure_compiled compile unless compiled? end |
.inherited(child) ⇒ Object
516 517 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 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 |
# File 'lib/view_component/base.rb', line 516 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, format = 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, format) 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 < Rails.application.routes.url_helpers) child.include 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. # We use `base_label` method here instead of `label` to avoid cases where the method # owner is included in a prefix like `ApplicationComponent.inherited`. child.identifier = caller_locations(1, 10).reject { |l| l.base_label == "inherited" }[0].path # If Rails application is loaded, removes the first part of the path and the extension. if defined?(Rails) && Rails.application child.virtual_path = child.identifier.gsub( /(.*#{Regexp.quote(ViewComponent::Base.config.view_component_path)})|(\.rb)/, "" ) end # Set collection parameter to the extended component child.with_collection_parameter provided_collection_parameter if instance_methods(false).include?(:render_template_for) vc_ancestor_calls = defined?(@__vc_ancestor_calls) ? @__vc_ancestor_calls.dup : [] vc_ancestor_calls.unshift(instance_method(:render_template_for)) child.instance_variable_set(:@__vc_ancestor_calls, vc_ancestor_calls) end super end |
.iteration_argument_present? ⇒ Boolean
675 676 677 |
# File 'lib/view_component/base.rb', line 675 def iteration_argument_present? initialize_parameter_names.include?(collection_iteration_parameter) end |
.sidecar_files(extensions) ⇒ Object
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.
467 468 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 |
# File 'lib/view_component/base.rb', line 467 def sidecar_files(extensions) return [] unless identifier extensions = extensions.join(",") # view files in a directory named like the component directory = File.dirname(identifier) filename = File.basename(identifier, ".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 - [identifier] + sidecar_directory_files + nested_component_files).uniq end |
.strip_trailing_whitespace(value = true) ⇒ Object
Strips trailing whitespace from templates before compiling them.
“‘ruby class MyComponent < ViewComponent::Base
strip_trailing_whitespace
end “‘
611 612 613 |
# File 'lib/view_component/base.rb', line 611 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.
618 619 620 |
# File 'lib/view_component/base.rb', line 618 def strip_trailing_whitespace? __vc_strip_trailing_whitespace 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.
628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 |
# File 'lib/view_component/base.rb', line 628 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) || splatted_keyword_argument_present? # If Ruby can't parse the component class, then the initialize # parameters will be empty and ViewComponent will not be able to render # the component. if initialize_parameters.empty? raise EmptyOrInvalidInitializerError.new(name, parameter) end raise MissingCollectionArgumentError.new(name, parameter) end |
.validate_initialization_parameters! ⇒ Object
Ensure the component initializer doesn’t define invalid parameters that could override the framework’s methods.
648 649 650 651 652 |
# File 'lib/view_component/base.rb', line 648 def validate_initialization_parameters! return unless initialize_parameter_names.include?(RESERVED_PARAMETER) raise ReservedParameterError.new(name, RESERVED_PARAMETER) end |
.with_collection(collection, spacer_component: nil, **args) ⇒ Object
Render a component for each element in a collection ([documentation](/guide/collections)):
“‘ruby render(ProductsComponent.with_collection(@products, foo: :bar)) “`
511 512 513 |
# File 'lib/view_component/base.rb', line 511 def with_collection(collection, spacer_component: nil, **args) Collection.new(self, collection, spacer_component, **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 “`
597 598 599 600 |
# File 'lib/view_component/base.rb', line 597 def with_collection_parameter(parameter) @provided_collection_parameter = parameter @initialize_parameters = nil end |
Instance Method Details
#__vc_request ⇒ Object
Enables consumers to override request/@request
288 289 290 |
# File 'lib/view_component/base.rb', line 288 def __vc_request @__vc_request ||= controller.request if controller.respond_to?(:request) 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.
183 184 185 |
# File 'lib/view_component/base.rb', line 183 def before_render # noop end |
#content ⇒ String
The content passed to the component instance as a block.
295 296 297 298 299 300 301 302 303 304 305 |
# File 'lib/view_component/base.rb', line 295 def content @__vc_content_evaluated = true return @__vc_content if defined?(@__vc_content) @__vc_content = if __vc_render_in_block_provided? view_context.capture(self, &@__vc_render_in_block) elsif __vc_content_set_by_with_content_defined? @__vc_content_set_by_with_content end end |
#content? ⇒ Boolean
Whether ‘content` has been passed to the component.
310 311 312 |
# File 'lib/view_component/base.rb', line 310 def content? __vc_render_in_block_provided? || __vc_content_set_by_with_content_defined? end |
#controller ⇒ ActionController::Base
The current controller. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
218 219 220 221 222 |
# File 'lib/view_component/base.rb', line 218 def controller raise ControllerCalledBeforeRenderError if view_context.nil? @__vc_controller ||= view_context.controller end |
#format ⇒ Object
For caching, such as #cache_if
273 274 275 |
# File 'lib/view_component/base.rb', line 273 def format @__vc_variant if defined?(@__vc_variant) end |
#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.
228 229 230 231 232 233 234 235 236 237 238 239 |
# File 'lib/view_component/base.rb', line 228 def helpers raise HelpersCalledBeforeRenderError if view_context.nil? # 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 |
#output_postamble ⇒ String
Optional content to be returned after the rendered template.
175 176 177 |
# File 'lib/view_component/base.rb', line 175 def output_postamble @@default_output_postamble ||= "".html_safe end |
#output_preamble ⇒ String
Optional content to be returned before the rendered template.
168 169 170 |
# File 'lib/view_component/base.rb', line 168 def output_preamble @@default_output_preamble ||= "".html_safe 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`.
205 206 207 208 209 210 211 212 |
# File 'lib/view_component/base.rb', line 205 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.
190 191 192 |
# File 'lib/view_component/base.rb', line 190 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.
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 114 115 116 117 118 119 120 121 122 123 124 |
# File 'lib/view_component/base.rb', line 74 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 DuplicateContentError.new(self.class.name) end @__vc_content_evaluated = false @__vc_render_in_block = block before_render if render? rendered_template = render_template_for(@__vc_variant, __vc_request&.format&.to_sym).to_s # Avoid allocating new string when output_preamble and output_postamble are blank if output_preamble.blank? && output_postamble.blank? rendered_template else safe_output_preamble + rendered_template + safe_output_postamble end 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 %> # doesn’t double-render “‘
‘super` also doesn’t consider the current variant. ‘render_parent` renders the parent template considering the current variant and emits the result without double-rendering.
137 138 139 140 |
# File 'lib/view_component/base.rb', line 137 def render_parent render_parent_to_string nil end |
#render_parent_to_string ⇒ Object
Renders the parent component to a string and returns it. This method is meant to be used inside custom #call methods when a string result is desired, eg.
“‘ruby def call
"<div>#{render_parent_to_string}</div>"
end “‘
When rendering the parent inside an .erb template, use ‘#render_parent` instead.
152 153 154 155 156 157 158 159 160 161 162 163 |
# File 'lib/view_component/base.rb', line 152 def render_parent_to_string @__vc_parent_render_level ||= 0 # ensure a good starting value begin target_render = self.class.instance_variable_get(:@__vc_ancestor_calls)[@__vc_parent_render_level] @__vc_parent_render_level += 1 target_render.bind_call(self, @__vc_variant) ensure @__vc_parent_render_level -= 1 end end |
#request ⇒ ActionDispatch::Request
The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
281 282 283 |
# File 'lib/view_component/base.rb', line 281 def request __vc_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.
62 63 64 |
# File 'lib/view_component/base.rb', line 62 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
266 267 268 |
# File 'lib/view_component/base.rb', line 266 def view_cache_dependencies [] end |
#virtual_path ⇒ Object
Exposes .virtual_path as an instance method
260 261 262 |
# File 'lib/view_component/base.rb', line 260 def virtual_path self.class.virtual_path end |