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
Constant Summary collapse
- ViewContextCalledBeforeRenderError =
Class.new(StandardError)
- RESERVED_PARAMETER =
:content
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.
-
._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) ⇒ 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 does not 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.
-
#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.
-
#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.
129 |
# File 'lib/view_component/base.rb', line 129 def initialize(*); end |
Class Attribute Details
.source_location ⇒ Object
299 300 301 |
# File 'lib/view_component/base.rb', line 299 def source_location @source_location end |
.virtual_path ⇒ Object
299 300 301 |
# File 'lib/view_component/base.rb', line 299 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 |
._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.
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 |
# File 'lib/view_component/base.rb', line 309 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. # # e.g. # # 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
488 489 490 |
# File 'lib/view_component/base.rb', line 488 def collection_counter_parameter "#{collection_parameter}_counter".to_sym end |
.collection_iteration_parameter ⇒ Object
498 499 500 |
# File 'lib/view_component/base.rb', line 498 def collection_iteration_parameter "#{collection_parameter}_iteration".to_sym end |
.collection_parameter ⇒ Object
479 480 481 482 483 484 485 |
# File 'lib/view_component/base.rb', line 479 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) ⇒ 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.
399 400 401 |
# File 'lib/view_component/base.rb', line 399 def compile(raise_errors: false) compiler.compile(raise_errors: raise_errors) end |
.compiled? ⇒ Boolean
390 391 392 |
# File 'lib/view_component/base.rb', line 390 def compiled? compiler.compiled? end |
.compiler ⇒ Object
404 405 406 |
# File 'lib/view_component/base.rb', line 404 def compiler @__vc_compiler ||= Compiler.new(self) end |
.counter_argument_present? ⇒ Boolean
493 494 495 |
# File 'lib/view_component/base.rb', line 493 def counter_argument_present? initialize_parameter_names.include?(collection_counter_parameter) end |
.format ⇒ Object
415 416 417 |
# File 'lib/view_component/base.rb', line 415 def format :html end |
.identifier ⇒ Object
420 421 422 |
# File 'lib/view_component/base.rb', line 420 def identifier source_location end |
.inherited(child) ⇒ Object
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 |
# File 'lib/view_component/base.rb', line 362 def inherited(child) # Compile so child will inherit compiled `call_*` template methods that # `compile` defines compile # 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].absolute_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
503 504 505 |
# File 'lib/view_component/base.rb', line 503 def iteration_argument_present? initialize_parameter_names.include?(collection_iteration_parameter) end |
.short_identifier ⇒ Object
Provide identifier for ActionView template annotations
357 358 359 |
# File 'lib/view_component/base.rb', line 357 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
410 411 412 |
# File 'lib/view_component/base.rb', line 410 def type "text/html" end |
.validate_collection_parameter!(validate_default: false) ⇒ Object
Ensure the component initializer accepts the collection parameter. By default, we do not validate that the default parameter name is accepted, as support for collection rendering is optional.
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 |
# File 'lib/view_component/base.rb', line 439 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 cannot 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} does not 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 does not define invalid parameters that could override the framework’s methods.
469 470 471 472 473 474 475 476 |
# File 'lib/view_component/base.rb', line 469 def validate_initialization_parameters! return unless initialize_parameter_names.include?(RESERVED_PARAMETER) raise ViewComponent::ComponentError.new( "#{self} initializer cannot 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))
350 351 352 |
# File 'lib/view_component/base.rb', line 350 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
429 430 431 |
# File 'lib/view_component/base.rb', line 429 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.
101 102 103 |
# File 'lib/view_component/base.rb', line 101 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.
109 110 111 |
# File 'lib/view_component/base.rb', line 109 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.
117 118 119 |
# File 'lib/view_component/base.rb', line 117 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.
151 152 153 154 155 156 157 158 159 160 161 162 163 164 |
# File 'lib/view_component/base.rb', line 151 def controller if view_context.nil? raise( ViewContextCalledBeforeRenderError, "`#controller` cannot 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
208 209 210 211 212 213 |
# File 'lib/view_component/base.rb', line 208 def format # Ruby 2.6 throws a warning without checking `defined?`, 2.7 does not if defined?(@__vc_variant) @__vc_variant end 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.
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 |
# File 'lib/view_component/base.rb', line 170 def helpers if view_context.nil? raise( ViewContextCalledBeforeRenderError, "`#helpers` cannot 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`.
138 139 140 141 142 143 144 145 |
# File 'lib/view_component/base.rb', line 138 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.
124 125 126 |
# File 'lib/view_component/base.rb', line 124 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.
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 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 |
# File 'lib/view_component/base.rb', line 51 def render_in(view_context, &block) self.class.compile(raise_errors: true) @view_context = view_context self.__vc_original_view_context ||= view_context @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 |
#request ⇒ ActionDispatch::Request
The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
234 235 236 |
# File 'lib/view_component/base.rb', line 234 def request @request ||= controller.request if controller.respond_to?(:request) end |
#view_cache_dependencies ⇒ Object
For caching, such as #cache_if
201 202 203 |
# File 'lib/view_component/base.rb', line 201 def view_cache_dependencies [] end |
#virtual_path ⇒ Object
Exposes .virtual_path as an instance method
195 196 197 |
# File 'lib/view_component/base.rb', line 195 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.
220 221 222 223 224 225 226 227 228 |
# File 'lib/view_component/base.rb', line 220 def with_variant(variant) ActiveSupport::Deprecation.warn( "`with_variant` is deprecated and will be removed in ViewComponent v3.0.0." ) @__vc_variant = variant self end |