Skip to content

Commit

Permalink
Address Docs related comments
Browse files Browse the repository at this point in the history
  • Loading branch information
pulkitkkr committed Aug 17, 2022
1 parent 31ad0b4 commit 656ec63
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 17 deletions.
2 changes: 1 addition & 1 deletion docs/api/view-helpers-api.md
Expand Up @@ -27,7 +27,7 @@ Uncommonly used options:
- **general options:**
- **props:** Ruby Hash which contains the properties to pass to the react object, or a JSON string. If you pass a string, we'll escape it for you.
- **prerender:** enable server-side rendering of a component. Set to false when debugging!
- **auto_load_bundle:** tries to load generated bundle for component from the generated directory.
- **auto_load_bundle:** will automatically load bundle for component by calling `append_javascript_pack_tag` and `append_stylesheet_pack_tag` under the hood.
- **id:** Id for the div, will be used to attach the React component. This will get assigned automatically if you do not provide an id. Must be unique.
- **html_options:** Any other HTML options get placed on the added div for the component. For example, you can set a class (or inline style) on the outer div so that it behaves like a span, with the styling of `display:inline-block`. You may also use an option of `tag: "span"` to replace the use of the default DIV tag to be a SPAN tag.
- **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise. Only on the **client side** will you will see the `railsContext` and your props.
Expand Down
37 changes: 21 additions & 16 deletions docs/guides/file-system-based-automated-bundle-generation.md
@@ -1,11 +1,11 @@
# File-System-Based Automated Bundle Generation

To use the automated bundle generation feature introduced in React on Rails v13.1.0, please upgrade to use [Shakapacker v6.5.0](https://github.com/shakacode/shakapacker/tree/v6.5.0) at least. If you are currently using webpacker, please follow the migration steps available [here](https://github.com/shakacode/shakapacker/blob/master/docs/v6_upgrade.md).
To use the automated bundle generation feature introduced in React on Rails v13.1.0, please upgrade to use [Shakapacker v6.5.1](https://github.com/shakacode/shakapacker/tree/v6.5.1) at least. If you are currently using webpacker, please follow the migration steps available [here](https://github.com/shakacode/shakapacker/blob/master/docs/v6_upgrade.md).

## Configuration

### Enable nested_entries for Shakapacker
To use the automated bundle generation feature, in the `webpacker.yml` file, set
To use the automated bundle generation feature, set nested_entries: true in the webpacker.yml file like this. The generated files will go in a nested directory.

```yml
default:
Expand All @@ -16,9 +16,8 @@ default:
For more details, see [Configuration and Code](https://github.com/shakacode/shakapacker#configuration-and-code) section in [shakapacker](https://github.com/shakacode/shakapacker/).

### Configure Components Directory
`components_directory` is the directories containing components that can be automatically registered and used in Rails views.
Configure `config/initializers/react_on_rails`
to set the name for `components_directory`.
`components_directory` is the name of the directories that contain components that will be automatically registered and used in Rails views.
For example, configure `config/initializers/react_on_rails` to set the name for `components_directory`

```rb
config.components_directory = "ror_components"
Expand All @@ -30,8 +29,6 @@ Now all React components inside the directories called `ror_components` will aut

For automated component registry, [`react_component`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component) and [`react_component_hash`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component_hash) view helper method tries to load generated bundle for component from the generated directory automatically per `auto_load_bundle` option. `auto_load_bundle` option in `config/initializers/react_on_rails` configures the default value that will be passed to component helpers. The default is `false`, and the parameter can be passed explicitly for each call.

*Note: Starting from React on Rails version 14.0.0, the default value for the `auto_load_bundle` option will be `true`.*

You can change the value in `config/initializers/react_on_rails` by updating it as follows:

```rb
Expand All @@ -42,8 +39,8 @@ config.auto_load_bundle = true
React on Rails automatically generates pack files for components to be registered in the `packs/generated` directory. To avoid committing generated files into the version control system, please update `.gitignore` to have

```gitignore
### Generated React on Rails packs
packs/generated
# Generated React on Rails packs
app/javascript/packs/generated
```

*Note: the directory might be different depending on the `source_entry_path` in `config/webpacker.yml`.*
Expand All @@ -52,7 +49,7 @@ packs/generated

### Basic usage

if the `webpacker.yml` file is configured as instructed [here](https://github.com/shakacode/shakapacker#configuration-and-code), with the following configurations
If the `webpacker.yml` file is configured as instructed [here](https://github.com/shakacode/shakapacker#configuration-and-code), with the following configurations

```yml
default: &default
Expand All @@ -69,7 +66,6 @@ the directory structure will look like this
app/javascript:
└── packs: # sets up webpack entries
│ └── application.js # references FooComponentOne.jsx, BarComponentOne.jsx and BarComponentTwo.jsx in `../src`
│ └── application.css
└── src: # any directory name is fine. Referenced files need to be under source_path
│ └── Foo
│ │ └── ...
Expand All @@ -84,12 +80,21 @@ app/javascript:
└── logo.svg
```

Now, to automatically register `FooComponentOne`, `BarComponentOne` and `BarComponentTwo` for the usage with [`react_component`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component) and [`react_component_hash`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component_hash) helpers, create a directory structure as mentioned below:
Previously, the`application.js` file would manually register `FooComponentOne`, `BarComponentOne` and `BarComponentTwo` using `ReactOnRails.register` as follows:
```jsx
import ReactOnRails from 'react-on-rails';
import FooComponentOne from '../src/Foo/FooComponentOne';
import BarComponentOne from '../src/Foo/BarComponentOne';
import BarComponentTwo from '../src/Foo/BarComponentTwo';

ReactOnRails.register({ FooComponentOne, BarComponentOne, BarComponentTwo });
```

Now, to automatically register `FooComponentOne`, `BarComponentOne` and `BarComponentTwo` for the usage with [`react_component`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component) and [`react_component_hash`](https://www.shakacode.com/react-on-rails/docs/api/view-helpers-api/#react_component_hash) helpers, delete the `application.js` file and create a directory structure as mentioned below:

```
app/javascript:
└── packs:
│ └── application.css
└── packs
└── src:
│ └── Foo
│ │ └── ...
Expand Down Expand Up @@ -128,9 +133,9 @@ the default value of the `auto_load_bundle` parameter can be specified by settin

### Server Rendering and Client Rendering Components

If server rendering is enabled, the component will be registered for usage both in server and client rendering. In order to have separate definitions for client and server rendering, name the component files as `Component_Name.server.jsx` and `Component_Name.client.jsx`. The `Component_Name.server.jsx` file will be used for server rendering and the `Component_Name.client.jsx` file for client rendering. If you don't want the component rendered on the server, you should only have the `Component_Name.client.jsx` file.
If server rendering is enabled, the component will be registered for usage both in server and client rendering. In order to have separate definitions for client and server rendering, name the component files as `ComponentName.server.jsx` and `ComponentName.client.jsx`. The `ComponentName.server.jsx` file will be used for server rendering and the `ComponentName.client.jsx` file for client rendering. If you don't want the component rendered on the server, you should only have the `ComponentName.client.jsx` file.

*Note: If specifying separate definitions for client and server rendering, please make sure to delete the generalized `Component_Name.jsx` file.*
*Note: If specifying separate definitions for client and server rendering, please make sure to delete the generalized `ComponentName.jsx` file.*

### Using Automated Bundle Generation Feature with already defined packs

Expand Down

0 comments on commit 656ec63

Please sign in to comment.