bullet_train 1.2.27 → 1.3.0

data/config/locales/en/base.yml

@@ -46,6 +46,8 @@ en:
     typing_search: Start typing search...
     sidebar: Sidebar
     creator: Bullet Train, Inc.
+    time_ago: "%{time} ago"
+    never: Never
     buttons:
       other: Other
       debug: Debug
@@ -80,6 +82,13 @@ en:
       timestamp_unavailable: Never
       date: '%m/%d/%Y'
       date_and_time: '%m/%d/%Y %l:%M %p'
+    file_fields:
+      download: Download File
+      download_current: Download Current Document
+      remove: Remove Current Document
+      upload: Upload New Document
+    bulk_select:
+      all: All
 
   menus:
     main:

data/config/locales/en/memberships.en.yml

@@ -34,6 +34,9 @@ en:
       user_profile_photo_id:
         name: &user_profile_photo_id Profile Photo
         label: *user_profile_photo_id
+      user_profile_photo:
+        name: &user_profile_photo Profile Photo
+        label: *user_profile_photo
       role_ids:
         name: &roles Special Privileges
         label: *roles

data/config/locales/en/users.en.yml

@@ -56,6 +56,10 @@ en:
         _: &profile_photo_id Profile Photo
         label: *profile_photo_id
         heading: *profile_photo_id
+      profile_photo:
+        _: &profile_photo Profile Photo
+        label: *profile_photo
+        heading: *profile_photo
       current_password:
         label: Current Password
       password:
@@ -116,6 +120,7 @@ en:
         last_name: *last_name
         email: *email
         profile_photo_id: *profile_photo_id
+        profile_photo: *profile_photo
         time_zone: *time_zone
         locale: *locale
         # 🚅 super scaffolding will insert new activerecord attributes above this line.

data/docs/application-hash.md

@@ -0,0 +1,25 @@
+## `ApplicationHash`
+[Webhooks::Outgoing::EventType](https://github.com/bullet-train-co/bullet_train-core/blob/main/bullet_train-outgoing_webhooks/app/models/webhooks/outgoing/event_type.rb) inherits a class called [ApplicationHash](https://github.com/bullet-train-co/bullet_train/blob/main/app/models/application_hash.rb) which includes helpful methods from [ActiveHash](https://github.com/active-hash/active_hash).
+
+ActiveHash itself is a simple base class that allows you to use a Ruby hash as a readonly datasource for an ActiveRecord-like model.
+
+For webhooks in Bullet Train, this means that we can handle `Webhooks::Outgoing::EventType` similar to an ActiveRecord model even though it doesn't have a table in the database like models usually do, making it easier to order and utilize data like this in the context of a Rails application.
+
+```
+> rails c
+irb(main):001:0> Scaffolding::AbsolutelyAbstract::CreativeConcept.all.class
+=> Scaffolding::AbsolutelyAbstract::CreativeConcept::ActiveRecord_Relation
+irb(main):002:0> Webhooks::Outgoing::EventType.all.class
+=> ActiveHash::Relation
+
+# An example from the EndpointSupport module
+def event_types
+  event_type_ids.map { |id| Webhooks::Outgoing::EventType.find(id) }
+end
+```
+
+Now that we can use `Webhooks::Outgoing::EventType` like an ActiveRecord model, we can use methods like `find`, as well as declare associations like `belongs_to` for any models that inherit `ApplicationHash`.
+
+Also, because the event types are declared in a [YAML file](https://github.com/bullet-train-co/bullet_train/blob/main/config/models/webhooks/outgoing/event_types.yml), all you have to do is add attributes there to add changes to your ApplicationHash data.
+
+Refer to the Active Hash [repository](https://github.com/active-hash/active_hash) for more details.

data/docs/billing/stripe.md

@@ -14,7 +14,7 @@ First, [purchase Bullet Train Billing for Stripe](https://buy.stripe.com/28o8zg4
 
 You'll need to specify both Ruby gems in your `Gemfile`, since we have to specify a private source for both:
 
-```
+```ruby
 source "https://YOUR_TOKEN_HERE@gem.fury.io/bullettrain" do
   gem "bullet_train-billing"
   gem "bullet_train-billing-stripe"
@@ -64,7 +64,7 @@ Bullet Train defines subscription plans and pricing options in `config/models/bi
 
 Edit `config/application.yml` and add your new Stripe secret key to the file:
 
-```
+```yaml
 STRIPE_SECRET_KEY: sk_0CJw2Iu5wwIKXUDdqphrt2zFZyOCH
 ```
 
@@ -103,7 +103,7 @@ Ensure you've completed the steps from [HTTP Tunneling with ngrok](/docs/tunneli
 
 After creating the webhook endpoint, click "reveal" under the heading "signing secret". Copy the `whsec_...` value into your `config/application.yml` like so:
 
-```
+```yaml
 STRIPE_WEBHOOKS_ENDPOINT_SECRET: whsec_vchvkw3hrLK7SmUiEenExipUcsCgahf9
 ```
 

data/docs/billing/usage.md

@@ -6,7 +6,7 @@ Bullet Train provides a holistic method for defining model-based usage limits in
 
 ### 1. Purchase Bullet Train Pro
 
-First, [purchase Bullet Train Pro](https://buy.stripe.com/aEU7vc4dBfHtfO89AV). Once you've completed this process, you'll be issued a private token for the Bullet Train Pro package server. The process is currently completed manually, so you may have to way a little to receive your keys.
+First, [purchase Bullet Train Pro](https://buy.stripe.com/aEU7vc4dBfHtfO89AV). Once you've completed this process, you'll be issued a private token for the Bullet Train Pro package server. The process is currently completed manually, so you may have to wait a little to receive your keys.
 
 ### 2. Install the Package
 
@@ -51,21 +51,21 @@ There are two concerns that need to be added to your application models.
 
 The first concern is `Billing::UsageSupport` and it allows tracking of usage of verbs on the models you want to support tracking usage on. It is recommended to add this capability to all models, so you can add this.
 
-```
+```ruby
 # app/models/application_record.rb
 
 class ApplicationRecord
-  include Billing::Usage
+  include Billing::UsageSupport
 end
 ```
 
-The second concern is `Billing::HasTrackers` and it allows any model to hold the usage tracking. This is usually done on the `Team` model.
+The second concern is `Billing::Usage::HasTrackers` and it allows any model to hold the usage tracking. This is usually done on the `Team` model.
 
-```
+```ruby
 # app/models/team.rb
 
 class Team
-  include Billing::HasTrackers
+  include Billing::Usage::HasTrackers
 end
 ```
 
@@ -191,7 +191,7 @@ current_limits.exhausted?(Blogs::Post, :soft)
 
 If you want to present an error or warning to the user based on their usage, there themed alert partials that can be displayed in your views. These partials can be rendered via the path `shared/limits/error` and `shared/limits/warning` respectively.
 
-```ruby
+```erb
 <%= render "shared/limits/warning", model: model.class %>
 
 <%= render "shared/limits/error", action: :create, model: model.class, count: 1, cancel_path: cancel_path %>

data/docs/field-partials/buttons.md

@@ -4,13 +4,13 @@
 
 If you invoke the field partial in `app/views/account/some_class_name/_form.html.erb` like so:
 
-```
+```erb
 <%= render 'shared/fields/buttons', form: form, method: :enabled %>
 ```
 
 You can define the available buttons in `config/locales/en/some_class_name.en.yml` like so:
 
-```
+```yaml
 en:
   some_class_name:
     fields:
@@ -27,7 +27,7 @@ en:
 
 You can generate the available buttons using a collection of database objects by passing the `options` option like so:
 
-```
+```erb
 <%= render 'shared/fields/buttons', form: form, method: :category_id,
   options: Category.all.map { |category| [category.id, category.label_string] } %>
 ```
@@ -36,7 +36,7 @@ You can generate the available buttons using a collection of database objects by
 
 You can allow multiple buttons to be selected using the `multiple` option, like so:
 
-```
+```erb
 <%= render 'shared/fields/buttons', form: form, method: :category_ids,
   options: Category.all.map { |category| [category.id, category.label_string] }, multiple: true %>
 ```

data/docs/field-partials/date-related-fields.md

@@ -0,0 +1,13 @@
+# Customizing `date_field` and `date_and_time_field` Field Partials
+
+You can customize the format in which your `Date` and `DateTime` fields appear by passing the `format` option to your render calls. You can also use `date_format` and `time_format` to accomplish the same thing.
+
+```erb
+<%# For Date objects %>
+<%= render 'shared/attributes/date', attribute: :date_test, format: "%m/%d" %>
+<%= render 'shared/attributes/date', attribute: :date_test, date_format: "%m/%d" %>
+
+<%# For DateTime objects %>
+<%= render 'shared/attributes/date_and_time', attribute: :date_time_test, format: "%m/%d %I %p" %>
+<%= render 'shared/attributes/date_and_time', attribute: :date_time_test, date_format: "%m/%d", time_format: "%I %p" %>
+```

data/docs/field-partials/file-field.md

@@ -8,8 +8,7 @@ In addition, Bullet Train has integrated the direct-uploads feature of Active St
 
 ## Example
 
-Add a 'document' file as an attachment to a `Post` model:
-
+The following steps illustrate how to add a `document` file attachment to a `Post` model.
 Add the following to `app/models/post.rb`:
 
 ```ruby

data/docs/field-partials/super-select.md

@@ -1,6 +1,8 @@
+Note: before you attempt to manually wire up a `super_select` field, note that Super Scaffolding will automatically do that for your models. See [Super Scoffolding](/docs/super-scaffolding.md) docs, section 4, for an example. And make sure Super Scoffolding doesn't automatically do what you're trying to do.
+
 # Examples for the `super_select` Field Partial
 
-The `super_select` partial provides a wonderful default UI (in contrast to the vanilla browser experience for this, which is horrible) with optional search and multi-select functionality out-of-the-box. It invokes the [Select2][select2] library to provide you these features.
+The `super_select` partial provides a wonderful default UI (in contrast to the vanilla browser experience for select boxes, which is horrible) with optional search and multi-select functionality out-of-the-box. It invokes the [Select2][select2] library to provide you these features.
 
 ## Define Available Buttons via Localization Yaml
 
@@ -28,7 +30,9 @@ You can define the available options in `config/locales/en/some_class_name.en.ym
 Although it's recommended to define any static list of choices in the localization Yaml file (so your application remains easy to translate into other languages), you can also specify these choices using the `choices` option from the underlying select form field helper:
 
 <pre><code><%= render 'shared/fields/super_select', form: form, method: :response_behavior,
-  choices: [['Immediately', 'immediate'], ['After a 10 minute delay', 'after_10_minutes'] ["Doesn't respond", 'disabled']] %></code></pre>
+  choices: [['Immediately', 'immediate'],
+  ['After a 10 minute delay', 'after_10_minutes'],
+  ["Doesn't respond", 'disabled']] %></code></pre>
 
 ## Generate Choices Programmatically
 
@@ -88,7 +92,7 @@ All events dispatched from the `super_select` partial are [Select2's jQuery even
 | select2:clearing    | $select2:clearing    |
 | select2:clear       | $select2:clear       |
 
-For example, catching the `$change` events in a parent `dependent-form-fields` Stimulus controller with a single `updateDependentFields` method would look like this:
+For example, the view template for catching the `$change` events in a parent `dependent-form-fields` using a Stimulus controller with a single `updateDependentFields` method would look like this:
 
 <pre><code>&lt;div data-controller="dependent-form-fields"&gt;
   &lt;div data-action="$change->dependent-form-fields#updateDependentFields"&gt;
@@ -124,4 +128,19 @@ export default class extends Controller {
 </code></pre>
 
 [select2]: https://select2.org
-[select2_events]: https://select2.org/programmatic-control/events
+[select2_events]: https://select2.org/programmatic-control/events
+
+## Options
+Select2 has different options available which you can check [here](https://select2.org/configuration/options-api).
+
+You can pass these options to the super select partial like so:
+```erb
+<%= render 'shared/fields/super_select', method: :project,
+  select2_options: {
+    allowClear: true,
+    placeholder: 'Your Custom Placeholder'
+  }
+%>
+```
+
+*Passing options like this doesn't allow JS callbacks or functions to be used, so you must extend the Stimulus controller and add options to the `optionsOverride` getter if you want to do so.

data/docs/field-partials.md

@@ -23,13 +23,13 @@ Each field partial can optionally include whichever of the following are require
 ## Basic Usage
 The form field partials are designed to be a 1:1 match for [the native Rails form field helpers](https://guides.rubyonrails.org/form_helpers.html) developers are already used to using. For example, consider the following basic Rails form field helper invocation:
 
-```
+```erb
 <%= form.text_field :text_field_value, autofocus: true %>
 ```
 
 Using the field partials, the same field would be implemented as follows:
 
-```
+```erb
 <%= render 'shared/fields/text_field', form: form, method: :text_field_value, options: {autofocus: true} %>
 ```
 
@@ -52,7 +52,7 @@ Because Bullet Train field partials have more responsibilities than the underlyi
 
 For example, to suppress a label on any field, we can use the `hide_label` option like so:
 
-```
+```erb
 <%= render 'shared/fields/text_field', form: form, method: :text_field_value, other_options: {hide_label: true} %>
 ```
 
@@ -67,7 +67,7 @@ For example, to suppress a label on any field, we can use the `hide_label` optio
 ## Reducing Repetition
 When you're including multiple fields, you can DRY up redundant settings (e.g. `form: form`) like so:
 
-```
+```erb
 <% with_field_settings form: form do %>
   <%= render 'shared/fields/text_field', method: :text_field_value, options: {autofocus: true} %>
   <%= render 'shared/fields/buttons', method: :button_value %>
@@ -76,34 +76,37 @@ When you're including multiple fields, you can DRY up redundant settings (e.g. `
 ```
 
 ## Field partials that integrate with third-party service providers
- - `cloudinary` makes it trivial to upload photos and images to [Cloudinary](https://cloudinary.com) and store their resulting Cloudinary ID as an attribute of the model backing the form. To enable this field partial, sign up for Cloudinary and copy the "Cloudinary URL" they provide you with into your `config/application.yml` as `CLOUDINARY_URL`. If you use our [Heroku app.json](https://github.com/bullet-train-co/bullet_train/blob/main/app.json) to provision your production environment, this will happen in that environment automatically.
+ - `cloudinary_image` makes it trivial to upload photos and videos to [Cloudinary](https://cloudinary.com) and store their resulting Cloudinary ID as an attribute of the model backing the form. To enable this field partial, sign up for Cloudinary and copy the "Cloudinary URL" they provide you with into your `config/application.yml` as `CLOUDINARY_URL`. If you use our [Heroku app.json](https://github.com/bullet-train-co/bullet_train/blob/main/app.json) to provision your production environment, this will happen in that environment automatically.
 
 ## Yaml Configuration
 The localization Yaml file (where you configure label and option values for a field) is automatically generated when you run Super Scaffolding for a model. If you haven't done this yet, the localization Yaml file for `Scaffolding::CompletelyConcrete::TangibleThing` serves as a good example. Under `en.scaffolding/completely_concrete/tangible_things.fields` you'll see definitions like this:
 
-<pre><code>text_field_value:
+```yaml
+text_field_value:
   name: &text_field_value Text Field Value
   label: *text_field_value
   heading: *text_field_value
-</code></pre>
+```
 
 This might look redundant at first glance, as you can see that by default the same label ("Text Field Value") is being used for both the form field label (`label`) and the heading (`heading`) of the show view and table view. It's also used when the field is referred to in a validation error message. However, having these three values defined separately gives us the flexibility of defining much more user-friendly labels in the context of a form field. In my own applications, I'll frequently configure these form field labels to be much more verbose questions (in an attempt to improve the UX), but still use the shorter label as a column header on the table view and the show view:
 
-<pre><code>text_field_value:
+```yaml
+text_field_value:
   name: &text_field_value Text Field Value
   label: "What should the value of this text field be?"
   heading: *text_field_value
-</code></pre>
+```
 
 You can also configure some placeholder text (displayed in the field when in an empty state) or some inline help text (to be presented to users under the form field) like so:
 
-<pre><code>text_field_value:
+```yaml
+text_field_value:
   name: &text_field_value Text Field Value
   label: "What should the value of this text field be?"
   heading: *text_field_value
   placeholder: "Type your response here"
   help: "The value can be anything you want it to be!"
-</code></pre>
+```
 
 Certain form field partials like `buttons` and `super_select` can also have their selectable options configured in this Yaml file. See their respective documentation for details, as usage varies slightly.
 
@@ -136,7 +139,17 @@ Set the data type to `jsonb` whenever passing the `multiple` option to a new att
 > bin/super-scaffold crud Project Team multiple_buttons:buttons{multiple}
 ```
 
+## Formating `date` and `date_and_time`
+After Super Scaffolding a `date` or `date_and_time` field, you can pass a format for the object like so:
+
+```
+<%= render 'shared/attributes/date', attribute: date_object, format: :short %>
+```
+
+Please refer to the [Ruby on Rails documentation](https://guides.rubyonrails.org/i18n.html#adding-date-time-formats) for more information.
+
 ## Additional Field Partials Documentation
  - [`buttons`](/docs/field-partials/buttons.md)
  - [`super_select`](/docs/field-partials/super-select.md)
  - [`file_field`](/docs/field-partials/file-field.md)
+ - [`date_field` and `date_and_time_field`](/docs/field-partials/date-related-fields.md)

data/docs/font-awesome-pro.md

@@ -45,6 +45,6 @@ No, that's not a typo. [That's the name of their company.](https://fortawesome.c
 
 In `app/javascript/application.js`, below `require("@icon/themify-icons/themify-icons.css")`, add:
 
-```
+```js
 require("@fortawesome/fontawesome-pro/css/all.css")
 ```

data/docs/index.md

@@ -5,13 +5,13 @@
 ## Introduction
  - [What is Bullet Train?](https://bullettrain.co) <i class="ti ti-new-window ml-2"></i>
  - [Getting Started](/docs/getting-started.md)
- - [Upgrading](/docs/upgrades.md)
+ - [Upgrades](/docs/upgrades.md)
 
 ## General Topics
  - [Domain Modeling](/docs/modeling.md)
  - [Dealing with Indirection](/docs/indirection.md)
  - [Overriding the Framework](/docs/overriding.md)
- - [Setting up a Tunnel](/docs/tunneling.md)
+ - [Tunneling](/docs/tunneling.md)
  - [JavaScript](/docs/javascript.md)
  - [Internationalization](/docs/i18n.md)
 
@@ -20,20 +20,21 @@
  - [Action Models](/docs/action-models.md)
  - [Database Seeds](/docs/seeds.md)
  - [Test Suite](/docs/testing.md)
- - [Point-and-Click Test Writing](https://github.com/bullet-train-co/magic_test) <i class="ti ti-new-window ml-2"></i>
+ - [Magic Test: Point-and-Click Test Writing](https://github.com/bullet-train-co/magic_test) <i class="ti ti-new-window ml-2"></i>
  - [Application Options](/docs/application-options.md)
 
 ## Accounts & Teams
  - [Authentication](/docs/authentication.md)
  - [Teams](/docs/teams.md)
- - [Roles and Permissions](/docs/permissions.md)
+ - [Roles & Permissions](/docs/permissions.md)
  - [Onboarding](/docs/onboarding.md)
  - [Namespacing](/docs/namespacing.md)
 
-## UI
+## User Interface
  - [Field Partials](/docs/field-partials.md)
  - [Theme Engine](/docs/themes.md)
- - [Partial Improvements](https://github.com/bullet-train-co/nice_partials) <i class="ti ti-new-window ml-2"></i>
+ - [Nice Partials](https://github.com/bullet-train-co/nice_partials) <i class="ti ti-new-window ml-2"></i>
+ - [Showcase](https://github.com/bullet-train-co/showcase) <i class="ti ti-new-window ml-2"></i>
 
 ## Billing
  - [Stripe](/docs/billing/stripe.md)
@@ -45,11 +46,11 @@
  - [OAuth Providers](/docs/oauth.md)
  - [Outgoing Webhooks](/docs/webhooks/outgoing.md)
  - [Incoming Webhooks](/docs/webhooks/incoming.md)
- 
+
 ## Add-Ons
  - [Font Awesome Pro](/docs/font-awesome-pro.md)
 
-## Production
+## Deployment
  - [Heroku](/docs/heroku.md)
  - [Desktop Applications](/docs/desktop.md)
 

data/docs/indirection.md

@@ -24,7 +24,7 @@ If you need to modify behavior in these framework-provided classes or modules, s
 
 Even in vanilla Rails development, when you're looking at a view file, the path you see passed to a `render` call isn't the actual file name of the partial that will be rendered. This is even more true in Bullet Train where certain partial paths are [magically served from theme gems](/docs/themes.md).
 
-`bin/resolve` makes it easy to figure out where where a partial is being served from:
+`bin/resolve` makes it easy to figure out where a partial is being served from:
 
 ```
 bin/resolve shared/box
@@ -79,6 +79,10 @@ You can see the full translation key of any string on the page by adding `?show_
 
 You can also log all the translation keys for anything being rendered to the console by adding `?log_locales=true` to the request URL. This can make it easier to copy and paste translation keys for strings that are rendered in non-selectable UI elements.
 
+#### Eject all Translations to your Application
+
+Run `rake bullet_train:themes[eject]` to put all of Bullet Train's core locales into your repository. Then you can sift through the files to keep the ones you want to customize, and remove the ones you don't need.
+
 #### Resolving Translation Keys with `bin/resolve`
 
 Once you have the full I18n translation key, you can use `bin/resolve` to figure out which package and file it's coming from. At that point, if you need to customize it, you can also use the `--eject` option to copy the framework for customization in your local application:

data/docs/overriding.md

@@ -10,7 +10,7 @@ When it comes to object-oriented classes, wholesale copying framework files into
 
 For this reason, common points of extension like framework-provided models and controllers actually exist as a kind of "stub" in the local repository, but include their base functionality from framework-provided concerns, like so:
 
-```
+```ruby
 class User < ApplicationRecord
   include Users::Base
 

data/docs/seeds.md

@@ -6,7 +6,7 @@ Bullet Train introduces a new, slightly different expectation for Rails seed dat
 
 This is different than the Rails default, [as evidenced by the Rails example](https://guides.rubyonrails.org/v6.1.1/active_record_migrations.html#migrations-and-seed-data) which uses `Product.create`:
 
-```
+```ruby
 5.times do |i|
   Product.create(name: "Product ##{i}", description: "A product.")
 end
@@ -16,7 +16,7 @@ end
 
 In Bullet Train applications, you would implement that same `db/seeds.rb` logic like so:
 
-```
+```ruby
 5.times do |i|
   Product.find_or_create_by(name: "Product ##{i}") do |product|
     # this only happens if on a `create`.
@@ -39,7 +39,7 @@ In some cases, you may have core seed data like roles that needs to exist in eve
 
 Then in `db/seeds.rb`, you can load all of the shared core seed data at the beginning of `db/seeds.rb` and then load the environment-specific seeds only when you've specified one of those environments.
 
-```
+```ruby
 load "#{Rails.root}/db/seeds/development.rb" if Rails.env.development?
 load "#{Rails.root}/db/seeds/test.rb" if Rails.env.test?
 ```