hot-glue 0.5.7 → 0.5.9.1

data/README.md

@@ -20,7 +20,7 @@ Hot Glue generates functionality that is quick and dirty. It lets you be crafty.
 * Automatically reads your models (make them, add relationships, **and** migrate your database before building your scaffolding!)
 * Excellent for CREATE-READ-UPDATE-DELETE (CRUD), lists with pagination
 * Great for prototyping, but you should learn Rails fundamentals first.
-* 'Packaged' with Devise, Kaminari, Rspec, FontAwesome (optional)
+* 'Packaged' with Devise, Kaminari, Rspec
 * Create system specs automatically along with the generated code.
 * Nest your routes model-by-model for built-in poor man's authentication.
 * Throw the scaffolding away when your app is ready to graduate to its next phase.
@@ -38,10 +38,10 @@ Other than the opinionated differences and additional features, Hot Glue produce
 
 # Get Hot Glue
 
-## [GET THE COURSE TODAY](https://jfbcodes.com/courses/hot-glue-in-depth-tutorial/?utm_source=github.com&utm_campaign=github_hot_glue_readme_page) **only $60 USD!**
+## [GET THE COURSE TODAY](https://school.jasonfleetwoodboldt.com/8188/?utm_source=github.com&utm_campaign=github_hot_glue_readme_page) **only $60 USD!**
 
 
-[![Hot Glue Course](https://user-images.githubusercontent.com/59002/189544503-6edbcd40-1728-4b13-ac9a-c7772ccb8284.jpg)](https://jfbcodes.com/courses/hot-glue-in-depth-tutorial/?utm_source=github.com&utm_campaign=github_hot_glue_readme_page)
+[![Hot Glue Course](https://user-images.githubusercontent.com/59002/189544503-6edbcd40-1728-4b13-ac9a-c7772ccb8284.jpg)](https://school.jasonfleetwoodboldt.com/8188?utm_source=github.com&utm_campaign=github_hot_glue_readme_page)
 
 ---
 ---
@@ -62,106 +62,59 @@ Instantly get a simple CRUD interface
 
 _If you are on Rails 6, see [LEGACY SETUP FOR RAILS 6](https://github.com/jasonfb/hot-glue/README2.md) and complete those steps FIRST._
 
+## The Super-Quick Setup
+
+https://jasonfleetwoodboldt.com/courses/stepping-up-rails/rails-quick-scripts/
+
+Copy & paste the whole code block from each section into your terminal. (Pick only ONE option for each section.)
+
+
+From section #1 (`rails new`), choose either (1) ImportMap Rails, (2) JSBundling, or (3) Shakapacker. 
+
+For Hot Glue, you will need:
+
+Section #1 is to create a new Rails app. (Or you can do that yourself.)
+
+Section #2 is to setup Rspec, FactoryBot, and Faker.
+
+Section #4 is optional but highly recommended.
+
+Section #5 is where you will pick a CSS Framework (Bootstrap, Tailwind, or none)
+
+Section #6 is for two support gems (Kaminari) for Hot Glue
 
-## 1. Rails 7 New App
+Section #7 is for Hot Glue itself
 
-To run Turbo (which Hot Glue requires), you must either (1) be running an ImportMap-Rails app, or (2) be running a Node-compiled app using any of JSBundling, Shakapacker, or its alternatives. 
+You will also need section #8 to setup Devise if you want authentication.
 
-For reference, see https://jasonfleetwoodboldt.com/courses/stepping-up-rails/rails-7-do-i-need-importmap-rails/
 
-Once you create the new Rails app, you can skip to the 'Super-Quick Setup' below.
+## Step-By-Step Setup
+
+### 1. RAILS NEW
+To understand the options for `rails new`, see [this post](https://jasonfleetwoodboldt.com/courses/rails-7-crash-course/rails-7-bootstrap/)
+
+It is important that you know what kind of app you are creating (Importmap, JSBundling, or Shakapacker) because there are specific differences in how you will work with them. (Hot Glue is compatible with all 3 paradigms, but if you don't take the time to understand the setup, you will be confused as to why things aren't working.)
+
+To run Turbo (which Hot Glue requires), you must either (1) be running an ImportMap-Rails app, or (2) be running a Node-compiled app using any of JSBundling, Shakapacker, or its alternatives.
 
 (1) To use ImportMap Rails, start with
-`rails new`
+`rails new MyGreatApp`
 
 (For full instructions to install Bootstrap with Importmap, check out [these instructions](https://jasonfleetwoodboldt.com/courses/stepping-up-rails/importmap-rails-with-bootstrap-sprockets-stimulus-and-turbo-long-tutorial/))
 
 (2) To use JSBundling, start with
-`rails new --javascript=jsbundling`
+`rails new MyGreatApp --javascript=esbuild`
 
 
 **If using JSBundling, make sure to use the new `./bin/dev` to start your server instead of the old `rails server` or else your Turbo interactions will not work correctly.**
 (If you want Bootstrap for a JSBundling app, install it following [these instructions](https://jasonfleetwoodboldt.com/courses/stepping-up-rails/rails-7-up-running-with-jsbundling-esbuild-stimulus-turbo-bootstrap-circleci/))
 
-(3) To use Shakapacker, start with `rails new --skip-javascript` and [see this post](https://jasonfleetwoodboldt.com/courses/react-heart-rails/rails-7-shakapacker-and-reactonrails-quick-setup-part-1/)
+(3) To use Shakapacker, start with `rails new MyGreatApp --skip-javascript` and [see this post](https://jasonfleetwoodboldt.com/courses/react-heart-rails/rails-7-shakapacker-and-reactonrails-quick-setup-part-1/)
 
 (For the old method of installing Bootstrap [see this post](https://jasonfleetwoodboldt.com/courses/stepping-up-rails/rails-7-bootstrap/))
 
 (Remember, for Rails 6 you must go through the [LEGACY SETUP FOR RAILS 6](https://github.com/jasonfb/hot-glue/blob/main/README2.md) before continuing.)
 
-If you doing the 'Super-Quick Setup', you can skip the additional blog posts linked above because the steps in them are covered in the shell script(s) below.
-
-## The Super-Quick Setup
-
-Be sure to do `git add .` and `git commit -m "initial commit"` after creating your new Rails 7 app.
-
-```
-bundle add rspec-rails factory_bot_rails ffaker --group "development, test" && 
-git add . && git commit -m "adds gems" && 
-rails generate rspec:install && 
-git add . && git commit -m "adds rspec" && 
-rm app/assets/stylesheets/application.css &&
-echo "" > app/assets/stylesheets/application.scss && 
-sed -i '' -e  's/# gem "sassc-rails"//g' Gemfile && sed -i '' -e 's/# Use Sass to process CSS//g' Gemfile && 
-bundle install && bundle add sassc-rails && git add . && git commit -m "adds sassc-rails" && 
-rm -rf test/ && git add . && git commit -m "removes minitest" && 
-bundle add hot-glue && git add . && git commit -m "adds hot-glue" && 
-rails generate hot_glue:install --layout=bootstrap && 
-git add . && git commit -m "hot glue setup" &&
-bundle add bootstrap &&
-echo "\n@import 'bootstrap';\n" >> app/assets/stylesheets/application.scss
-sed -i '' -e  's/# Rails.application.config.assets.precompile += %w( admin.js admin.css )/Rails.application.config.assets.precompile += %w( application.scss )/g' config/initializers/assets.rb &&
-sed -i '' -e 's/Rails.application.configure do/Rails.application.configure do\n  config.sass.inline_source_maps = true/g' config/environments/development.rb 
-git add . && git commit -m "bootstrap install" &&
-bundle add font_awesome5_rails && 
-echo "\n@import 'font_awesome5_webfont';\n" >> app/assets/stylesheets/application.scss
-git add . && git commit -m "adds fontawesome" &&  
-bundle add kaminari && 
-rails generate kaminari:views bootstrap4 && 
-git add . && git commit -m "adding kaminari and views" &&
-bundle add devise && bundle install && 
-git add . && git commit -m "adding devise gem" && 
-rails generate devise:install && 
-rails g devise:views && 
-sed -i '' -e  's/Rails.application.configure do/Rails.application.configure do\n  config.action_mailer.default_url_options = { host: "localhost", port: 3000 }/g' config/environments/development.rb && 
-sed -i '' -e  's/# root "articles#index"//g' config/routes.rb && 
-sed -i '' -e  's/Rails.application.routes.draw do/Rails.application.routes.draw do\n  root to: "welcome#index"/g' config/routes.rb && 
-git add . && git commit -m 'devise view fixes' &&
-rails generate controller Welcome &&
-sed -i '' -e 's/class WelcomeController < ApplicationController/class WelcomeController < ApplicationController\n  def index\n\n  end/g' app/controllers/welcome_controller.rb &&
-echo "hello world" > app/views/welcome/index.erb &&
-git add . && git commit -m "generates Welcome controller" &&
-sed -i '' -e 's/html: { method: :post }/html: { method: :post, 'data-turbo': false}/g' app/views/devise/confirmations/new.html.erb &&
-sed -i '' -e 's/ url: session_path(resource_name))/ url: session_path(resource_name), html: {"data-turbo": false})/g' app/views/devise/sessions/new.html.erb && 
-sed -i '' -e 's/ url: registration_path(resource_name))/ url: registration_path(resource_name), html: {"data-turbo": false})/g' app/views/devise/registrations/new.html.erb && 
-sed -i '' -e 's/, html: { method: :post })/, html: { method: :post, "data-turbo": false })/g' app/views/devise/passwords/new.html.erb && 
-git add . && git commit -m 'devise view fixes' &&
-rails generate model User name:string &&
-rails generate devise User && git add . && git commit -m "adds Users model with devise" && 
-&& ./bin/setup && rails db:migrate &&
-git add . && git commit -m "schema file"
-```
-
-
-For Importmap apps:
-```
-./bin/importmap pin "bootstrap@5.1.3" &&
-./bin/importmap pin "@popperjs/core@2.11.2" &&
-git add . && git commit -m "pinning boostrap and popper js for bootstrap"
-```
-
-For JSBundling & Shakapacker:
-```
-echo "\ncss: yarn build:css --watch\n" >> Procfile.dev &&
-yarn add @popperjs/core bootstrap bootstrap-icons sass &&
-sed -i '' -e 's/\/\/= link_directory ..\/stylesheets .css//g' app/assets/config/manifest.js &&
-sed -i '' -e 's/  "scripts": {/  "scripts": {\n    "build:css": "sass .\/app\/assets\/stylesheets\/application.scss:.\/app\/assets\/builds\/application.css --no-source-map --load-path=node_modules",/g' package.json &&
-yarn install &&
-git add . && git commit -m "adding bootstrap packages"
-```
-
-
-## Step-By-Step Setup
 
 ### 2. ADD RSPEC, FACTORY-BOT, AND FFAKER
 
@@ -180,9 +133,16 @@ end
 
 - Because you are not using Minitest, you can delete the `test/` folder at the root of your repository.
 
+### 3. CSS Bundling Rails (optional)
+
+```
+bundle add cssbundling-rails
+./bin/rails css:install:bootstrap
+```
 
 
-### 3. HOTGLUE INSTALLER
+
+### 4. HOTGLUE INSTALLER
 Add `gem 'hot-glue'` to your Gemfile & `bundle install`
 
 During in installation, you MUST supply a `--layout` flag.
@@ -212,29 +172,20 @@ default is `erb`. IMPORTANT: As of right now, HAML and SLIM are not currently su
 
 
 #### example installing ERB using Bootstrap layout:
-`rails generate hot_glue:install --markup=erb --layout=bootstrap`
+`./bin/rails generate hot_glue:install --markup=erb --layout=bootstrap`
 
 #### Example installing using Hot Glue layout and the 'like_mountain_view' (Gmail-inspired) theme:
 `rails generate hot_glue:install --markup=erb --layout=hotglue --theme=like_mountain_view`
 
 The Hot Glue installer did several things for you in this step. Examine the git diffs or see 'Hot Glue Installer Notes' below.
 
-
-### 4. Font-awesome (optional)
-
-I recommend
-https://github.com/tomkra/font_awesome5_rails
-or
-https://github.com/FortAwesome/font-awesome-sass
-
-
-### 5. Devise
+### 4. Devise
 (If you are on Rails 6, you must do ALL of the steps in the Legacy Setup steps. Be sure not to skip **Legacy Step #5** below)
 https://github.com/jasonfb/hot-glue/blob/main/README2.md
 
 You MUST run the installer FIRST or else you will put your app into a non-workable state:
 ```
-rails generate devise:install
+./bin/rails generate devise:install
 ```
 
 IMPORTANT: Follow the instructions the Devise installer gives you, *Except Step 3*, you can skip this step:
@@ -249,7 +200,7 @@ IMPORTANT: Follow the instructions the Devise installer gives you, *Except Step
 
 Be sure to create primary auth model with:
 
-`rails generate devise User name:string`
+`./bin/rails generate devise User name:string`
 
 Remember, you don't need to tell Devise that your User has an email, an encrypted password, a reset token, and a 'remember me' flag to let the user stay logged in.
 
@@ -257,21 +208,7 @@ Those features come by default with Devise, and you'll find the fields for them
 
 In this example above, you are creating all of those fields along with a simple 'name' (string) field for your User table.
 
-
-!!! Warning: as of 2022-09-19, Devise is still not compatible out-of-the-box with Rails Turbo.
-
-To fix this, run
-`rails generate devise:views`
-
-
-Then manually add `html: {'data-turbo' => "false"}` to all of the Devise forms. You will need to edit the following forms:
-`views/devise/sessions/new.html.erb`, `views/devise/registrations/edit.html.erb`, 
-`views/devise/registrations/new.html.erb`, and  
-
-Add the data-turbo false option in the html key of the form, shown in bold here: 
-
-form_for(resource, as: resource_name, **html: {'data-turbo' => "false"},** url: session_path(resource_name) ) do |f|
-
+Devise 4.9.0 is now fully compatible with Rails 7.
 
 #### Hot Glue Installer Notes 
 
@@ -367,7 +304,7 @@ Alternatively, you can define your own driver like so:
 TitleCase class name of the thing you want to build a scaffoling for.
 
 ```
-rails generate hot_glue:scaffold Thing
+./bin/rails generate hot_glue:scaffold Thing
 ```
 
 (note: Your `Thing` object must `belong_to` an authenticated `User` or alternatively you must create a Gd controller, see below.)
@@ -381,7 +318,7 @@ All options begin with two dashes (`--`) and a followed by an `=` and a value
 pass `--namespace=` as an option to denote a namespace to apply to the Rails path helpers
 
 
-`rails generate hot_glue:scaffold Thing --namespace=dashboard`
+`./bin/rails generate hot_glue:scaffold Thing --namespace=dashboard`
 
 This produces several views at `app/views/dashboard/things/` and a controller at`app/controllers/dashboard/things_controller.rb`
 
@@ -413,9 +350,9 @@ resources :invoices do
 end
 ```
 
-`rails generate hot_glue:scaffold Invoice`
+`./bin/rails generate hot_glue:scaffold Invoice`
 
-`rails generate hot_glue:scaffold Line --nested=invoice`
+`./bin/rails generate hot_glue:scaffold Line --nested=invoice`
 
 
 Remember, nested should match how the hierarchy of nesting is in your `routes.rb` file. (Which Hot Glue does not create or edit for you.)
@@ -437,11 +374,11 @@ end
 
 _For multi-level nesting use slashes to separate your levels of nesting._
 
-`rails generate hot_glue:scaffold Invoice`
+`./bin/rails generate hot_glue:scaffold Invoice`
 
-`rails generate hot_glue:scaffold Line --nested=invoice`
+`./bin/rails generate hot_glue:scaffold Line --nested=invoice`
 
-`rails generate hot_glue:scaffold Charge --nested=invoice/line`
+`./bin/rails generate hot_glue:scaffold Charge --nested=invoice/line`
 
 
 
@@ -483,8 +420,8 @@ end
 Even though we have two routes pointed to **invoices**, both will go to the same controller (`app/controllers/admin/invoices_controller.rb`)
 
 ```
-rails generate hot_glue:scaffold User --namespace=admin --gd
-rails generate hot_glue:scaffold Invoice --namespace=admin --gd --nested=~users
+./bin/rails generate hot_glue:scaffold User --namespace=admin --gd
+./bin/rails generate hot_glue:scaffold Invoice --namespace=admin --gd --nested=~users
 ```
 Notice for the Invoice build, the parent user is *optionalized* (not 'optional'-- optionalized: to be made so it can be made optional).  
 
@@ -506,7 +443,7 @@ If you use Devise, you probably already have a `current_user` method available i
 
 If you use a different object other than "User" for authentication, override using the `auth` option.
 
-`rails generate hot_glue:scaffold Thing --auth=current_account`
+`./bin/rails generate hot_glue:scaffold Thing --auth=current_account`
 
 You will note that in this example it is presumed that the Account object will have an association for `things`
 
@@ -545,7 +482,7 @@ As well, the `after_sign_in_path_for(user)` here is a hook for Devise also that
 The default (do not pass `auth_identifier=`) will match the `auth` (So if you use 'account' as the auth, `authenticate_account!` will get invoked from your generated controller; the default is always 'user', so you can leave both auth and auth_identifier off if you want 'user')
 
 
-`rails generate hot_glue:scaffold Thing --auth=current_account --auth_identifier=login`
+`./bin/rails generate hot_glue:scaffold Thing --auth=current_account --auth_identifier=login`
 
  
 In this example, the controller produced with:
@@ -559,7 +496,7 @@ However, the object graph anchors would continue to start from current_account.
 
 Use empty string to **turn this method off**:
  
-`rails generate hot_glue:scaffold Thing --auth=current_account --auth_identifier=''`
+`./bin/rails generate hot_glue:scaffold Thing --auth=current_account --auth_identifier=''`
 
 In this case a controller would be generated that would have NO before_action to authenticate the account, but it would still treat the current_account as the auth root for the purpose of loading the objects.
 
@@ -580,7 +517,7 @@ The short form looks like this. It presumes there is a 'pets' association from `
 
 (The long form equivalent of this would be `--hawk=pet_id{current_user.pets}`)
 
-This is covered in [Example #3 in the Hot Glue Tutorial](https://jfb.teachable.com/courses/hot-glue-in-depth-tutorial/lectures/38584014)
+This is covered in [Example #3 in the Hot Glue Tutorial](https://school.jasonfleetwoodboldt.com/8188)
 
 To hawk to a scope that is not the currently authenticated user, use the long form with `{...}` 
 to specify the scope. Be sure to note to add the association name itself, like `users`: 
@@ -590,7 +527,7 @@ to specify the scope. Be sure to note to add the association name itself, like `
 This would hawk the Appointment's `user_id` key to any users who are within the scope of the 
 current_user's has_many association (so, for any other "my" family, would be `current_user.family.users`). 
 
-This is covered in [Example #4 in the Hot Glue Tutorial](https://jfb.teachable.com/courses/hot-glue-in-depth-tutorial/lectures/38787505)
+This is covered in [Example #4 in the Hot Glue Tutorial](https://school.jasonfleetwoodboldt.com/8188)
 
 
 ### `--plural=`
@@ -598,11 +535,11 @@ This is covered in [Example #4 in the Hot Glue Tutorial](https://jfb.teachable.c
 You don't need this if the pluralized version is just + "s" of the singular version.
 Only use for non-standard plurlizations, and be sure to pass it as TitleCase (as if you pluralized the model name which is non-standard for Rails)
 
-An better alternative is to define the non-standard plurlizations globally in your app.
+An better alternative is to define the non-standard plurlizations globally in your app, which Hot Glue will respect.
 
 Make a file at `config/initializers/inflections.rb`
-
-# Add new inflection rules using the following format
+ 
+Add new inflection rules using the following format:
 ```
 ActiveSupport::Inflector.inflections do |inflect|
     inflect.irregular 'clothing', 'clothes'
@@ -621,7 +558,7 @@ By default, all fields are included unless they are on the default exclude list.
 If you specify any exclude list, those excluded **and** the default exclude list will be excluded. (If you need any of the fields on the default exclude list, you must use `--include` instead.)
 
 
-`rails generate hot_glue:scaffold Account --exclude=password`
+`./bin/rails generate hot_glue:scaffold Account --exclude=password`
 
 
 ### `--include=`
@@ -629,7 +566,7 @@ Separate field names by COMMA
 
 If you specify an include list, it will be treated as a whitelist: no fields will be included unless specified on the include list.
 
-`rails generate hot_glue:scaffold Account --include=first_name,last_name,company_name,created_at,kyc_verified_at`
+`./bin/rails generate hot_glue:scaffold Account --include=first_name,last_name,company_name,created_at,kyc_verified_at`
 
 You may not specify both include and exclude.
 
@@ -774,7 +711,7 @@ The bang (`!`) methods can respond in one of four ways:
 
 This means you can be a somewhat lazy about your bang methods, but keep in mind the truth operator compares boolean true NOT any object is truth. So your return object must either be actually true (boolean), or an object that is string or string-like (responds to .to_s). Want to just say it didn’t work? Return false. Want to just say it was OK? Return true. Want to say it was successful but provide a more detailed response? Return a string.
 
-Finally, you can raise an ActiveRecord error which will also get passed to the user, but in the flash alert area
+Finally, you can raise an ActiveRecord error which will also get passed to the user in the flash alert area.
 
 For more information see Example 5 in the Tutorial
 
@@ -791,6 +728,9 @@ Can now be created with more space (wider) by adding a `+` to the end of the dow
 
 The 'Abcs' portal will display as 5 bootstrap columns instead of the typical 4. (You may use multiple ++ to keep making it wider but the inverse with minus is not supported
 
+### `--stacked-downnesting`
+
+This puts the downnested portals on top of one another (stacked top to bottom) instead of side-by-side (left to right). This is useful if you have a lot of downnested portals and you want to keep the page from getting too wide.
 
 
 ## FLAGS (Options with no values)
@@ -853,7 +793,7 @@ To do this, use flag `--display-list-after-update`. The update will behave like
 
 ### `--with-turbo-streams`
 
-If and only if you specify `--with-turbo-streams`, your views will contain `turbo_stream_from` directives. Whereas your views will always contain `turbo_frame_tags` (wether or not this flag is specified) and will use the Turbo stream replacement mechanism for non-idempotent actions (create & update). This flag just brings the magic of live-reload to the scaffold interfaces themselves.
+If and only if you specify `--with-turbo-streams`, your views will contain `turbo_stream_from` directives. Whereas your views will always contain `turbo_frame_tags` (whether or not this flag is specified) and will use the Turbo stream replacement mechanism for non-idempotent actions (create & update). This flag just brings the magic of live-reload to the scaffold interfaces themselves.
 
 **_To test_**: Open the same interface in two separate browser windows. Make an edit in one window and watch your edit appear in the other window instantly.
 
@@ -868,6 +808,7 @@ please note that *creating* and *deleting* do not yet have a full & complete imp
 
 ### `--alt-foreign-key-lookup` (Foreign Key Lookups)
 
+Example #1
 `--alt-foreign-key-lookup=user_id{email}`
 
 Let's assume a `Company` `has_many :company_users` and also a `Company` `has_many :users, through: :company_users`
@@ -880,6 +821,19 @@ Let's say instead you don't want to expose the full list of all users to this co
 
 Instead of a drop-down, the interface will present an input box for the user to supply an *search by* email.
 
+Example #2
+```
+--alt-foreign-key-lookup='agent_id{email+}'
+```
+
+First, assume the current able has a `belongs_to` association for `agent_id` to a foreign model, `Agent`
+
+Here, we would build a scaffold that would treat the foreign key `agent_id` as an alt lookup, allowing the user to search for foreign records by email (the agent's email).
+
+The `+` symbol indicates to automatically make a new `agent` record (without it, the agent_id will be set to nil if there is no associated agent record found -- this may cause the update to fail, unless `optional: true` is on the belongs_to association.)
+
+
+
 ** Note: Current implementation does not work in conjunction with hawked associations to protect against users from accessing associated records not within scope.**
 TODO: make it work with hawked associations to protect against users from accessing associated records not within scope
 
@@ -920,8 +874,6 @@ Omits list LABEL itself above the list. (Do not confuse with the list heading wh
 Note that list labels may  be automatically omitted on downnested scaffolds.
 
 
-
-
 ## Field Labels
 
 ### `--form-labels-position` (default: `after`; options are **before**, **after**, and **omit**)
@@ -956,18 +908,178 @@ Omits the heading of column names that appears above the 1st row of data.
 
 ## Special Features
 
+### `--attachments`
+
+#### ActiveStorage Quick Setup
+(For complete docs, refer to https://guides.rubyonrails.org/active_storage_overview.html)
+
+`brew install vips`
+(for videos `brew install ffmpeg`)
+
+```
+bundle add image_processing
+./bin/rails active_storage:install
+./bin/rails db:migrate
+```
+
+Generate an images model:
+
+`./bin/rails generate model Images name:string`
+
+add to `app/model/image.rb`, giving it a variant called thumb (Note: Hot Glue will fallback to using a variant called "thumb" if you use the shorthand syntax. If you use the long syntax, you can specify the variant to use for displaying the image)
+
+```
+has_one_attached :avatar do |attachable|
+  attachable.variant :thumb, resize_to_limit: [100, 100]
+end
+```
+Generate a Hot Glue scaffold with the attachment avatar appended to the field list (the shorthand syntax)
+
+`./bin/rails generate hot_glue:scaffold Image --include='name:avatar' --gd --attachments='avatar'`
+
+(Attachments behave like fields and follow the same layout rules used for fields, except that, unlike fields, when NOT using an --include list, they do not get automatically added. Thus, attachments are opt-in. You do not need to specify an attachment on the attachments list as ALSO being on the include list, but you can for the purpose of using the layout tricks discussed in Specified Grouping Mode to make the attachment appear on the layout where you want it to)
+
+#### Caveats:
+• If thumbnails aren't showing up, make sure you have
+
+1) installed vips, and
+2) used an image that supports ActiveStorage "variable" mechanism. The supported types are png, gif, jpg, pjpeg, tiff, bmp, vnd.adobe.photoshop, vnd.microsoft.icon, webp. see https://stackoverflow.com/a/61971660/3163663
+To debug, make sure the object responds true to the variable? method.
+
+If you use the shorthand syntax,  Hot Glue looks for a variant "thumb" (what you see in the example above). 
+
+If it finds one, it will render thumbnails from the attachment variant `thumb`. To specify a variant name other than "thumb", use the first parameter below.
+
+If using the shortform syntax and Hot Glue does **not find a variant** called `thumb` at the code generation time, it will build scaffolding without thumbnails.
+
+#### `--attachments` Long form syntax with 1 parameter
+
+**--attachments='_attachment name_{_variant name_}'** 
+
+What if your variant is called something other than `thumb`
+
+Use the long-form syntax specifying a variant name other than `thumb`. For example, `thumbnail`
+
+`./bin/rails generate hot_glue:scaffold Image --include='name:avatar' --gd --attachments='avatar{thumbnail}'`
+
+The model would look like this:
+```
+has_one_attached :avatar do |attachable|
+  attachable.variant :thumbnail, resize_to_limit: [100, 100]
+end
+```
+
+If using the long-form syntax with 1 parameter and Hot Glue does not find the specified variant declared in your attachment, it will stop and raise an error. 
+
+
+#### `--attachments` Long form syntax with 1st and 2nd parameters
+
+**--attachments='_attachment name_{_variant name_|_field for saving original filename_}'**
+
+Grab the original file name of the uploaded file and stick it into a field called `name`
+
+`./bin/rails generate hot_glue:scaffold Image --include='orig_filename:avatar' --gd --attachments='avatar{thumbnail|name} --show-only=name'`
+
+Note: You must have a string field called `orig_filename`. It does not need to be visible, but if it is, it should be part of the `--show-only` list. (If it is not part of the show-only list, Hot Glue will overwrite it every time you upload a new file, making it so that any user's change might not stick.)
+
+Note that the `orig_filename` is not part of the inputted parameters,  it simply gets appended to the model **bypassing the Rails strong parameters mechanism**, which is why it is irrelevant if it is included in the field list and recommended that if you do include it, you make it show-only so as not to allow your users to edit or modify it.
+
+Note: The 1st and 2nd parameters may be left empty (use `||`) but the 3rd and 4th parameters must either be specified or the parameter must be left off. 
+
+#### `--attachments` Long form syntax with 1st, 2nd, and 3rd parameters
+
+An optional 3rd parameter to the long-form syntax allows you to specify direct upload using the word "direct", which will add direct_upload: true to your f.file_field tags.
+
+Simply specify a 3rd parameter of `direct` to enable this attachment to use direct upload.
+
+**--attachments='avatar{thumbnail|orig_filename|direct}'**
+
+If you leave the 2nd parameter blank when using the 3rd parameter, it will default to NOT saving the original filename:
+
+`--attachments='avatar{thumbnail||direct}'`
+
+
+#### For S3 Setup
+
+
+```
+bundle add aws-sdk-s3
+```
+
+
+in `config/storage.yml`, enable this block and configure with the access key + secret associated with an AWS user that has permissions:
+
+Also be sure to change `bucket`
+
+```
+# Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key)
+amazon:
+  service: S3
+  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
+  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
+  region: us-east-1
+  bucket: your_bucket-<%= Rails.env %> 
+
+```
+
+
+in development.rb or production.rb (or both), set
+```
+config.active_storage.service = :amazon
+```
+
+
+#### For Direct Upload Support
+1. 
+```
+yarn add @rails/activestorage
+```
+
+2. You need a job runner like sidekiq or delayed_job. I recommend sidekiq. Make sure to have it 
+
+- Start sidekiq with `bundle exec sidekiq` while you are testing
+
+3. Install ActiveStorage JS using: 
+
+`./bin/rails generate hot_glue:direct_upload_install`
+
+AND be sure to use the 3rd parameter ('direct') when building a HG scaffold as explained above.
+
+
+#### For Dropzone support
+- Dropzone requires direct uploads, so you must have direct uploads enabled for the attachment you want to use dropzone with.
+
+
+- Direct uploads requires that you have configured your external storage (S3, etc) correctly. See the ActiveStorage guide.
+
+`yarn add dropzone`
+
+
+(If you don't already have stimulus-rails, you will also need: `bundle add stimulus-rails` and `./bin/rails stimulus:install`)
+
+Then run:
+```
+./bin/rails generate hot_glue:dropzone_install
+```
+This will 1) copy the dropzone_controller.js file into your app and 2) add the dropzone css into your app's application.css or application.bootstrap.css file.
+
+
+
 
 ### `--factory-creation={ ... }`
 
 The code you specify inside of `{` and `}` will be used to generate a new object. The factory should instantiate with any arguments (I suggest Ruby keyword arguments) and must provide a method that is the name of the thing.
 
+You may use semi-colons to separate multiple lines of code.
+
 For example, a user Factory might be called like so:
 
-`rails generate hot_glue:scaffold User --factory-creation={factory = UserFactory.new(params: user_params)} --gd`
+`./bin/rails generate hot_glue:scaffold User --factory-creation={factory = UserFactory.new(params: user_params)} --gd`
 
 (Note we are relying on the `user_params` method provided by the controller.)
 
 You must do one of two things:
+
 1) In the code you specify, set an instance variable `@user` to be the newly created thing. (Your code should contain something like `@thing = ` to trigger this option.)
 2) Make a local variable called `factory` **and** have a method of the name of the object (`user`) on a local variable called `factory` that your code created
 
@@ -999,6 +1111,18 @@ end
 ```
 
 
+If you are using factory creation along with with alt lookups, be sure your factory code creates a local variable that follows this name
+
+**<downcase association name>**_factory.<downcase association name>
+
+Thus, your factory object must have a method of the same name as the factory being created which returns the thing that got created.
+(It can do the creation either on instantiation or when calling that method)
+
+For example, assuming the example from above, we are going to do the lookup ourselves inside of our own `AgentFactory` object.)
+
+```
+agent_factory = AgentFactory.new(find_or_create_by_email: agent_company_params[:__lookup_email])
+```
 
 
 
@@ -1008,6 +1132,7 @@ HotGlue will copy a file named base_controller.rb to the same folder where it tr
 
 The created controller will always have this base controller as its subclass. You are encouraged to implement functionality common to the *namespace* (shared between the controllers in the namespace) using this technique.
 
+
 ## Special Table Labels
 
 If your object is very wordy (like MyGreatHook) and you want it to display in the UI as something shorter,
@@ -1041,6 +1166,7 @@ Child portals have the headings omitted automatically (there is a heading identi
 # Note about enums
 
 The Rails 7 enum implementation for Postgres is very slick but has a counter-intuitive facet.
+
 Define your Enums in Postgres as strings:
 (database migration)
 ```
@@ -1064,25 +1190,79 @@ enum status: {
   }
 ```
 
-To set the labels, use another class-level method that is a hash of keys-to-labels using a method named the same name as the enum method but with `_labels`
+To set the labels, use a class-level method that is a hash of keys-to-labels using a method named the same name as the enum method but with `_labels`
 
 If no `_labels` method exists, Hot Glue will fallback to using the Postgres-defined names.
 ```
 def self.status_labels
     {
-      pending: 'Is Pending',
-      active: 'Is active',
-      archived: 'Is Archived',
+      pending: 'Is currently pending',
+      active: 'Is really active',
+      archived: 'Is done & archived',
       disabled: 'Is Disabled',
       waiting: 'Is Waiting'
     }
 ```
 
-Now, your labels will show up as defined in the `_labels` ("Is Pending", etc) instead of the database-values.
+Now, your labels will show up on the front-end as defined in the `_labels` ("Is currently pending", etc) instead of the database-values.
 
 
 # VERSION HISTORY
 
+#### 2023-03-17 - v0.5.9
+- Attachments! You can use Hot Glue to seamlessly create an image, file, or video attachment. Please see the docs in new flag `--atachments` under the "Special Features" section
+
+- Watch the demo on attachments here on YouTube: https://youtu.be/yJbjwReCr18
+
+- Fixes to downnesting
+
+- `--stacked-downnesting` flag — The Layout Builder now can stack downnesting portals instead of putting them side-by-side. When stacked, there is no limit to how many you can have and the entire stack takes up 4-bootstrap columns. 
+
+- Hot Glue has been moved on Github from my personal organization to a new organization named `hot-glue-for-rails`. The new Github url is: `https://github.com/hot-glue-for-rails/hot-glue`
+
+
+#### 2023-03-01 - v0.5.8 
+
+• Fixes spec assertions for enums to work with the enum `_label` field (when provided).
+
+• Fixes `--form-label-position` (before/after) so that a carriage return is placed between the label & field correctly for either choice
+
+• All spec files are now created in `spec/features/` folder (previously was `spec/system/` with `type: :feature`; they no longer have `type: :feature` as this is not necessary when they are in the `spec/features` folder)
+
+• Corrects the hawk scope to only add the plural related entity when NOT using the shorthand `{ ... }`
+
+• BEM (block element modifier)-style has been added list headings, show cells, edit cells. These class names will get added to the `<div>` tags for both the heading and cells. 
+
+The format is as follows:
+
+For headings
+    `heading--{singular}--{field name}-{field name}-{field name}`
+
+For cells:
+    `cell--{singular}--{field name}-{field name}-{field name}`
+   use this to globally style different fields by object & field name
+
+Note that if you have multiple fields inside one cell (for example, with specified grouping or smart layout), your fields names get concatenated using single-hyphens:
+For example, consider a customer scaffold with a first name & last name appearing in one cell. The cell itself will have a class of:
+`cell--customer--first_name-last_name`
+
+If your cell contains only one field, for example, a phone number, it would look like this:
+`cell--customer--phone_number`
+
+Tip: Use the _ends with_ and _starts with_ selectors, which can be used like this:.
+
+```
+div[class$="--phone_number"] {
+    text-decoration: underline; 
+}
+```
+
+
+```
+
+```
+
+
 #### 2023-02-13 - v0.5.7 - factory-creation, alt lookups, update show only, fixes to Enums, support for Ruby 3.2
 • See `--factory-creation` section.
 
@@ -1147,8 +1327,8 @@ License check has been removed (Hot Glue is now free to use for hobbyists and in
 #### 2022-03-23 - v0.5.2 - Hawked Foreign Keys
 
  - You can now protect your foreign keys from malicious input and also restrict the scope of drop downs to show only records with the specified access control restriction.
- - [Example #3](https://jfb.teachable.com/courses/hot-glue-in-depth-tutorial/lectures/38584014) in the Hot Glue Tutorial shows you how to use the hawk to limit the scope to the logged in user.
- - [Example #4](https://jfb.teachable.com/courses/hot-glue-in-depth-tutorial/lectures/38787505) in the Hot Glue Tutorial shows how to hawk to a non-usual scope, the inverse of the current user's belongs_to (that is, hawk the scope to X where current_user `belongs_to :x`)
+ - [Example #3](https://school.jasonfleetwoodboldt.com/8188) in the Hot Glue Tutorial shows you how to use the hawk to limit the scope to the logged in user.
+ - [Example #4](https://school.jasonfleetwoodboldt.com/8188) in the Hot Glue Tutorial shows how to hawk to a non-usual scope, the inverse of the current user's belongs_to (that is, hawk the scope to X where current_user `belongs_to :x`)
  
 
 #### 2022-03-12  - v0.5.1 - Inline List Labels