README.md in actionview-component-1.11.1 vs README.md in actionview-component-1.12.0
- old
+ new
@@ -1,21 +1,23 @@
_Note: This gem is in the process of a name / API change, see https://github.com/github/actionview-component/issues/206_
+_You are viewing the README for the development version of ActionView::Component. If you are using the current release version you can find the README at https://github.com/github/actionview-component/blob/v1.11.1/README.md_
+
# ActionView::Component
`ActionView::Component` is a framework for building view components in Rails.
**Current Status**: Used in production at GitHub. Because of this, all changes will be thoroughly vetted, which could slow down the process of contributing. We will do our best to actively communicate status of pull requests with any contributors. If you have any substantial changes that you would like to make, it would be great to first [open an issue](http://github.com/github/actionview-component/issues/new) to discuss them with us.
## Roadmap
-This gem is meant to serve as a precursor to upstreaming the `ActionView::Component` class into Rails. It also serves to enable the usage of `ActionView::Component` in older versions of Rails.
+Support for third-party component frameworks was merged into Rails `6.1.0.alpha` in https://github.com/rails/rails/pull/36388 and https://github.com/rails/rails/pull/37919. Our goal with this project is to provide a first-class component framework for this new capability in Rails.
-Preliminary support for rendering components was merged into Rails `6.1.0.alpha` in https://github.com/rails/rails/pull/36388. Assuming `ActionView::Component` makes it into Rails, this gem will then exist to serve as a backport.
+This gem includes a backport of those changes for Rails `5.0.0` through `6.1.0.alpha`.
## Design philosophy
-As the goal of this gem is to be upstreamed into Rails, it is designed to integrate as seamlessly as possible, with the [least surprise](https://www.artima.com/intv/ruby4.html).
+This library is designed to integrate as seamlessly as possible with Rails, with the [least surprise](https://www.artima.com/intv/ruby4.html).
## Compatibility
`actionview-component` is tested for compatibility with combinations of Ruby `2.5`/`2.6`/`2.7` and Rails `5.0.0`/`5.2.3`/`6.0.0`/`6.1.0.alpha`.
@@ -75,28 +77,18 @@
#### Data flow
By clearly defining the context necessary to render a component, we’ve found them to be easier to reuse than partials.
-#### Performance
-
-In early benchmarks, we’ve seen performance improvements over the existing rendering pipeline. For a test page with nested renders 10 levels deep, we’re seeing around a 5x increase in speed over partials:
-
-```
-Comparison:
- component: 6515.4 i/s
- partial: 1251.2 i/s - 5.21x slower
-```
-
-_Rails 6.1.0.alpha, [joelhawksley/actionview-component-demo](https://github.com/joelhawksley/actionview-component-demo), /benchmark route, via `RAILS_ENV=production rails s`, measured with [evanphx/benchmark-ips](https://github.com/evanphx/benchmark-ips)_
-
### When should I use components?
Components are most effective in cases where view code is reused or needs to be tested directly.
### Building components
+#### Conventions
+
Components are subclasses of `ActionView::Component::Base` and live in `app/components`. You may wish to create an `ApplicationComponent` that is a subclass of `ActionView::Component::Base` and inherit from that instead.
Component class names end in -`Component`.
Component module names are plural, as they are for controllers. (`Users::AvatarComponent`)
@@ -195,27 +187,29 @@
with_content_areas :header, :body
def initialize(user:)
@user = user
end
+
+ attr_reader :user
end
```
`app/components/modal_component.html.erb`:
```erb
<div class="modal">
<div class="header"><%= header %></div>
- <div class="body"><%= body %>"></div>
+ <div class="body"><%= body %></div>
</div>
```
We can render it in a view as:
```erb
<%= render(ModalComponent.new(user: {name: 'Jane'})) do |component| %>
<% component.with(:header) do %>
- Hello <%= user[:name] %>
+ Hello <%= component.user[:name] %>
<% end %>
<% component.with(:body) do %>
<p>Have a great day.</p>
<% end %>
<% end %>
@@ -248,11 +242,11 @@
end
```
```erb
<%= render(ModalComponent.new(header: "Hi!")) do |component| %>
- <% help_enabled? && component.with(:header) do %>
+ <% component.with(:header) do %>
<span class="help_icon"><%= component.header %></span>
<% end %>
<% component.with(:body) do %>
<p>Have a great day.</p>
<% end %>
@@ -314,11 +308,11 @@
```erb
<div class="modal">
<% if header %>
<div class="header"><%= header %></div>
<% end %>
- <div class="body"><%= body %>"></div>
+ <div class="body"><%= body %></div>
</div>
```
`app/views/render_arg.html.erb`:
```erb
@@ -376,18 +370,20 @@
The `#render?` hook allows you to move this logic into the Ruby class, leaving your views more readable and declarative in style:
```ruby
# app/components/confirm_email_component.rb
-class ConfirmEmailComponent < ApplicationComponent
+class ConfirmEmailComponent < ActionView::Component::Base
def initialize(user:)
@user = user
end
def render?
@user.requires_confirmation?
end
+
+ attr_reader :user
end
```
```
<!-- app/components/confirm_email_component.html.erb -->
@@ -510,11 +506,10 @@
config.action_view_component.preview_path = "#{Rails.root}/spec/components/previews"
```
### Initializer requirement
-In Ruby 2.6.x and below, ActionView::Component requires the presence of an `initialize` method in each component.
-However, `initialize` is no longer required for projects using 2.7.x and above.
+ActionView::Component requires the presence of an `initialize` method in each component.
## Frequently Asked Questions
### Can I use other templating languages besides ERB?