hot-glue 0.4.4 → 0.4.8.1

data/README.md

@@ -1,10 +1,8 @@
 
-[![Build Status](https://app.travis-ci.com/jasonfb/hot-glue.svg?branch=main)](https://travis-ci.com/jasonfb/hot-glue)
-
+[![Hot Glue](https://circleci.com/gh/jasonfb/hot-glue.svg?style=shield)](https://circleci.com/gh/jasonfb/hot-glue)
 
 Hot Glue is a Rails scaffold builder for the Turbo era. It is an evolution of the admin-interface style scaffolding systems of the 2010s ([activeadmin](https://github.com/activeadmin/activeadmin), [rails_admin](https://github.com/sferik/rails_admin), and [active_scaffold](https://github.com/activescaffold/active_scaffold)).
 
-
 Using Turbo-Rails and Hotwire (default in Rails 7) you get a lightning-fast out-of-the-box CRUD building experience.
 
 Every page displays only a list view: new and edit operations happen as 'edit-in-place', so the user never leaves the page.
@@ -19,18 +17,18 @@ By default, it generates code that gives users full control over objects they 'o
 
 Hot Glue generates functionality that's quick and dirty. It lets you be crafty. As with a real hot glue gun, use with caution.
 
-* Build plug-and-play scaffolding mixing generated ERB or HAML with the power of Hotwire and Turbo-Rails
-* Everything edits-in-place (unless you use --big-edit, then it won't)
-* Automatically Reads Your Models (make them before building your scaffolding!)
+* Build plug-and-play scaffolding mixing generated ERB with the power of Hotwire and Turbo-Rails
+* Everything edits-in-place (unless you use `--big-edit`, then it won't)
+* Automatically Reads Your Models (make them AND migrate your DB before building your scaffolding!)
 * Excellent for CREATE-READ-UPDATE-DELETE (CRUD), lists with pagination (coming soon: searching & sorting)
 * Great for prototyping, but you should learn Rails fundamentals first.
 * 'Packaged' with Devise, Kaminari, Rspec, FontAwesome
-* Create system specs  automatically along with the generated code.
+* 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.
 
 # Hot Glue Tutorial 
-## [GET THE COURSE TODAY (includes Hot Glue License)](https://jfb.teachable.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 (includes Hot Glue License)](https://jfbcodes.com/courses/hot-glue-in-depth-tutorial/?utm_source=github.com&utm_campaign=github_hot_glue_readme_page) **only $60 USD!**
 
 |   |  |  
 | ------------- | ------------- |
@@ -55,44 +53,36 @@ Instantly get a simple CRUD interface
 
 # Getting Started
 
-_If you are on Rails 6, skip to section Rails 6 Setup and complete those steps FIRST._
-
-
-## 1. ADD RSPEC, FACTORY-BOT, AND FFAKER
+_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._
 
-add these 3 gems to your gemfile **inside a group for both :development and :test*. Do not add these gems to only the :test group or else your will have problems with the generators.
-```
-gem 'rspec-rails'
-gem 'factory_bot_rails'
-gem 'ffaker'
-```
 
-- run `rails generate rspec:install`
+## 1. Rails 7 New App
 
-- replace `application.css` with a new file (delete old contents) `application.scss`
+There are two ways to create new apps on Rails 7: With or without ImportMap. These instructions prefer the **without Importmap** method, but to help you choose [see this post](https://jasonfleetwoodboldt.com/courses/stepping-up-rails/rails-7-do-i-need-importmap-rails/)
 
-THIS FILE CAN BE EMPTY, BUT WILL BE USED BY THEME INSTALLER
+`rails new --css=bootstrap --javascript=webpack --database=postgresql`
 
-## 2. ADD BOOTSTRAP (OPTIONAL)
+Confirm that both Stimulus and Turbo are working. For the quick step-by-step to help you confirm 
+that both Stimulus and Turbo are working for your new JSBundling-Rails/CSSBunlding-Rails setup [see this post](https://jasonfleetwoodboldt.com/courses/stepping-up-rails/rails-7-new-app-with-js-bundling-css-bundling/).
 
-_BOOTSTRAP IS NO LONGER NEEDED_, but I recommend it.
+(Note that Bootstrap is optional for Hot Glue. Here, I am just showing you the default isntallation for simplicity.)
 
-IF you are using `--layout=bootstrap` (step 3), you must install Bootstrap here.
+For the old method of installing Bootstrap [see this post](https://jasonfleetwoodboldt.com/courses/stepping-up-rails/rails-7-bootstrap/)
 
-Bootstrap with Webpacker is no longer in Rails 7 by default. (For that see ________TBD________)
+Remember, for Rails 6 you must go through the [LEGACY SETUP FOR RAILS 6](https://github.com/jasonfb/hot-glue/README2.md) before continuing. 
 
-For Bootstrap with Sprockets (recommended by Rails team), see https://github.com/twbs/bootstrap-rubygem
+## 2. ADD RSPEC, FACTORY-BOT, AND FFAKER
 
-If going the the Bootstrap with Sprockets route, note the gem is
+add these 3 gems to your gemfile **inside a group for both :development and :test*. Do not add these gems to only the :test group or else your will have problems with the generators.
 ```
-gem 'bootstrap', '~> 5.1.3'
+gem 'rspec-rails'
+gem 'factory_bot_rails'
+gem 'ffaker'
 ```
 
-Then, all you need to do is add to `app/assets/stylesheets/application.scss`
+- run `rails generate rspec:install`
+
 
-```
-@import "bootstrap";
-```
 
 ## 3. HOTGLUE INSTALLER
 Add `gem 'hot-glue'` to your Gemfile & `bundle install`
@@ -101,7 +91,7 @@ Purchase a license at https://heliosdev.shop/hot-glue-license
 
 During in installation, you MUST supply a `--layout` flag.
 
-### `--layout` flag
+### `--layout` flag (NOTE: haml and slim are no longer supported at this time)
 Here you will set up and install Hot Glue for the first time. It will install a config file that will save two preferences: layout (hotglue or bootstrap) and markup (erb or haml or slim).
 
 Once you run the installer, the installer will save what you set it to in `config/hot_glue.yml`. Newly generated scaffolds will use these two settings, but you can modify them just by modifying the config file (you don't need to re-run the installer)
@@ -135,7 +125,7 @@ The themes are just SCSS files installed into app/assets/stylesheets. You can tw
 
 ### `--markup` flag
 
-default is `erb`
+default is `erb`. IMPORTANT: As of right now, I am only supporting & building against ERB. HAML and SLIM are not currently supported.
 
 
 ## 3. RUN HOT-GLUE INSTALL:
@@ -145,9 +135,64 @@ default is `erb`
 ### Example installing HAML 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. install font-awesome (optional)
+
+I recommend
+https://github.com/tomkra/font_awesome5_rails
+or
+https://github.com/FortAwesome/font-awesome-sass
+
+
+## 5. Devise
+
+(or only use --gd mode, see below)
+
+Add to your Gemfile
+
+As of 2022-01-26 Devise for Rails 7 is still not released so you must use **main branch**, like so:
+
+`gem 'devise', branch: 'main', git: 'https://github.com/heartcombo/devise.git'`
+
+(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))
+
+For Rails 7, be sure you are on the main branch of devise above and your logins should work. (The previously necessary step of disabling turbo shown in Legacy Step #5 is no longer needed. )
+
+You MUST run the installer FIRST or else you will put your app into a non-workable state:
+```
+rails generate devise:install
+```
+
+IMPORTANT: Follow the instructions the Devise installer gives you, *Except Step 3*, you can skip this step:
+```
+ 3. Ensure you have flash messages in app/views/layouts/application.html.erb.
+     For example:
+
+       <p class="notice"><%= notice %></p>
+       <p class="alert"><%= alert %></p>
+
+```
+
+Be sure to create primary auth model with:
+
+`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.
+
+Those features come by default with Devise, and you'll find the fields for them in the newly generated migration file. 
+
+In this example above, you are creating all of those fields along with a simple 'name' (string) field for your User table.
+
+
+
+
+### Hot Glue Installer Notes 
 
-##  3(B). Modify `application.html.erb`
-(THIS WAS AUTOMATICALLY DONE BY THE HOT GLUE INSTALLATION -- CONFIRM CHANGES ONLY)
+These things were **done for you** in Step #3 (above). You don't need to think about them but if you are familiar with Capybara and/or adding Hot Glue to an existing app, you may want to:
+
+####  Hot Glue modified `application.html.erb`
 Note: if you have some kind of non-standard application layout, like one at a different file
 or if you have modified your opening <body> tag, this may not have been automatically applied by the installer.
 
@@ -156,8 +201,7 @@ or if you have modified your opening <body> tag, this may not have been automati
   <%= render partial: 'layouts/flash_notices' %>
 ```
 
-## 3(C). Modify `rails_helper.rb`
-(THIS WAS AUTOMATICALLY DONE BY THE HOT GLUE INSTALLATION)
+#### Hot Glue modified `rails_helper.rb`
 Note: if you have some kind of non-standard rails_helper.rb, like one that does not use the standard ` do |config|` syntax after your `RSpec.configure`
 this may not have been automatically applied by the installer.
 
@@ -170,8 +214,7 @@ this may not have been automatically applied by the installer.
   ```  
 
 
-## 3(D) CAPYBARA: SWITCH FROM RACK-TEST TO HEADLESS CHROME
-(THIS WAS AUTOMATICALLY DONE BY THE HOT GLUE INSTALLATION)
+#### Hot Glue switched Capybara from RACK-TEST to HEADLESS CHROME
 
 - By default Capybara is installed with :rack_test as its driver.
 - This does not support Javascript, and the code from Hot Glue IS NOT fallback compatible-- it will not work on non-Javascript browsers.
@@ -192,7 +235,7 @@ By default, the installer should have added this option to your `rails_helper.rb
 Capybara.default_driver = :selenium_chrome_headless 
 ```
 
-Alternatively, can define your own driver like so:
+Alternatively, you can define your own driver like so:
 
   ```
   Capybara.register_driver :my_headless_chrome_desktop do |app|
@@ -211,8 +254,7 @@ Alternatively, can define your own driver like so:
     
   ```
 
-
-(THIS WAS ALSO AUTOMATICALLY DONE BY THE HOT GLUE INSTALLATION)
+#### Hot Glue Added a Quick (Old-School) Capybara Login For Devise
 
 - for a quick Capybara login, create a support helper in `spec/support/` and log-in as your user
 - in the default code, the devise login would be for an object called account and lives at the route `/accounts/sign_in`
@@ -228,148 +270,12 @@ Alternatively, can define your own driver like so:
    end
    ```
 
-
-## 4. install font-awesome (optional)
-
-I recommend
-https://github.com/tomkra/font_awesome5_rails
-or
-https://github.com/FortAwesome/font-awesome-sass
-
-
-## 5. Devise
-
-(or only use --gd mode, see below)
-
-Add to your Gemfile
-
-As of 2021-12-28 Devise for Rails 7 is still not released so you must use main branch, like so:
-`gem 'devise', branch: 'main', git: 'https://github.com/heartcombo/devise.git'`
-
-If on Rails 6 **or** Rails 7, you must do the steps in **Legacy Step #5** (below).
-
-(If you are on Rails 6, you must do ALL of the steps in the Legacy Setup steps.)
-
-To be clear: You CAN use Devise with Rails 7, but you must still do the Legacy Step #5 described below for your login to work.
-
-```
-rails generate devise:install
-```
-
-IMPORTANT: Follow the instructions the Devise installer gives you, *Except Step 3*, you can skip this step:
-```
- 3. Ensure you have flash messages in app/views/layouts/application.html.erb.
-     For example:
-
-       <p class="notice"><%= notice %></p>
-       <p class="alert"><%= alert %></p>
-
-```
-
-
-As described in Legacy Step #5, **you cannot** skip Devise installer Step 4, even though the installer tells you it is optional:
-``` 
-  4. You can copy Devise views (for customization) to your app by running:
-
-       rails g devise:views
-       
-```
-Once you copy the files, you must modify the Devise views to disable Turbo as described in Legacy Step #5.
-
-
-## LEGACY SETUP FOR RAILS 6
-
-(Note Legacy Step #5 is necessary for BOTH Rails 6 and Rails 7.)
-
-
-## Legacy Step #1. ADD HOTWIRE
-(RAILS 6 ONLY— SKIP THIS STEP FOR RAILS 7)
-```
-yarn add @hotwired/turbo-rails
-```
-or `npm install @hotwired/turbo-rails`
-
-
-## Legacy Step #2. SWITCH FROM TurblLinks to Turbo-Rails
-(RAILS 6 ONLY — SKIP FOR RAILS 7)
-(THIS WAS AUTOMATICALLY DONE BY THE HOT GLUE INSTALLATION -- CONFIRM CHANGES ONLY)
-- Add `gem 'turbo-rails'` to your Gemfile & `bundle install`
-- Then install it with `rails turbo:install`
-- The Turbo install has switched your action cable settings from 'async' to Redis, so be sure to start a redis server
-- in `app/javascript/packs/application.js` remove this line
-```
-import Turbolinks from "turbolinks"
-```
-and replace it with
-```
-import { Turbo } from "@hotwired/turbo-rails"
-```
-
-
-Also replace
-``` 
-Turbolinks.start()
-```
-with:
-```
-Turbo.start()
-```
-
-
-## Legacy Step #3. INSTALL WEBPACKER
-(_SKIP FOR RAILS 7_ unless you want to use Webpacker with Rails 7)
-
-** For webpacker, you must be using Node version ^12.13.0 || ^14.15.0 || >=16 **
-
-I recommend Node Version Manager (NVM) to switch between nodes. You will not be able to get through the following command with a Node version that does not match above.
-
-Check your node version with `node -v`
-
-```
-`yarn add @rails/webpacker`
-```
-
-
-rails webpacker:install
-
-## Legacy Step #4: ENUM Support
-For Enum support, I recommend activerecord-pg_enum
-Instructions for Rails 6 are here:
-https://jasonfleetwoodboldt.com/courses/stepping-up-rails/enumerated-types-in-rails-and-postgres/
-
-_This functionality is now built-in to Rails 7._
-
-
-## Legacy Step #5-- Fix Devise if adding Turbo To Your Project
-## IMPORTANT: Devise currently has serious compatibility issues with Turbo Rails. In particular, your log-in screens do not work out of the box. Follow the next step to fix them.
-
-Manually port the Devise views into your app with
-
-`rails generate devise:views`
-
-Edit `devise/registrations/new`, `devise/sessions/new`, `devise/passwords/new` and `devise/confirmations/new` modifying all four templates like so:
-
-form_for(resource, as: resource_name, url: session_path(resource_name) ) do |f|
-
-
-
-add the data-turbo false option in the html key:
-
-
-form_for(resource, as: resource_name, **html: {'data-turbo' => "false"},** url: session_path(resource_name) ) do |f|
-
-
-
-This tells Devise to fall back to non-Turbo interaction for the log-in and registration. For the rest of the app, we will use Turbo Rails interactions.
-
-
 ---
 ---
 
 
 # HOT GLUE DOCS
 
-
 ## First Argument
 (no double slash)
 
@@ -404,33 +310,54 @@ end
 ```
 
 
-### `--nest=`
+### `--nested=`
 
-pass `--nest=` to denote a nested resources
+This object is nested within another tree of objects, and there is a nested route in your `routes.rb` file. When specifying the parent(s), be sure to use **singular case**.
 
+#### Example #1: One-level Nesting
+Invoice `has_many :lines` and a Line `belongs_to :invoice`
 
-`rails generate hot_glue:scaffold Line --nest=invoice`
+```
+resources :invoices do
+  resource :lines do
+end
+```
 
-In this example, it is presumed that the current user has_many :invoices, and that invoices have many :lines
+`rails generate hot_glue:scaffold Invoice`
 
+`rails generate hot_glue:scaffold Line --nested=invoice`
 
-For multi-level nesting use slashes to separate your levels of nesting. Remember, you should match what you have in your routes.rb file.
 
+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.)
+
+#### Example #2: Two-level Nesting
+
+Invoice `has_many :lines` and a Line `belongs_to :invoice`
+Line `has_many :charges` and Charge `belongs_to :line`
+
+**config/routes.rb**
 ```
 resources :invoices do
     resources :lines do
         resources :charge
     end    
 end
-
 ```
-In this example, it is presumed that the current user has_many :invoices, and that invoices have many :lines, and that lines have many :charges
 
 
-To generate scaffold:
-`rails generate hot_glue:scaffold Charge --nest=invoice/line`
+_For multi-level nesting use slashes to separate your levels of nesting._
+
+`rails generate hot_glue:scaffold Invoice`
+
+`rails generate hot_glue:scaffold Line --nested=invoice`
+
+`rails generate hot_glue:scaffold Charge --nested=invoice/line`
+
 
-The order of the nest should match the nested resources you have in your own app.  In particular, you auth root will be used as the starting point when loading the objects from the URL:
+
+For non-Gd controllers, your auth root will be used as the starting point when loading the objects from the URL if this object is nested.
+
+(For Gd controllers the root object will be loaded directly from the ActiveRecord object.)
 
 In the example above, @invoice will be loaded from
 
@@ -444,13 +371,9 @@ Then, finally the @charge will be loaded
 
 `@charge = @line.charges.find(params[:id])`
 
-It's called "poor man's access control" because if a user attempts to hack the URL by passing ids for objects they don't own--- which Rails makes relatively easy with its default URL pattern-- they will hit ActiveRecord not found errors (the objects they don't own won't be found in the associated relationship).
-
-It works, but it isn't granular. As well, it isn't appropriate for a large app with any level of intricacy to access control (that is, having roles).
-
-Your customers can delete their own objects by default (may be a good idea or a bad idea for you). If you don't want that, you should strip out the delete actions off the controllers.
-
+This is "starfish access control" or "poor man's access control."  It works when the current user has several things they can manage, and by extension can manage children of those things.  
 
+                                                         
 ### `--auth=`
 
 By default, it will be assumed you have a `current_user` for your user authentication. This will be treated as the "authentication root" for the "poor man's auth" explained above.
@@ -473,6 +396,26 @@ It is also presumed that when viewing their own dashboard of things, the user wi
 
 If you supply nesting (see below), your nest chain will automatically begin with your auth root object (see nesting)
 
+#### Optionalized Nested Parents
+
+Add `~` in front of any nested parameter (any parent in the `--nest` list) you want to make optional. This creates a two-headed controller: It can operate with or without that optionalized parameter. 
+
+This is an advanced feature is to use two duplicitous routes to the same controller.  You can only use this feature with Gd controller.  To use, specify your controller *twice* in your routes.rb. Then, in your `--nest` setting, add `~` to any nested parent you want to **make optional**. "Make optional" means the controller will behave as-if it exists in two places: once, at the normal nest level.  Then the same controller will 'exist' again one-level up in your routes. **If the route has sub-routes, you'll need to re-specify the entire subtree also**.
+```
+namespace :admin
+  resources :users do
+    resources :invoices
+  end
+  resources :invoices
+end
+```
+Hot Glue will build the scaffolding once for users and once again for invoice. Even though we have two routes pointed to invoices, 
+```
+rails generate hot_glue:scaffold User --namespace=admin --gd --downnest=invoices
+rails generate hot_glue:scaffold Invoice --namespace=admin --gd --nest=~users
+```
+Notice for the Invoice build, the parent user is *optionalized* (not 'optional'-- optionalized: to be made so it can be made optional).  The Invoices controller, which is a Gd controller, will load the User if a user is specified in the route (`/admin/users/:user_id/invoices/`). It will ALSO work at `/admin/invoices` and will switch back into loading directly from the base class when routed this way.
+
 
 
 
@@ -549,22 +492,79 @@ If you specify an include list, it will be treated as a whitelist: no fields wil
 
 `rails generate hot_glue:scaffold Account --include=first_name,last_name,company_name,created_at,kyc_verified_at`
 
-Separate COLUMNS by a COLON
+You may not specify both include and exclude.
+
+Include setting is affected by both specified grouping and smarty layouts, explained below.
+
+
+#### Specified Grouping Mode
+
+To specify grouped columns, separate COLUMNS by a COLON, then separate fields with commas. Specified groupings work like smart layouts (see below), except you drive which groupings make up the columns. 
+
+(Smarty layouts, below, achieves the same effect but automatically groups your fields into a smart number of columns. ) 
+
 If you want to group up fields together into columns, use a COLON (`:`) character to specify columns.
-Your input may have a COLON at the end of it, but otherwise your columns will made flush left.
 
-Without colons, no group will happen, so these two fields would display in two columns:
+Your input **may** have a COLON at the end of it, but otherwise your columns will made **flush left**.
+
+Without specified grouping (and not using smart layout), no group will happen, so these two fields would display in two columns:
 `--include=api_id,api_key`
 
-With a trailing colon, you're telling Hot Glue to make the two fields into column #1. (Here, there is no other column.)
+With a trailing colon you would be specifying the grouping. You're telling Hot Glue to make the two fields into column #1. (There is no other column.)
 `--include=api_id,api_key:`
 
+
 If, for example, you wanted to put the `name` field into column #1 and then the api_id and api_key into column #2, you would use:
 `--include=name:api_id,api_key`
 
-Specifying any colon in your include syntax switches the builder into 12-column mode, whereas without you might create more than 12 columns if there are too many feilds for the available columns on the layout.
 
-You may not specify both include and exclude.
+
+Specifying any colon in your include syntax switches the builder into specified grouping mode. The effect will be that the fields will be stacked together into nicely fit columns. (This will look confusing if your user expect an Excel-like interface.)
+
+With Bootstrap in specified grouping or smart layout mode, it automatically attempts to fit everything into 12-columns. 
+
+Using Bootstrap with neither specified grouping nor smart layouts may make 12 columns, which will produce strange result. (Bootstrap is not designed to work with, for example, a 13-column layout.)
+
+You should typically either specify your grouping or use smart layouts when building with Bootstrap, but if your use case does not fit the stacking feature you can specify neither and then you may have deal with the over-stuffed layouts as explained above. 
+
+
+
+### `--smart-layout` mode (automatic grouping) (default: false)
+
+Smart layouts are like specified grouping but Hot Glue does the work of figuring out how many fields you want in each column. 
+
+It will concatinate your fields into groups that will fit into the Bootstraps 12-column grid.
+
+The effect will be that the fields will be stacked together into nicely fit columns.
+
+**Some people expect each field to be a column and think this looks strange.**
+
+**If your customer is used to Excel, this feature will confuse them.**
+
+Also, this feature will **probably not** be supported by the SORTING (not yet implemented; TBD). I'm not really sure it makes sense to build a non-columnar layout with sorting, so I think I **probably won't support smart layouts** if you want sorting. (You will be forced to choose between the two which I think makes sense.)
+
+The layout builder works from right-to-left and starts with 12, the number of Bootstrap's columns.
+
+It reserves 2 columns for the default buttons. Then +1 additional column for **each magic button** you have specified.
+
+Then it takes 4 columns for **each downnested portal**.
+
+If you're keeping track, that means we may have used 6 to 8 out of our Bootstrap columns already if we have buttons & portals. (With no portals and no magic buttons you have a nice even 10 columns to work with.)
+
+If we have 2 downnested portals and only the default buttons, that uses 10 out of 12 Bootstrap columns, leaving only 2 bootstrap columns for the fields.
+
+THe layout builder takes the number of columns left and then distributes the feilds 'evenly' among them. However, note that order specified translates to up-to-down within the column, and then left-to-right across the columns, like so:
+
+A D G
+
+B E H
+
+C F I
+
+This is what would happen if 9 fields, specified in the order A,B,C,D,E,F,G,H,I, were distributed across 3 columns. 
+
+(If you had a number of fields that wasn't easily divisible by the number of columns, it would leave the final column a few fields short of the others.)
+
 
 
 ### `--show-only=`
@@ -576,30 +576,30 @@ IMPORTANT: By default, all fields that begin with an underscore (`_`) are automa
 
 I would recommend this for fields you want globally non-editable by users in your app. For example, a counter cache or other field set only by a backend mechanism.
 
-### `--stimulus_syntax=true` or `--stimulus_syntax=false`
-(for Rails <=6, default is false. For Rails 7, default is true.)
+### `--ujs_syntax=true` (Default is set automatically based on whether you have turbo-rails installed)
 
-Stimulus is only used for the delete button's confirmation dialog.
+If you are pre-Turbo (UJS), your delete buttons will come out like this:
+`data: {'confirm': 'Are you sure you want to delete....?'}`
 
-If you don't have stimulus syntax enabled, your delete buttons have this. This will confirm the delete with a simple alert if you have UJS enabled.
+If you are Turbo (Rails 7 or Rails 6 with proactive Turbo-Rails install), your delete button will be:
+`data: {'turbo-confirm': 'Are you sure you want to delete....?'}`
 
-```
-{confirm: 'Are you sure?'}
-```
+If you specify the flag, you preference will be used. If you leave the flag off, Hot Glue will detect the presence of Turbo-Rails in your app. 
 
-If you do have Stimulus syntax enabled, your delete buttons will look like so:
-```
-    ## TODO: fix this
-```
+**WARNING**: If you created a new Rails app since October 2021 and you have the yanked turbo-rails Gems on your local machine, 
+you will have some bugs with the delete buttons and also not be on the latest version of turbo-rails.
 
+Make sure to uninstall the yanked 7.1.0 and 7.1.1 from your machine with `gem uninstall turbo-rails`
+and also fix any Rails apps created since October 2021 by fixing the Gemfile. Details here:
+https://stackoverflow.com/questions/70671324/new-rails-7-turbo-app-doesnt-show-the-data-turbo-confirm-alert-messages-dont-f
 
 
-### `--magic-buttons` (Version 0.4.0 only)
+### `--magic-buttons` 
 If you pass a list of magic buttons (separated by commas), they will appear in the button area on your list.
 
-It will be assumed there will be cooresponding bang methods on your models.
+It will be assumed there will be corresponding bang methods on your models.
 
-The band methods can respond in one of four ways:
+The bang (`!`) methods can respond in one of four ways:
 
 • With true, in which case a generic success message will be shown in the flash notice (“Approved” or “Rejected” in this case)
 
@@ -619,9 +619,10 @@ For more information see Example 5 in the Tutorial
 ### `--downnest`
 
 Automatically create subviews down your object tree. This should be the name of a has_many relationship based from the current object.
-You will need to build scaffolding with the same name for the related object as well.
-On the list view, the object you are currently building will be built with a sub-view list of the objects related from the given line.
+You will need to build scaffolding with the same name for the related object as well. On the list view, the object you are currently building will be built with a sub-view list of the objects related from the given line.
 
+The downnested child table (not to be confused with this object's `--nested` setting, where you are specifying this object's _parents_) is called a **child portal**. When you create a record in the child portal, the related record is automatically set to be owned by its parent (as specified by `--nested`). For an example, see the [v0.4.7 release notes](https://github.com/jasonfb/hot-glue/releases/tag/v0.4.7).
+ 
 
 
 
@@ -661,6 +662,11 @@ Omits pagination. (All list views have pagination by default.)
 
 Omits list action. Only makes sense to use this if you are create a view where you only want the create button you want to navigate to the update screen alternative ways.
 
+
+### `--no-list-labels`
+
+Omits list labels. (note that in the form the labels are rendered again anyway)
+
 ### `--no-create`
 
 Omits create action.
@@ -681,7 +687,6 @@ Sometimes you might want to redisplay the entire list after you make an update (
 
 To do this, use flag `--display_list_after_update`. The update will behave like delete and re-fetch all the records in the result and tell Turbo to swap out the entire list.
 
-### `--smart-layout` (default: false)
 
 
 
@@ -694,25 +699,59 @@ Obviously, the created controller will always have this base controller as its s
 
 ## Field Types Supported
 
-- Integers that don't end with `_id`, they will be displayed as text fields.
+- Integers that don't end with `_id`: displayed as input fields with type="number"
 - Integers that do end with `_id` will be treated automatically as associations. You should have a Rails association defined. (Hot Glue will warn you if it can't find one.)
-- String*
-- Text*
-- Float*
-- Datetime
-- Date
-- Time
-- Boolean
-- Enum - will display as a value list populated from the enum list defined on your model. see https://jasonfleetwoodboldt.com/courses/stepping-up-rails/enumerated-types-in-rails-and-postgres/
+- String: displayed as small input box 
+- Text: displayed as large textarea
+- Float: displayed as input box
+- Datetime: displayed as HTML5 datetime picker
+- Date: displayed as HTML5 date picker
+- Time: displayed as HTML5 time picker
+- Boolean: displayed radio buttons yes/ no
+- Enum - displayed as a drop-down list (defined the enum values on your model). For Rails 6 see https://jasonfleetwoodboldt.com/courses/stepping-up-rails/enumerated-types-in-rails-and-postgres/
+
 
-* shows in a size-aware container, i.e. in a bigger box if the field allows for more content
+# VERSION HISTORY
 
 
 
-# VERSION HISTORY
 
+#### 2022-02-07 - v0.4.8 Optionalized Nested Parents
+    - optionalized nested parents. to use add `~` in front of any nested parameter you want to make optional
+    
+    - This is an advanced feature is to use two duplicitous routes to the same controller.  You can only use this feature with Gd controller.  To use, specify your controller *twice* in your routes.rb. Then, in your `--nest` setting, add `~` to any nested parent you want to **make optional**. "Make optional" means the controller will behave as-if it exists in two places: once, at the normal nest level.  Then the same controller will 'exist' again one-level up in your routes. **If the route has sub-routes, you'll need to re-specify the entire subtree also**.
+```
+namespace :admin
+  resources :users do
+    resources :invoices
+  end
+  resoures :invoices
+end
+```
+We will  build the scaffolding once for users and once again for invoice. Even though we have two routes pointed to invoices,
+```
+rails generate hot_glue:scaffold User --namespace=admin --gd --downnest=invoices
+rails generate hot_glue:scaffold Invoice --namespace=admin --gd --nest=~users
+```
+    - Notice for the Invoice build, the parent user is *optionalized* (not 'optional'-- optionalized: to be made so it can be made optional).  The Invoices controller, which is a Gd controller, will load the User if a user is specified in the route (`/admin/users/:user_id/invoices/`). It will ALSO work at `/admin/invoices` and will switch back into loading directly from the base class when routed this way.
+    - fixes to specified grouping mode-- the columns you specify now grab up the remaining bootstrap columns to fill space
+
+#### 2022-01-26 - v0.4.7 `--nest` has been renamed to `--nested`; please use `--nested` moving forward
+  - `--alt-controller-name` feature from the last release has been removed, I have something better coming soon
+  - significant improvements to how child portals are handled, including setting the owner (parent) object when creating new records from a child portal
+  - improvements to how 'self-auth' is handled, i.e., when a controller is built using an authentication identifier (e.g. `current_user`) that is the same as the controller's object
+  - note that when building a self-auth controller, the list view still behaves as-if it is a list but controller only has access to the auth object (e.g. `current_user`). You would really only need this for the edge case of a user updating their own record, or, as in the example, to use as the starting point for building the child portals.  
+  - another edge case in here that has been fixed involved creating a 'no field' form-- in the example, invoices are created using the "new" button and "save" button, even though the form has no editable fields for the user to input. In these edge cases, an invisible form field is inserted to make the form submission work correctly. This only happens for an action that has no inputable fields. 
+  - cleaner code for the `_form` output and also the `controller` output 
+
+#### 2022-01-23 - v0.4.6 -  `--no-list-labels` (flag; defaults false)
+(additional features in this release have been subsequently removed)
 
-#### 2022-12-30 - v0.4.2
+#### 2022-01-11 - v0.4.5 - buttons on smart layouts take up 1 bootstrap column each; fixes confirmation alert for delete buttons
+
+#### 2022-01-01 - v0.4.3 and 0.4.4 - adding fully email-based license, no activation codes required.
+
+#### 2022-12-30 - v0.4.2 -- Smart layouts introduced
 
 #### 2021-12-15 - v0.4.1
 
@@ -720,11 +759,10 @@ Obviously, the created controller will always have this base controller as its s
 
 #### 2021-12-12 - v0.3.9 - Magic Buttons
 
-
 #### 2021-12-11 - v0.3.5 - Downnesting
 
 
-#### 2021-11-27 - v0.2.9E   — EXPERIMENTAL
+#### 2021-11-27 - v0.2.9E   (experimental)
                      - Downnesting
                      - Adds spec coverage support for enums
                      - Several more fixes; this is preparation for forthcoming release.
@@ -732,7 +770,6 @@ Obviously, the created controller will always have this base controller as its s
 
 #### 2021-10-11 - v0.2.6 - many additional automatic fixes for default Rails installation 6 or 7 for the generate hot_glue:install command
 
-
 #### 2021-10-10 - v0.2.5 - this version is all about developer happyness:
                             - significant fixes for the behavioral (system) specs. they now create new & update interactions
                             for (almost) all field types
@@ -746,9 +783,9 @@ Obviously, the created controller will always have this base controller as its s
 
 #### 2021-09-30 - v0.2.3 - fixes ERB output for show-only fields; fixes flash_notices for erb or haml; adds @stimulus_syntax flag for delete confirmations with stimulus
 
-#### 2021-09-27  - v0.2.2 - Fixes some issues with related fields; unlocks Rails 7 in Gemspec file
+#### 2021-09-27 - v0.2.2 - Fixes some issues with related fields; unlocks Rails 7 in Gemspec file
 
-#### 2021-09-20  - v0.2.1 - Fixes nesting behavior when using gd option
+#### 2021-09-20 - v0.2.1 - Fixes nesting behavior when using gd option
 
 #### 2021-09-06 - v0.2.0 - ERB or HAML; use the option --markup=erb or --markup=haml (default is now erb)
 
@@ -776,9 +813,6 @@ Obviously, the created controller will always have this base controller as its s
 
 
 
-
-
-
 # HOW THIS GEM IS TESTED
 
 SETUP:
@@ -796,16 +830,29 @@ The DUMMY testing DOES NOT test the actual functionality of the output code (it
 
 
 # DATABASE
+being able to run `rake spec` at the root of this repo is achieved using
+```
+ln -s  spec/dummy/db/schema.rb db/schema.rb
+```
+
+ 
 
-`cd spec/dummy`
-`rails db:drop`
-`rails db:create`
-`rails db:migrate`
-`RAILS_ENV=test rails db:migrate`
+Run rspec as
+``` 
+rake spec
+```
+Or with test coverage report:
 
-`cd ../..`
+```
+COVERGE=on rake spec
+
+```
 
-take note that when running the spec at the root of the repo you are initializing the Dummy app, which will use the 
-SQLite database in spec/dummy/database/
+--
+--
+ 
+Test coverage as of 2022-02-06
+ 
+![Screen Shot 2022-02-06 at 10 26 36 PM](https://user-images.githubusercontent.com/59002/152719855-fdd3da6d-8348-44b9-8753-b0e73eee8065.png)