Skip to content

Commit 4198106

Browse files
jho406jho406
committed
Update docs
This updates docs to account for `foobar.html.erb` files made optional by superglue_rails v1.1.0. We also update some copy here too.
1 parent f4ab59b commit 4198106

11 files changed

+58
-48
lines changed

‎docs/configuration.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ when the internet is down.
2727
Stop by the [tutorial] to learn how to work with this file.
2828

2929
**Vite Users** This step can be entirely optional if you're using Vite. See
30-
the [recipe](recipe/vite.md) for more information.
30+
the [recipe](recipes/vite.md) for more information.
3131

3232
This file exports a mapping between a `componentIdentifier` to an imported page
3333
component. This gets used in your `application.js` so that superglue knows

‎docs/cross-cutting-concerns.md

-2
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,9 @@ app/
3030
| |-- posts/
3131
| | |-- index.js
3232
| | |-- index.json.props
33-
| | |-- index.html.erb
3433
| |-- comments/
3534
| | |-- index.js
3635
| | |-- index.json.props
37-
| | |-- index.html.erb
3836
```
3937

4038
By [design](./redux-state-shape.md) this results in duplicate JSON nodes

‎docs/index.md

+11-15
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Overview
22

3-
Superglue is a library that thoughtfully pairs Rails and React. Its
4-
built with a laser focus on The Rails Way and aims to provide a simple
5-
developer experience on par with Hotwire, Stimulus, and Turbo. Confidently use
6-
Rails routes, controllers, views as you normally would in a multi-page
7-
application and integrate with React's vast ecosystem.
3+
Superglue and friends [thoughtfully pairs Rails and React]. Its built with a
4+
laser focus on The Rails Way and aims to provide a simple developer experience
5+
on par with Hotwire, Stimulus, and Turbo. Confidently use Rails routes,
6+
controllers, views as you normally would in a multi-page application and
7+
integrate with React's vast ecosystem.
88

99
## Who is it for?
1010

@@ -78,7 +78,7 @@ end
7878
```
7979

8080
Familiar Rails conveniences include form_props (a fork of `form_with` made for React),
81-
flash messages integrated as a Redux [slice], and [Unobtrusive Javascript](UJS) helpers.
81+
flash messages integrated as a Redux [slice], and [Unobtrusive Javascript][UJS] helpers.
8282

8383
### It’s React
8484

@@ -120,7 +120,7 @@ export default function FooBar() {
120120
}
121121
```
122122

123-
### It’s Turbolinks and UJS
123+
### It’s Turbolinks
124124

125125
Superglue drew inspiration fromthe original Turbolinks, but instead of sending
126126
your `foobar.html.erb` over the wire and swapping the `<body>`, it sends
@@ -134,12 +134,7 @@ your React components to SPA transition to the next page.
134134
<a href=”/next_page” data-sg-visit> Next Page </a>
135135
```
136136

137-
## A thoughtful pairing
138-
139-
Superglue is about thoughfully pairing React and Rails that brings out the best
140-
of both frameworks.
141-
142-
### The return of UJS and diggable templates
137+
### The return of UJS
143138

144139
Superglue’s secret sauce is that your `foobar.json.props` is diggable; making
145140
any part of your page dynamic by using a query string. It’s a simpler approach
@@ -231,6 +226,7 @@ your team.
231226

232227

233228
[Redux state]: ./redux-state-shape.md
234-
[modals]: ./recipes/modals.md
235-
[more]: ./recipes
229+
[modals]: recipes/modals.md
230+
[more]: recipes/
236231
[slice]: ./cross-cutting-concerns.md#slices
232+
[thoughtfully pairs Rails and React]: https://thoughtbot.com/blog/superglue-1-0-react-rails-a-new-era-of-thoughtfulness

‎docs/navigation-context.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ const {
1717
```
1818

1919
<div class="grid cards" markdown>
20-
- [:octicons-arrow-right-24: See complete reference](../reference/types/#navigationcontextprops)
20+
- [:octicons-arrow-right-24: See complete reference](reference/types.md#navigationcontextprops)
2121
for `NavigationContext`
2222
</div>
2323

@@ -73,5 +73,5 @@ the URL.
7373
for `navigateTo`
7474
</div>
7575

76-
[saving]: ../reference/#saveandprocesspage
77-
[copyPage]: ../reference/#copypage
76+
[saving]: ./reference/index.md#saveandprocesspage
77+
[copyPage]: ./reference/index.md#copypage

‎docs/recipes/infinite-scroll.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ And continue off from our [pagination] recipe.
1616
We'll use the `beforeSave` callback to modify the payload before superglue
1717
saves it to the store. This callback is an option for both `visit` and
1818
`remote` functions. See the
19-
[beforeSave reference](../reference/types.requests/#beforesave-2) for more details.
19+
[beforeSave reference](../reference/types.requests.md#beforesave-2) for more details.
2020

2121
```diff
2222
// app/views/posts/index.js

‎docs/recipes/modals.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Both urls render a list of posts. Lets set up the controller and the
4040
Similarly, we tie the `componentIdentifier` to the same page component.
4141

4242
**Vite Users** This step can be entirely optional if you're using Vite. See
43-
the [recipe](recipe/vite.md) for more information.
43+
the [recipe](./vite.md) for more information.
4444

4545
```js
4646
import PostIndex from '../views/posts/index'

‎docs/recipes/ssr.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ setHumidRenderer((json, baseUrl, path) => {
3333
// and `remote` thunks.
3434
baseUrl={baseUrl}
3535
// The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
36-
// template, e.g., index.html.erb
36+
// template, e.g., application/superglue.html.erb
3737
initialPage={initialState}
3838
// The initial path of the page, e.g., /foobar
3939
path={path}
@@ -125,9 +125,14 @@ Add a line to your `package.json` like so:
125125
+ "build:ssr": "node ./build-ssr.mjs"
126126
```
127127

128-
Use `Humid.render` in all your ERB templates `index.html.erb`:
128+
Use `Humid.render` in all your ERB templates `superglue.html.erb`:
129129

130130
```diff
131+
<script type="text/javascript">
132+
- window.SUPERGLUE_INITIAL_PAGE_STATE=<%= render_props %>;<%# erblint:disable ErbSafety %>
133+
+ <% initial_state = render_props %>
134+
+ window.SUPERGLUE_INITIAL_PAGE_STATE=<%= initial_state %>;<%# erblint:disable ErbSafety %>
135+
</script>
131136
- <div id="app"></div>
132137
+ <div id="app"><%= Humid.render(initial_state, request.scheme + '://' + request.host_with_port, request.fullpath).html_safe %></div>
133138
```

‎docs/recipes/vite.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ And finally, one of the more manual process of using superglue is the [manual bu
4545
of your `page_to_page_mapping.js` file. We can improve the developer experience by
4646
removing that step by using this snippet:
4747

48-
[manual build]: ../configuration
48+
[manual build]: ../configuration.md
4949

5050
```javascript
5151
const pageIdentifierToPageComponent = {}

‎docs/requests.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ offers, Superglue comes with two functions built around `fetch`, `visit` and
55
`remote`. These are wrapped with your own implementation in
66
[application_visit.js] and can be accessed via the [NavigationContext].
77

8-
[NavigationContext]: ../reference/types/#navigationcontextprops
8+
[NavigationContext]: reference/types.md#navigationcontextprops
99

1010

1111
!!! tip

‎docs/tutorial.md

+30-19
Original file line numberDiff line numberDiff line change
@@ -25,20 +25,38 @@ Lets begin by adding a route and a controller to an app.
2525
=== "`greet_controller.rb`"
2626
in `app/controllers/greet_controller.rb`
2727

28+
!!! tip Enable jsx rendering defaults
29+
`use_jsx_rendering_defaults` enables Rails to look for `.jsx` files and
30+
pairs with `.props` files. For example:
31+
32+
```
33+
app/views
34+
application/
35+
superglue.html.erb
36+
about/
37+
index.jsx
38+
users/
39+
index.jsx
40+
index.json.props
41+
```
42+
2843
```ruby
2944
class GreetController < ApplicationController
45+
before_action :use_jsx_rendering_defaults
46+
3047
def show
3148
end
3249
end
3350
```
3451

3552
### Add the views
3653

37-
Next lets add the following views. Here we're splitting the usual `show.html.erb` into 3 parts:
38-
54+
Next lets add the following views.
3955
- `app/views/greet/show.json.props`
40-
- `app/views/greet/show.js`
41-
- `app/views/greet/show.html.erb`
56+
- `app/views/greet/show.jsx`
57+
58+
The Superglue installation generator also adds a `application/superglue.html.erb`, which
59+
will be used as the default html template for every controller action.
4260

4361
Click the tabs below to see the contents:
4462

@@ -72,7 +90,7 @@ Click the tabs below to see the contents:
7290
body,
7391
footer
7492
} = useContent();
75-
93+
7694
const {greet} = body
7795

7896
return (
@@ -84,22 +102,15 @@ Click the tabs below to see the contents:
84102
}
85103
```
86104

87-
=== "3. `show.html.erb`"
88-
89-
!!! info
90-
This file is usually generated by a scaffold and stays exactly the same
91-
regardless if its `index.html.erb`, `show.html.erb`, `edit.html.erb`, etc.
105+
=== "3. `application/superglue.html.erb`"
92106

93107

94108
```ruby
95-
<% initial_state = controller.render_to_string(formats: [:json], locals: local_assigns, layout: true) %>
96-
97109
<script type="text/javascript">
98-
window.SUPERGLUE_INITIAL_PAGE_STATE=<%= initial_state.html_safe %>;<%# erblint:disable ErbSafety %>
110+
window.SUPERGLUE_INITIAL_PAGE_STATE=<%= render_props %>;<%# erblint:disable ErbSafety %>
99111
</script>
100112

101113
<div id="app"></div>
102-
103114
```
104115

105116
This file renders `show.json.props`, injects it globally as the initial
@@ -108,10 +119,10 @@ Click the tabs below to see the contents:
108119

109120
### Connect the dots
110121

111-
The json [payload] that gets rendered into `show.html.erb` contains an the
112-
`componentIdentifier`. We're going to use the `componentIdentifier` to tie
113-
`show.json.props` to `show.js` so superglue knows which component to render
114-
with which response by modifying `app/javascript/page_to_page_mapping.js`.
122+
The json [payload] that gets injected contains a `componentIdentifier`. We're
123+
going to use the `componentIdentifier` to tie `show.json.props` to `show.js` so
124+
superglue knows which component to render with which response by modifying
125+
`app/javascript/page_to_page_mapping.js`.
115126

116127
[payload]: page-response.md
117128

@@ -121,7 +132,7 @@ with which response by modifying `app/javascript/page_to_page_mapping.js`.
121132
gets rendered. In our case: http://localhost:3000/greet.json
122133

123134
**Vite Users** This step can be entirely optional if you're using Vite. See
124-
the [recipe](/superglue/recipes/vite/) for more information.
135+
the [recipe](recipes/vite.md) for more information.
125136

126137
=== "1. Example `greet.json`"
127138
The layout for `show.json.props` is located at `app/views/layouts/application.json.props`. It

‎superglue/lib/types/index.ts

+2-2
Original file line numberDiff line numberDiff line change
@@ -472,7 +472,7 @@ export interface BuildVisitAndRemote {
472472
export interface SetupProps {
473473
/**
474474
* The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
475-
* template, e.g., index.html.erb
475+
* template, e.g., application/superglue.html.erb
476476
*/
477477
initialPage: VisitResponse
478478
/**
@@ -517,7 +517,7 @@ export interface ApplicationProps
517517
extends React.ComponentPropsWithoutRef<'div'> {
518518
/**
519519
* The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
520-
* template, e.g., index.html.erb
520+
* template, e.g., application/superglue.html.erb
521521
*/
522522
initialPage: VisitResponse
523523
/**

0 commit comments

Comments
 (0)