Skip to content

Commit

Permalink
Reorganize documentation (ViewComponent#973)
Browse files Browse the repository at this point in the history 
This PR reorganizes our documentation a bit, fleshing out the landing page and the contributing guidelines. It's probably best reviewed via the Pages Preview.
  • Loading branch information
@joelhawksley
joelhawksley authored Jun 18, 2021
1 parent 54aa0f5 commit 0a3fe23
Show file tree
Hide file tree
Showing 5 changed files with 174 additions and 159 deletions.
69 changes: 41 additions & 28 deletions docs/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,34 +13,6 @@ If you have any substantial changes that you would like to make, please [open an

Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE.txt).

## Roles

### Triager

ViewComponent triagers are able to manage issues and pull request by assigning owners and labels, closing issues and marking duplicates.

After helping with the project by participating in issues, pull requests, and/or discussions, members of the community are welcome to request triage access by opening a pull request to update this list:

The triagers team is @andrewmcodes, @bbugh, @cesariouy, @dark-panda, @dylnclrk, @g13ydson, @horacio, @jcoyne, @johannesengl, @kaspermeyer, @mellowfish, @metade, @nashby, @rainerborene, @rdavid1099, @spdawson, and @vinistock.

Committers and maintainers may also nominate triagers by opening a pull request to update this list.

### Committer

ViewComponent committers have `write` access, enabling them to push directly to the repository and approve/merge pull requests. Committers often have implicit ownership over a particular area of the project, such as previews, generators, or translations.

Triagers are invited to become committers by having an existing committer or maintainer open a pull request on the repository to update this list of committers:

The committers team is @elia, @jonspalmer, @juanmanuelramallo, @rmacklin, and @spone.

### Maintainer

ViewComponent maintainers have `admin` access, enabling them to manage repository settings including access levels. They also have ownership of `view_component` on RubyGems and are required to have 2FA enabled for their GitHub and RubyGems accounts.

Maintainership is open by invitation only at this time.

The maintainers team is @blakewilliams, @joelhawksley, @jonrohan, and @manuelpuyol.

## Submitting a pull request

1. [Fork](https://github.com/github/view_component/fork) and clone the repository.
Expand All @@ -61,14 +33,55 @@ Here are a few things you can do that will increase the likelihood of your pull

## Documentation

### Previewing changes locally

1. Navigate to `/docs`.
1. Configure and install the dependencies: `bundle`.
1. Run Jekyll: `bundle exec jekyll serve`.
1. Open the docs site at `http://127.0.0.1:4000/`.
1. If making changes to the API, run `bundle exec rake docs:build` to generate `docs/api.md` from YARD comments.

### Style guidelines

- Keep it short.
- Avoid unclear antecedents. Use `the method name is too long` instead of `it is too long`.
- Avoid `you`, `we`, `your`, `our`.
- Write in the [active voice](https://writing.wisc.edu/handbook/style/ccs_activevoice/). Avoid the passive voice.

Don't be afraid to ask for help! We recognize that English is not the first language of many folks who contribute to ViewComponent.

## Releasing

If you are the current maintainer of this gem:

1. Run `./script/release` and follow the instructions.

## Governance

ViewComponent is built by over a hundred members of the community. Project membership has three levels:

### Triage

ViewComponent triagers are able to manage issues and pull request by assigning owners and labels, closing issues and marking duplicates.

After helping with the project by participating in issues, pull requests, and/or discussions, members of the community are welcome to request triage access by opening a pull request to update this list:

The triagers team is @andrewmcodes, @bbugh, @cesariouy, @dark-panda, @dylnclrk, @g13ydson, @horacio, @jcoyne, @johannesengl, @kaspermeyer, @mellowfish, @metade, @nashby, @rainerborene, @rdavid1099, @spdawson, and @vinistock.

Committers and maintainers may also nominate triagers by opening a pull request to update this list.

### Commit

ViewComponent committers have `write` access, enabling them to push directly to the repository and approve/merge pull requests. Committers often have implicit ownership over a particular area of the project, such as previews, generators, or translations.

Triagers are invited to become committers by having an existing committer or maintainer open a pull request on the repository to update this list of committers:

The committers team is @elia, @jonspalmer, @juanmanuelramallo, @rmacklin, and @spone.

### Maintain

ViewComponent maintainers have `admin` access, enabling them to manage repository settings including access levels. They also have ownership of `view_component` on RubyGems and are required to have 2FA enabled for their GitHub and RubyGems accounts.

Maintainership is open by invitation only at this time.

The maintainers team is @blakewilliams, @joelhawksley, @jonrohan, and @manuelpuyol.
97 changes: 97 additions & 0 deletions docs/guide/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
layout: default
title: Getting started
parent: Building ViewComponents
nav_order: 1
---

# Getting started

## Conventions

- Components are subclasses of `ViewComponent::Base` and live in `app/components`. It's common practice to create and inherit from an `ApplicationComponent` that is a subclass of `ViewComponent::Base`.
- Component names end in -`Component`.
- Component module names are plural, as for controllers and jobs: `Users::AvatarComponent`
- Name components for what they render, not what they accept. (`AvatarComponent` instead of `UserComponent`)

## Installation

In `Gemfile`, add:

```ruby
gem "view_component", require: "view_component/engine"
```

## Quick start

Use the component generator to create a new ViewComponent.

The generator accepts a component name and a list of arguments:

```console
bin/rails generate component Example title

invoke test_unit
create test/components/example_component_test.rb
create app/components/example_component.rb
create app/components/example_component.html.erb
```

Available options to customize the generator are documented on the [Generators](/guide/generators.html) page.

## Implementation

A ViewComponent is a Ruby file and corresponding template file with the same base name:

```ruby
# app/components/example_component.rb
class ExampleComponent < ViewComponent::Base
def initialize(title:)
@title = title
end
end
```

```erb
<%# app/components/example_component.html.erb %>
<span title="<%= @title %>"><%= content %></span>
```

Content passed to a ViewComponent as a block is captured and assigned to the `content` accessor.

Rendered in a view as:

```erb
<%# app/views/home/index.html.erb %>
<%= render(ExampleComponent.new(title: "my title")) do %>
Hello, World!
<% end %>
```

Returning:

```html
<span title="my title">Hello, World!</span>
```

## `#with_content`

String content can also be passed to a ViewComponent by calling `#with_content`:

```erb
<%# app/views/home/index.html.erb %>
<%= render(ExampleComponent.new(title: "my title").with_content("Hello, World!")) %>
```

## Rendering from controllers

It's also possible to render ViewComponents in controllers:

```ruby
# app/controllers/home_controller.rb
def show
render(ExampleComponent.new(title: "My Title")) { "Hello, World!" }
end
```

_In versions of Rails < 6.1, rendering a ViewComponent from a controller does not include the layout._
81 changes: 0 additions & 81 deletions docs/guide/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,84 +6,3 @@ has_children: true
---

# Building ViewComponents

## Conventions

- Components are subclasses of `ViewComponent::Base` and live in `app/components`. It's common practice to create and inherit from an `ApplicationComponent` that is a subclass of `ViewComponent::Base`.
- Component names end in -`Component`.
- Component module names are plural, as for controllers and jobs: `Users::AvatarComponent`
- Name components for what they render, not what they accept. (`AvatarComponent` instead of `UserComponent`)

## Quick start

Use the component generator to create a new ViewComponent.

The generator accepts a component name and a list of arguments:

```console
bin/rails generate component Example title

invoke test_unit
create test/components/example_component_test.rb
create app/components/example_component.rb
create app/components/example_component.html.erb
```

Available options to customize the generator are documented on the [Generators](/guide/generators.html) page.

## Implementation

A ViewComponent is a Ruby file and corresponding template file with the same base name:

```ruby
# app/components/example_component.rb
class ExampleComponent < ViewComponent::Base
def initialize(title:)
@title = title
end
end
```

```erb
<%# app/components/example_component.html.erb %>
<span title="<%= @title %>"><%= content %></span>
```

Content passed to a ViewComponent as a block is captured and assigned to the `content` accessor.

Rendered in a view as:

```erb
<%# app/views/home/index.html.erb %>
<%= render(ExampleComponent.new(title: "my title")) do %>
Hello, World!
<% end %>
```

Returning:

```html
<span title="my title">Hello, World!</span>
```

## `#with_content`

String content can also be passed to a ViewComponent by calling `#with_content`:

```erb
<%# app/views/home/index.html.erb %>
<%= render(ExampleComponent.new(title: "my title").with_content("Hello, World!")) %>
```

## Rendering from controllers

It's also possible to render ViewComponents in controllers:

```ruby
# app/controllers/home_controller.rb
def show
render(ExampleComponent.new(title: "My Title")) { "Hello, World!" }
end
```

_In versions of Rails < 6.1, rendering a ViewComponent from a controller does not include the layout._
44 changes: 36 additions & 8 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,45 @@ nav_order: 1

A framework for building reusable, testable & encapsulated view components in Ruby on Rails.

## Design philosophy
## What is a ViewComponent?

ViewComponents are Ruby objects used to build markup. Think of them as an evolution of the presenter pattern, inspired by [React](https://reactjs.org/docs/react-component.html).

## When should I use ViewComponents?

ViewComponents best for templates that are reused or benefit from being tested directly. Heavily reused partials and templates with significant amounts of embedded Ruby often make good ViewComponents.

## Benefits

### Testing

Unlike traditional Rails templates, ViewComponents can be unit tested. In the GitHub codebase, ViewComponent unit tests are over 100x faster than similar controller tests.

With ViewComponent, integration tests can be reserved for end-to-end assertions, with permutations covered at the unit level.

### Data Flow

ViewComponent is designed to integrate as seamlessly as possible [with Rails](https://rubyonrails.org/doctrine/), with the [least surprise](https://www.artima.com/intv/ruby4.html).
Traditional Rails templates have an implicit interface, making it hard to reason about their dependencies. This can lead to subtle bugs when rendering the same template in different contexts.

## Installation
ViewComponents use a standard Ruby initializer that clearly defines what is needed to render, making reuse easier (and safer) than with partials.

In `Gemfile`, add:
### Performance

```ruby
gem "view_component", require: "view_component/engine"
```
Based on our [benchmarks](https://github.com/github/view_component/blob/main/performance/benchmark.rb), ViewComponents are ~10x faster than partials.

### Code quality

Template code often fails basic Ruby standards: long methods, deep conditional nesting, and mystery guests abound.

ViewComponents are Ruby objects, making it easy to follow (and enforce) code quality standards.

## Design philosophy

ViewComponent is designed to integrate with Rails as seamlessly as possible, with the [least surprise](https://www.artima.com/intv/ruby4.html).

## Contributors

ViewComponent is built by:
ViewComponent is built by over a hundred members of the community, including:

<img src="https://avatars.githubusercontent.com/asgerb?s=64" alt="asgerb" width="32" />
<img src="https://avatars.githubusercontent.com/bbugh?s=64" alt="bbugh" width="32" />
Expand Down Expand Up @@ -83,3 +107,7 @@ ViewComponent is built by:
<img src="https://avatars.githubusercontent.com/vinistock?s=64" alt="vinistock" width="32" />
<img src="https://avatars.githubusercontent.com/xronos-i-am?s=64" alt="xronos-i-am" width="32" />
<img src="https://avatars.githubusercontent.com/matheusrich?s=64" alt="matheusrich" width="32" />

<hr />

[Getting started →](/guide/getting-started.html)
42 changes: 0 additions & 42 deletions docs/motivation.md
View file

This file was deleted.

0 comments on commit 0a3fe23

Please sign in to comment.