bullet_train 1.0.89 → 1.0.93

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10ae054a169a950cefe74b26d215e6013289aa2c9225f8265d928f8e21f4dede
-  data.tar.gz: f95021c8db87c1e6eced4941ccd496ecca72f4eeae0cb5fb72b5440c9118b82b
+  metadata.gz: 0fd0ed98cb437a6a91f7289ee15c050bbf07ad8321c2eb5cd62e6095bc58b67e
+  data.tar.gz: 7f380b03457f3a8f68d87451a731c7dc0c3c67fbfe1de2ac9bc0984f5a6e5075
 SHA512:
-  metadata.gz: ef9099aab56abe73bedd674e99d4198a550077442eaa42a37a37847c13c27ee4c61e8607969806020a42e9cd1674afcbbae9911fc545a403fb13505e6a6ad57c
-  data.tar.gz: 59b9907db1197b7157503eb51000779a0cdbf1b137defae7550997fa8305b50fd739e51e40217c0a9bd10f39e522b6a3df0c85778f520340d1331e598d31ca25
+  metadata.gz: b56c26291a63a669de8526e03b60473ea44589f562efb85ba0e100c8267b9d8b1e6b728acb1fcfe71b97a0f9789d5e24451b04a2609ab9e7f9941970195825d9
+  data.tar.gz: 95a757e8187c5b0d0f0108794796b1b73a2d8f8b3edccf20c9040b6e6308ba594f650b73cb5576f41080dcd9f9bc34a154a2de8b9bbd106858a81bd347cfa59d

data/app/models/concerns/memberships/base.rb

@@ -13,7 +13,6 @@ module Memberships::Base
 
     has_many :scaffolding_completely_concrete_tangible_things_assignments, class_name: "Scaffolding::CompletelyConcrete::TangibleThings::Assignment", dependent: :destroy
     has_many :scaffolding_completely_concrete_tangible_things, through: :scaffolding_completely_concrete_tangible_things_assignments, source: :tangible_thing
-    has_many :reassignments_scaffolding_completely_concrete_tangible_things_reassignments, class_name: "Memberships::Reassignments::ScaffoldingCompletelyConcreteTangibleThingsReassignment", dependent: :destroy, foreign_key: :membership_id
 
     has_many :scaffolding_absolutely_abstract_creative_concepts_collaborators, class_name: "Scaffolding::AbsolutelyAbstract::CreativeConcepts::Collaborator", dependent: :destroy
 

data/app/views/layouts/docs.html.erb

@@ -119,6 +119,12 @@
                   <% end %>
                 <% end %>
 
+                <%= render 'account/shared/menu/item', url: '/docs/action-models', label: 'Action Models' do |p| %>
+                  <% p.content_for :icon do %>
+                    <i class="fal fa-bars-progress ti ti-target"></i>
+                  <% end %>
+                <% end %>
+
                 <%= render 'account/shared/menu/item', url: '/docs/seeds', label: 'Database Seeds' do |p| %>
                   <% p.content_for :icon do %>
                     <i class="fal fa-seedling ti ti-server"></i>

data/docs/action-models.md

@@ -0,0 +1,148 @@
+# Action Models
+
+Action Models make it easy to scaffold and implement user-facing custom actions in your Bullet Train application and API in a RESTful way. Action Models are perfect for situations where you want one or more of the following:
+
+ - Bulk actions for a model where users can select one or more objects as targets.
+ - Long-running background tasks where you want to keep users updated on their progress in the UI or notify then after completion.
+ - Actions that have one or more configuration options available.
+ - Tasks that can be configured now but scheduled to take place later.
+ - Actions where you want to keep an in-app record of when it happened and who initiated the action.
+ - Tasks that one team member can initiate, but a team member with elevated privileges has to approve.
+
+Examples of real-world features that can be easily implemented using Action Models include:
+
+ - A project manager can archive multiple projects at once.
+ - A customer service agent can refund multiple payments at once and provide a reason.
+ - A user can see progress updates while their 100,000 row CSV file is imported.
+ - A marketing manager can publish a blog post now or schedule it for publication tomorrow at 9 AM.
+ - A contributor can propose a content template change that will be applied after review and approval.
+
+Importantly, Action Models aren't a special new layer in your application or a special section of your code base. Instead, they're just regular models, with corresponding scaffolded views and controllers, that exist alongside the rest of your domain model. They leverage Bullet Train's existing strengths around domain modeling and code generation with Super Scaffolding.
+
+They're also super simple and very DRY. Consider the following example, assuming the process of archiving each project is very complicated and takes a lot of time:
+
+```ruby
+class Projects::ArchiveAction < ApplicationRecord
+  include Actions::TargetsMany
+  include Actions::ProcessesAsync
+  include Actions::HasProgress
+  include Actions::CleansUp
+
+  belongs_to :team
+
+  def valid_targets
+    team.projects
+  end
+
+  def perform_on_target(project)
+    project.archive
+  end
+end
+```
+
+## Installation
+
+### 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.
+
+### 2. Install the Package
+
+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-action_models"
+end
+```
+
+Don't forget to run `bundle install` and `rails restart`.
+
+## Super Scaffolding Commands
+
+You can get detailed information about using Super Scaffolding to generate different types of Action Models like so:
+
+```
+bin/super-scaffold action-model:targets-many
+bin/super-scaffold action-model:targets-one
+bin/super-scaffold action-model:targets-one-parent
+```
+
+## Basic Example
+
+### 1. Generate and scaffold an example `Project` model.
+
+```
+rails g model Project team:references name:string
+bin/super-scaffold crud Project Team name:text_field
+```
+
+### 2. Generate and scaffold an archive action for projects.
+
+```
+bin/super-scaffold action-model:targets-many Archive Project Team
+```
+
+### 3. Implement the action logic.
+
+Open `app/models/projects/archive_action.rb` and update the implementation of this method:
+
+```ruby
+def perform_on_target(project)
+  project.archive
+end
+```
+
+You're done!
+
+## Additional Examples
+
+### Add configuration options to an action.
+
+Because Action Models are just regular models, you can add new fields to them with Super Scaffolding the same as any other model. This is an incredible strength, because it means the configuration options for your Action Models can leverage the entire suite of form field types available in Bullet Train, and maintaining the presentation of those options to users is like maintaining any other model form in your application.
+
+For example:
+
+```
+rails g migration add notify_users_to_projects_archive_actions notify_users:boolean
+# side quest: update the generated migration with `default: false` on the new boolean field.
+bin/super-scaffold crud-field Projects::ArchiveAction notify_users:boolean
+```
+
+Now users will be prompted with that option when they perform this action, and you can update your logic to take action based on it, or at least pass on the information to another method that takes action based on it:
+
+```ruby
+def perform_on_target(project)
+  project.archive(send_notification: notify_users)
+end
+```
+
+## Action Types
+
+Action Models can be generated in three flavors:
+
+ - `action-model:targets-many`
+ - `action-model:targets-one`
+ - `action-model:targets-one-parent`
+
+### Targets Many
+
+Action Models that _can_ target many objects are by far the most common, but it's important to understand that they're not only presented to users as bulk actions. Instead, by default, they're presented to users as an action available for each individual object, but they're also presented as a bulk action when users have selected multiple objects.
+
+"Targets many" actions live at the same level in the domain model (and belong to the same parent) as the model they target. (If this doesn't make immediate sense, just consider that it would be impossible for instances of these actions to live under multiple targets at the same time.)
+
+### Targets One
+
+Sometimes you have an action that will only ever target one object at a time. In this case, they're generated a little differently and live under (and belong to) the model they target.
+
+When deciding between "targets many" and "targets one", our recommendation is that you only use "targets one" for actions that you know for certain could never make sense targeting more than one object at the same time. For example, if you're creating a send action for an email that includes configuration options and scheduling details, you may be reasonably confident that you never need users to be able to schedule two different emails at the same time with the same settings. That would be a good candidate for a "targets one" action.
+
+### Targets One Parent
+
+This final type of action is available for things like importers that don't necessarily target specific existing objects by ID, but instead create many new or affect many existing objects under a specific parent based on the configuration of the action (like an attached CSV file.) These objects don't "target many" per se, but they live at the same level (and belong to the same parent) as the models they end up creating or affecting.
+
+## Frequently Asked Questions
+
+### Do Action Models have to be persisted to the database?
+
+No. Action Models extend from `ApplicationRecord` by default, but if you're not using features that depend on persistence to the database, you can make them `include ActiveModel::API` instead. That said, it's probably not worth the trouble. As an alternative, consider just including `Actions::CleansUp` in your action to ensure it removes itself from the database after completion.

data/docs/index.md

@@ -16,6 +16,7 @@
 
 ## Developer Tools
  - [Super Scaffolding](/docs/super-scaffolding.md)
+ - [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>

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.0.89"
+  VERSION = "1.0.93"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.0.89
+  version: 1.0.93
 platform: ruby
 authors:
 - Andrew Culver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-01 00:00:00.000000000 Z
+date: 2022-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standard
@@ -607,6 +607,7 @@ files:
 - db/migrate/20210816072508_add_locale_to_teams.rb
 - db/migrate/20211020200855_add_doorkeeper_application_to_memberships.rb
 - db/migrate/20211027002944_add_doorkeeper_application_to_users.rb
+- docs/action-models.md
 - docs/api.md
 - docs/authentication.md
 - docs/billing/stripe.md