bullet_train 1.14.1 → 1.14.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/app/views/devise/mailer/unlock_instructions.html.erb +1 -1
- data/docs/javascript.md +39 -1
- data/docs/oauth.md +2 -0
- data/docs/stripe-connect.md +77 -0
- data/lib/bullet_train/version.rb +1 -1
- metadata +3 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 71828511bb47aaec322fe2df6eb57da6803f85ec5574c789b7239ef059dded39
|
4
|
+
data.tar.gz: 95efdfff897bf780f45c3d24a4e53ea3259a2901c503e96d851a7a63129df049
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 72baa13642dcb282d08d5fa88e4bddb4665f84b79968b421d40d4d9a6d88caa4dbeb13f93338de04dda1014f4beabbbea0a962b83d3911065e938acc3f3c614a
|
7
|
+
data.tar.gz: 9922c22a48bac4248dcd0c240662339bad4cee568602f48ea436d0066c4740551d12bdbdb301d9a35a1bab86a7ee0e59c64dc737b6427b803ad89a2ab4b7f425
|
data/docs/javascript.md
CHANGED
@@ -2,7 +2,7 @@
|
|
2
2
|
Bullet Train leans into the use of [Stimulus](https://stimulus.hotwired.dev) for custom JavaScript. If you haven't read it previously, [the original introductory blog post for Stimulus from 2018](https://medium.com/signal-v-noise/stimulus-1-0-a-modest-javascript-framework-for-the-html-you-already-have-f04307009130) was groundbreaking in its time, and we still consider it required reading for understanding the philosophy of JavaScript in Bullet Train.
|
3
3
|
|
4
4
|
## Writing Custom JavaScript
|
5
|
-
The happy path for writing new custom JavaScript is to [write it as a Stimulus controller](https://stimulus.hotwired.dev/handbook/building-something-real) in `app/javascript/controllers` and invoke it by augmenting the HTML in your views. If you name the file `*_controller.js`, it will be automatically picked up and compiled as part of your application's JavaScript bundle.
|
5
|
+
The happy path for writing new custom JavaScript is to [write it as a Stimulus controller](https://stimulus.hotwired.dev/handbook/building-something-real) in `app/javascript/controllers` and invoke it by augmenting the HTML in your views. If you name the file `*_controller.js`, it will be automatically picked up and compiled as part of your application's JavaScript bundle. Be careful to [avoid adding scripts to the body of your pages (see below)](#avoid-scripts-in-the-body).
|
6
6
|
|
7
7
|
## npm Packages
|
8
8
|
npm packages are managed by [Yarn](https://yarnpkg.com) and any required importing can be done in `app/javascript/application.js`.
|
@@ -16,3 +16,41 @@ The resulting JavaScript bundle is output to the `app/assets/builds` directory w
|
|
16
16
|
|
17
17
|
## React, Vue.js, etc.
|
18
18
|
We're not against the use of front-end JavaScript frameworks in the specific contexts where they're the best tool for the job, but we solidly subscribe to the "heavy machinery" philosophy put forward in [that original Stimulus blog post](https://medium.com/signal-v-noise/stimulus-1-0-a-modest-javascript-framework-for-the-html-you-already-have-f04307009130), and have no interest in actually supporting them.
|
19
|
+
|
20
|
+
## Complex Screen Interactions
|
21
|
+
|
22
|
+
For more complex screen interactions, we do recommend using features of Hotwire's Turbo framework, Turbo Frames in particular.
|
23
|
+
|
24
|
+
Here are some important considerations:
|
25
|
+
|
26
|
+
### Avoid Morphing for Page Refreshes (It Breaks Form Fields)
|
27
|
+
|
28
|
+
We don't recommend using [Turbo's Morphing](https://turbo.hotwired.dev/handbook/page_refreshes) for refreshing whole screens, especially not when the screen contains form fields. That's because Turbo's Morphing works by comparing and modifying the DOM in a way that breaks JavaScript-created elements. Bullet Train's field partials, however, use third-party librairies, like those created by our `super_select`, our `date_field`, and even the Trix rich-text editor, which create their own elements via JavaScript. Use Turbo's Morphing sparingly.
|
29
|
+
|
30
|
+
### Reactive Page Updates with CableReady::Updatable
|
31
|
+
|
32
|
+
Bullet Train's answer to reactive page updates is a lightweight library called [CableReady::Updatable](https://cableready.stimulusreflex.com/guide/updatable.html). Rather than refreshing whole pages, it defines specific page regions that update themselves on model changes, across browser sessions. Look throughout your scaffolded `index` and `show` views for `cable_ready_updates_for` and in your models for the `enable_cable_ready_updates: true` option on `has_many` associations. By default, forms are not defined as updatable regions using CableReady::Updatable, for the same reasons explained above.
|
33
|
+
|
34
|
+
### Dynamic Forms
|
35
|
+
|
36
|
+
For creating dynamically-updated forms, Bullet Train introduces two powerful new patterns: the [_Dependent Fields Pattern_ and the _Dependent Fields Frame_](/docs/field-partials/dynamic-forms-dependent-fields.md). If you use the `address_field` partial, you'll see the pattern in action: changing the country will update the state and zip code fields. You can use these patterns to create complex, dynamically-updated forms.
|
37
|
+
|
38
|
+
## Avoid Scripts in the Body
|
39
|
+
|
40
|
+
If you experience slow Turbo interactions, check for script tags in the body of your pages. Following [Turbo's documentation](https://turbo.hotwired.dev/handbook/building#working-with-script-elements):
|
41
|
+
|
42
|
+
❌ Don't place scripts in the body:
|
43
|
+
|
44
|
+
```html
|
45
|
+
<body>
|
46
|
+
<script src="third-party-tracker.js"></script>
|
47
|
+
</body>
|
48
|
+
```
|
49
|
+
|
50
|
+
✅ Instead, place them in the head with the `defer` attribute:
|
51
|
+
|
52
|
+
```html
|
53
|
+
<head>
|
54
|
+
<script src="third-party-tracker.js" defer></script>
|
55
|
+
</head>
|
56
|
+
```
|
data/docs/oauth.md
CHANGED
@@ -10,6 +10,8 @@ rails generate super_scaffold:oauth_provider
|
|
10
10
|
## Stripe Connect Example
|
11
11
|
Similar to the "Tangible Things" template for [Super Scaffolding CRUD workflows](/docs/super-scaffolding.md), Bullet Train includes a Stripe Connect integration by default and this example also serves as a template for Super Scaffolding to implement other providers you might want to add.
|
12
12
|
|
13
|
+
See [the docs about Stripe Connect](/docs/stripe-connect.md) for more info about setting up Stripe Connect in your app.
|
14
|
+
|
13
15
|
## Dealing with Last Mile Issues
|
14
16
|
|
15
17
|
You should be able to add many third-party OAuth providers with Super Scaffolding without any manual effort. However, there are sometimes quirks from provider to provider, so if you need to dig in to get things working on a specific provider, here are the files you'll probably be looking for:
|
@@ -0,0 +1,77 @@
|
|
1
|
+
# Stripe Connect
|
2
|
+
|
3
|
+
Bullet Train comes with a Stripe Connect integration ready to go. All you have to do is configure your Stripe account and set
|
4
|
+
a couple of ENV variables.
|
5
|
+
|
6
|
+
Once Stripe Connect is configured it allows for two things:
|
7
|
+
|
8
|
+
1. Users can connect their Stripe account as a form of sign in to your app. A "Sign in with Stripe" button will appear on the
|
9
|
+
login form. Users who have already signed up with email address and password will continue to be able to use those credentials,
|
10
|
+
but they'll also be able to connect a Stripe account for auth.
|
11
|
+
2. Teams can add a new Stripe Installation for marketplace type sales. (It's up to you to build out the marketplace and the sales process
|
12
|
+
we just make it easy to allow your users to connect their Stripe accounts.)
|
13
|
+
|
14
|
+
## Initial Setup
|
15
|
+
|
16
|
+
In order to get things working you'll need to configure the OAuth settings under "Settings > Connect" in your Stripe account.
|
17
|
+
|
18
|
+
* [OAuth Settings for test mode](https://dashboard.stripe.com/test/settings/connect/onboarding-options/oauth)
|
19
|
+
* [OAuth Settings for production](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth)
|
20
|
+
|
21
|
+
### Set the `STRIPE_CLIENT_ID` ENV var
|
22
|
+
|
23
|
+
From the OAuth Settings page you need to grab the "Test client ID" and/or "Live client ID" depending on whether you're configuring test mode
|
24
|
+
or live mode. Copy that value and set is as the `STRIPE_CLIENT_ID` ENV var in your environment.
|
25
|
+
|
26
|
+
### Enable OAuth
|
27
|
+
|
28
|
+
On the Stripe OAuth Settings page make sure that the switch for "Enable OAuth"/"OAuth for Stripe Dashboard accounts" is turned on.
|
29
|
+
|
30
|
+
### Set your redirect URL
|
31
|
+
|
32
|
+
In the "Redirects" section of the OAuth Settings click "+ Add URI" and set the callback URL. The path for the callback is
|
33
|
+
`/users/auth/stripe_connect/callback` and the host will vary depending on your environment and how you access it.
|
34
|
+
|
35
|
+
For test mode on localhost you can usually set the redirect URL to be:
|
36
|
+
|
37
|
+
```
|
38
|
+
http://localhost:3000/users/auth/stripe_connect/callback
|
39
|
+
```
|
40
|
+
|
41
|
+
For live mode it will need to be an `https` URL and it should point to your production environment.
|
42
|
+
|
43
|
+
```
|
44
|
+
https://your-apps-fancy-domain-goes-here/users/auth/stripe_connect/callback
|
45
|
+
```
|
46
|
+
|
47
|
+
### Set the `STRIPE_SECRET_KEY` ENV var
|
48
|
+
|
49
|
+
Finally you need to set the secret key. These can be found under "Developers > API Keys"
|
50
|
+
|
51
|
+
* [API Keys for test mode](https://dashboard.stripe.com/test/apikeys)
|
52
|
+
* [API Keys for production](https://dashboard.stripe.com/apikeys)
|
53
|
+
|
54
|
+
Copy the "Secret key" value and set is as the `STRIPE_SECRET_KEY` ENV var in the appropriate environment.
|
55
|
+
|
56
|
+
## Using Stripe Connect
|
57
|
+
|
58
|
+
Once you've configured your Stripe account and set the necessary ENV vars you'll need to restart your server.
|
59
|
+
|
60
|
+
### Create a second Stripe account for testing.
|
61
|
+
|
62
|
+
The Stripe account that you configured above is kind of a "host account" that "owns" the connections between your app and _other_ Stripe accounts
|
63
|
+
(Stripe accounts that are not your app). So in order to test connections you'll need a second Stripe account.
|
64
|
+
|
65
|
+
### Using Stripe Connect for sign in
|
66
|
+
|
67
|
+
Under the user menu in your Bullet Train app, go to the "Account Details" link (`/account/users/XXX/edit`).
|
68
|
+
|
69
|
+
There you should see a section for "Connected Stripe Accounts".
|
70
|
+
|
71
|
+
Click the "Connect Stripe Account" button and then follow the prompts. At the end of the process you should be redirected back to your
|
72
|
+
"Account Details" screen and you should see that you now have a Stripe account connected.
|
73
|
+
|
74
|
+
### Using Stripe Connect for marketplace sales
|
75
|
+
|
76
|
+
In the top menu you should now see an "Integrations" menu with a "Stripe Installations" menu item. When you go there you'll be able to
|
77
|
+
add a new Stripe Installation. The process is pretty much the same as connecting a new account for auth purposes.
|
data/lib/bullet_train/version.rb
CHANGED
metadata
CHANGED
@@ -1,13 +1,13 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: bullet_train
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.14.
|
4
|
+
version: 1.14.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Andrew Culver
|
8
8
|
bindir: bin
|
9
9
|
cert_chain: []
|
10
|
-
date: 2025-01-
|
10
|
+
date: 2025-01-27 00:00:00.000000000 Z
|
11
11
|
dependencies:
|
12
12
|
- !ruby/object:Gem::Dependency
|
13
13
|
name: standard
|
@@ -760,6 +760,7 @@ files:
|
|
760
760
|
- docs/overriding.md
|
761
761
|
- docs/permissions.md
|
762
762
|
- docs/seeds.md
|
763
|
+
- docs/stripe-connect.md
|
763
764
|
- docs/stylesheets.md
|
764
765
|
- docs/super-scaffolding.md
|
765
766
|
- docs/super-scaffolding/delegated-types.md
|