hot-glue 0.4.5 → 0.4.9

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,20 @@ 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 Hot Glue
+## [Licence Only Option Now Available](https://heliosdev.shop/p/hot-glue/?utm_source=github.com&utm_campaign=github_hot_glue_readme_page) **only $50 USD!**
+## [GET THE COURSE TODAY (includes Licence)](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 +55,39 @@ 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._
+_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._
 
 
-## 1. ADD RSPEC, FACTORY-BOT, AND FFAKER
+## 1. Rails 7 New App
 
-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'
-```
+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/)
 
-- run `rails generate rspec:install`
+`rails new --css=bootstrap --javascript=webpack --database=postgresql`
 
-- replace `application.css` with a new file (delete old contents) `application.scss`
+Confirm that both Stimulus and Turbo are working.
 
-THIS FILE CAN BE EMPTY, BUT WILL BE USED BY THEME INSTALLER
+**If using JSBundling, make sure to use the new `bin/dev rails` instead of the old `rails server` or else your Webpack will not compile.** 
 
-## 2. ADD BOOTSTRAP (OPTIONAL)
+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,22 +96,14 @@ Purchase a license at https://heliosdev.shop/hot-glue-license
 
 During in installation, you MUST supply a `--layout` flag.
 
-### `--layout` flag
-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)
+### `--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. 
 
-If you do NOT specify `--layout=bootstrap`, then `hotglue` will be assumed. When constructing scaffold with bootstrap layout (at this time Hot Glue peeks into config/hot_glue.yml to see what you've set there), your views come out with divs that have classes like .container-fluid, .row, and .col. You'll need to install Bootstrap separately, any way you like, but jQuery is not required as Hot Glue does not rely on jQuery-dependant Bootstrap features.
+It will install a config file that will save two preferences: layout (`hotglue` or `bootstrap`)
 
+The installer will create `config/hot_glue.yml`. 
 
-If instead you install Hot Glue (or switch the setting) using the default layout mode (`--layout=hotglue`),
-your scaffolding will be built using no-Bootstrap syntax: It has its own syntax with classes like
-`.scaffold-container`,
-`.scaffold-list`,
-`.scaffold-row`, and
-`.scaffold-cell`
-
-During the installation, if your `--layout` flag is left unspecified or set to `hotglue` you must also pass `--theme` flag.
+During the installation, if your `--layout` flag is set to `hotglue` you must also pass `--theme` flag.
 
 the themes are:
 • like_mountain_view (Google)
@@ -124,30 +111,76 @@ the themes are:
 • like_bootstrap (bootstrap 4 copy)
 • dark_knight (_The Dark Night_ (2008) inspired)
 • like_cupertino (modern Apple-UX inspired)
-• gradeschool (spiral bound/lined notebook inspired)
-
-Please note that the scaffold is ** built with different market up for boostrap**, so you cannot switch between the Bootstrap and Hotglue layouts without rebuilding the scaffold.
-
-(On the other hand, if you build within the Hotglue layout, all of the Hotglue theme files CAN be swapped out without rebuilding the scaffold.)
-
-The themes are just SCSS files installed into app/assets/stylesheets. You can tweak or modify or remove them after they get installed.
-
 
 ### `--markup` flag
 
-default is `erb`
+default is `erb`. IMPORTANT: As of right now, HAML and SLIM are not currently supported.
 
 
-## 3. RUN HOT-GLUE INSTALL:
 ### example installing ERB using Bootstrap layout:
 `rails generate hot_glue:install --markup=erb --layout=bootstrap`
 
 ### 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.
+
+
+
 
-##  3(B). Modify `application.html.erb`
-(THIS WAS AUTOMATICALLY DONE BY THE HOT GLUE INSTALLATION -- CONFIRM CHANGES ONLY)
+### Hot Glue Installer Notes 
+
+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 +189,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 +202,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 +223,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 +242,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 +258,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 +298,54 @@ end
 ```
 
 
-### `--nest=`
+### `--nested=`
+
+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`
 
-pass `--nest=` to denote a nested resources
+```
+resources :invoices do
+  resource :lines do
+end
+```
 
+`rails generate hot_glue:scaffold Invoice`
 
-`rails generate hot_glue:scaffold Line --nest=invoice`
+`rails generate hot_glue:scaffold Line --nested=invoice`
 
-In this example, it is presumed that the current user has_many :invoices, and that invoices have many :lines
 
+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.)
 
-For multi-level nesting use slashes to separate your levels of nesting. Remember, you should match what you have in your routes.rb file.
+#### 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`
 
-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:
+`rails generate hot_glue:scaffold Charge --nested=invoice/line`
+
+
+
+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 +359,37 @@ 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).
+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.  
+
 
-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).
+#### Optionalized Nested Parents
 
-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.
+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 duplicative routes to the same controller**. You can only use this feature with Gd controller.  
 
+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
+```
+
+Even though we have two routes pointed to invoices, both will go to the same controller (`invoices_controller.rb`)
+
+```
+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.
+
+
+                                                         
 ### `--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.
@@ -474,8 +413,6 @@ 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)
 
 
-
-
 ### `--auth_identifier=`
 
 Your controller will call a method authenticate_ (AUTH IDENTIFIER) bang, like:
@@ -549,22 +486,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 flag and then you may then have to deal with the over-stuffed layouts as explained. 
+
+
+
+### `--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 Bootstrap's 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=`
@@ -619,9 +613,14 @@ 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).
 
+Can now be created with more space (wider) by adding a `+` to the end of the downnest name
+- e.g. `--downnest=abc+,xyz`
+
+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
 
 
 
@@ -661,6 +660,18 @@ 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 at the top of the list.
+
+### `--no-list-heading`
+
+Omits the list heading. 
+
+(Note that on a per model basis, you can also globally omit the heading or set a unique value using 
+`@@table_label_singular` and `@@table_label_plural` on your model objects.)
+
 ### `--no-create`
 
 Omits create action.
@@ -681,7 +692,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)
 
 
 
@@ -692,26 +702,96 @@ HotGlue will copy a file named base_controller.rb to the same folder where it tr
 
 Obviously, the created controller will always have this base controller as its subclass. In this way, you are encouraged to implement functionality common to the *namespace* (shared between the controllers in the namespace), using this technique.
 
-## Field Types Supported
+## Special Table Labels
+
+If your object is very wordy (like MyGreatHook) and you want it to display in the UI as something shorter,
+add `@@table_label_plural = "The Things"` and `@@table_label_singular = "The Things"`. 
+
+Hot Glue will use this as the listing heading label and New record label. This affects only the UI only.
+
+You can also set these to `nil` to omit the labels completely. 
+
+Child portals have the headings omitted automatically (there is a heading identifying them already on the parent view where they get included), or you can use the `--no-list-heading` on any specific build. 
 
-- Integers that don't end with `_id`, they will be displayed as text fields.
-- 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/
 
-* shows in a size-aware container, i.e. in a bigger box if the field allows for more content
+## Field Types Supported
 
+- Integers that don't end with `_id`: displayed as input fields with type="number"
+- Foreign keys: 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.)
+  - Note:  if your foreign key has a nonusual class name, it should be using the `class_name:` in the model definition
+- 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/
 
 
 # VERSION HISTORY
 
-#### 2022-01-01 - v0.4.3 and 0.4.4 - adding fully email based license; no activation codes required
+#### 2022-02-14 - v0.4.9
+• Fixed issue building models with namespaced class names (e.g. `Fruits::Apple` and `Fruits::Bannana`). 
+  You can now build against these kinds of models natively (be sure to pass the full model name, with double-colon syntax). 
+
+• Also fixes issues when associations themselves were namespaced models.
+
+• The N+1 Killer (!!!) 
+    - N+1 queries for _any association_ built by the list are now automagically killed by the list controllers.
+    - Thanks to the work done back in Rails 5.2, Rails smartly uses either two queries to glob up the data OR one query with a LEFT OUTER JOIN if that's faster. You don't have to think about it. **Thanks Rails 5.2!**
+    - Hot Glue now adds `.includes(...)` if it is including an association when it loads the list view to eliminate the N+1s
+    - Bullet is still the best way to identify, find, & fix your N+1 queries is still highly recommended. https://github.com/flyerhzm/bullet 
+
+• Downnest children (portals) can now be created with more space (made wider) by adding one or more `+` to the end of the downnest name, denoting add 1 bootstrap column.
+    - e.g. `--downnest=abc+,xyz`
+
+    The "Abc" portal will take up 5 bootstrap columns and the Xyz portal will take up 4 columns. (++ to indicate 6, `+++` for 7, etc)
+
+• Now that you can expand the downnest child portal width, you can easily give them too much width taking up more than 12 bootstrap columns. 
+  The builder stops you from building if you have taken up too many bootstrap columns, are in _either_ **Smart Layout mode** or **Specified Grouping mode**.
+  However, this check is not in place if you are in neither mode, in which case you should watch out for building more than 12 bootstrap columns.
+
+• To give a special label to a model, add `@@table_label_plural = "The Things"` and `@@table_label_singular = "The Thing"`. 
+  This model will now have a list heading of "The Things" instead of its usual name. 
+  For 'create buttons' and the 'New' screen, the builder will use the singular setting. 
+  This affects all builds against that model and affects the UI (display) only. 
+  All route names, table names, and variables are unaffected by this.
+
+• You can also use `@@table_label_plural = nil` to set these tables to **omit** the label headings, or use the new flag...
+
+• `--no-list-heading` (defaults to false but note several conditions when list headings are now hidden)
+
+Omits the list heading. Note that the listing heading is omitted: 
+1) if there is no list, 
+2) if you set the `--no-list-heading` flag, 
+3) if the model has `@@table_label_plural = nil`, or 
+4) if you are constructing a nested child portal with only non-optionalized parents. 
+
+
+
+#### 2022-02-09 - v0.4.8.1 - Issue with Installer for v0.4.8
+    - There was an issue for the installer for v0.4.8. This new version v0.4.8.1 correts it.
+
+
+#### 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
+    
+
+#### 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-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
 
@@ -724,7 +804,7 @@ Obviously, the created controller will always have this base controller as its s
 #### 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 +812,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 +825,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 +855,6 @@ Obviously, the created controller will always have this base controller as its s
 
 
 
-
-
-
 # HOW THIS GEM IS TESTED
 
 SETUP:
@@ -796,16 +872,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
+```
+
+ 
+
+Run rspec as
+``` 
+rake spec
+```
+Or with test coverage report:
+
+```
+COVERGE=on rake spec
 
-`cd spec/dummy`
-`rails db:drop`
-`rails db:create`
-`rails db:migrate`
-`RAILS_ENV=test rails db:migrate`
+```
 
-`cd ../..`
+--
+--
+ 
+Test coverage as of 2022-02-14 (v0.4.9)
 
-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/
+![Screen Shot 2022-02-14 at 8 33 29 PM](https://user-images.githubusercontent.com/59002/153975911-30fa9c84-c8d8-49e7-bd5c-e2b958d6f10e.png)