README.md in actionview-component-1.10.0 vs README.md in actionview-component-1.11.0
- old
+ new
@@ -1,5 +1,7 @@
+_Note: This gem is in the process of a name / API change, see https://github.com/github/actionview-component/issues/206_
+
# 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.
@@ -13,11 +15,11 @@
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).
## Compatibility
-`actionview-component` is tested for compatibility with combinations of Ruby `2.5`/`2.6` and Rails `5.0.0`/`5.2.3`/`6.0.0`/`6.1.0.alpha`.
+`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`.
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -115,10 +117,22 @@
create test/components/example_component_test.rb
create app/components/example_component.rb
create app/components/example_component.html.erb
```
+`ActionView::Component` includes template generators for the `erb`, `haml`, and `slim` template engines and will use the template engine specified in your Rails config (`config.generators.template_engine`) by default.
+
+If you want to override this behavior, you can pass the template engine as an option to the generator:
+
+```bash
+bin/rails generate component Example title content --template-engine slim
+ invoke test_unit
+ create test/components/example_component_test.rb
+ create app/components/example_component.rb
+ create app/components/example_component.html.slim
+```
+
#### Implementation
An `ActionView::Component` is a Ruby file and corresponding template file (in any format supported by Rails) with the same base name:
`app/components/test_component.rb`:
@@ -387,21 +401,20 @@
<%= render(ConfirmEmailComponent.new(user: current_user)) %>
```
### Testing
-Components are unit tested directly. The `render_inline` test helper wraps the result in `Nokogiri.HTML`, allowing us to test the component above as:
+Components are unit tested directly. The `render_inline` test helper is compatible with Capybara matchers, allowing us to test the component above as:
```ruby
require "action_view/component/test_case"
class MyComponentTest < ActionView::Component::TestCase
test "render component" do
- assert_equal(
- %(<span title="my title">Hello, World!</span>),
- render_inline(TestComponent.new(title: "my title")) { "Hello, World!" }.to_html
- )
+ render_inline(TestComponent.new(title: "my title")) { "Hello, World!" }
+
+ assert_selector("span[title='my title']", "Hello, World!")
end
end
```
In general, we’ve found it makes the most sense to test components based on their rendered HTML.
@@ -411,13 +424,12 @@
To test a specific variant you can wrap your test with the `with_variant` helper method as:
```ruby
test "render component for tablet" do
with_variant :tablet do
- assert_equal(
- %(<span title="my title">Hello, tablets!</span>),
- render_inline(TestComponent.new(title: "my title")) { "Hello, tablets!" }.css("span").to_html
- )
+ render_inline(TestComponent.new(title: "my title")) { "Hello, tablets!" }
+
+ assert_selector("span[title='my title']", "Hello, tablets!")
end
end
```
### Previewing Components