From 656ec63ba3bc8f9282e85a666621113fe0f85f3f Mon Sep 17 00:00:00 2001 From: pulkitkkr Date: Tue, 16 Aug 2022 22:27:56 -0400 Subject: [PATCH] Address Docs related comments --- docs/api/view-helpers-api.md | 2 +- ...ystem-based-automated-bundle-generation.md | 37 +++++++++++-------- 2 files changed, 22 insertions(+), 17 deletions(-) diff --git a/docs/api/view-helpers-api.md b/docs/api/view-helpers-api.md index dbe61ce34..fe023736f 100644 --- a/docs/api/view-helpers-api.md +++ b/docs/api/view-helpers-api.md @@ -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. diff --git a/docs/guides/file-system-based-automated-bundle-generation.md b/docs/guides/file-system-based-automated-bundle-generation.md index 21644339c..c590e1bf5 100644 --- a/docs/guides/file-system-based-automated-bundle-generation.md +++ b/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: @@ -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" @@ -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 @@ -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`.* @@ -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 @@ -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 │ │ └── ... @@ -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 │ │ └── ... @@ -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