hot-glue 0.6.19 → 0.6.21

data/README.md

@@ -321,6 +321,166 @@ TitleCase class name of the thing you want to build a scaffolding for.
 
 (note: Your `Thing` object must `belong_to` an authenticated `User` or alternatively you must create a Gd controller, see below.)
 
+
+## FLAGS (Options with no values)
+These options (flags) also uses `--` syntax but do not take any values. (Notice no equal sign.) Everything is assumed (default) to be false unless specified.
+
+
+### `--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.
+
+
+
+### `--god` or `--gd`
+
+Use this flag to create controllers with no root authentication. You can still use an auth_identifier, which can be useful for a meta-leval authentication to the controller.
+
+For example, FOR ADMIN CONTROLLERS ONLY, supply a auth_identifier and use `--god` flag.
+
+In Gd mode, the objects are loaded directly from the base class (these controllers have full access)
+```
+def load_thing
+    @thing = Thing.find(params[:id])
+end
+
+```
+
+### `--button-icons` (default is no icons)
+You can specify this either as builder flag or as a config setting (in `config/hot_glue.yml`)
+Use `font-awesome` for Font Awesome or `none` for no icons.
+
+
+### `--specs-only`
+
+Produces ONLY the controller spec file, nothing else.
+
+
+### `--no-specs`
+
+Produces all the files except the spec file.
+
+
+### `--no-paginate` (default: false)
+
+Omits pagination. (All list views have pagination by default.)
+
+### `--paginate-per-page-selector` (default: false)
+
+Show a small drop-down below the list to let the user choose 10, 25, or 100 results per page.
+
+
+### `--no-list`
+
+Omits list action. Only makes sense to use this if want to create a view where you only want the create button or to navigate to the update screen alternative ways. (The new/create still appears, as well the edit, update & destroy actions are still created even though there is no natural way to navigate to them.)
+
+
+
+### `--no-create`
+
+Omits new & create actions.
+
+### `--no-delete`
+
+Omits delete button & destroy action.
+
+### `--no-controller`
+
+Omits controller.
+
+### `--no-list`
+
+Omits list views.
+
+`--new-button-position` (above, below; default: above)
+Show the new button above or below the list.
+
+`--downnest-shows-headings` (default: false)
+Show headings above downnested portals.
+
+
+### `--big-edit`
+
+If you do not want inline editing of your list items but instead want to fallback to full-page style behavior for your edit views, use `--big-edit`.
+
+The user will be taken to a full-screen edit page instead of an edit-in-place interaction.
+
+When using `--big-edit`, any downnested portals will be displayed on the edit page instead of on the list page.
+
+Big edit makes all edit and magic button operations happen using `'data-turbo': false`, fully reloading the page and submitting HTML requests instead of TURBO_STREAM requests.
+
+Likewise, the controller's `update` action always redirects instead of using Turbo.
+
+
+### `--display-list-after-update`
+
+After an update-in-place normally only the edit view is swapped out for the show view of the record you just edited.
+
+Sometimes you might want to redisplay the entire list after you make an update (for example, if your action removes that record from the result set).
+
+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.
+
+### `--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` (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.
+
+This happens using two interconnected mechanisms:
+
+1) by default, all Hot Glue scaffold is wrapped in `turbo_frame_tag`s. The id of these tags is your namespace + the Rails dom_id(...). That means all Hot Glue scaffold is namespaced to the namespaces you use and won't collide with other turbo_frame_tag you might be using elsewhere
+
+2) by appending **model callbacks**, we can automatically broadcast updates to the users who are using the Hot Glue scaffold. The model callbacks (after_update_commit and after_destroy_commit) get appended automatically to the top of your model file. Each model callback targets the scaffold being built (so just this scaffold), using its namespace, and renders the line partial (or destroys the content in the case of delete) from the scaffolding.
+
+please note that *creating* and *deleting* do not yet have a full & complete implementation: Your pages won't re-render the pages being viewed cross-peer (that is, between two users using the app at the same time) if the insertion or deletion causes the pagination to be off for another user.
+
+
+### `--no-list-label`
+Omits list LABEL itself above the list. (Do not confuse with the list heading which contains the field labels.)
+
+Note that list labels may  be automatically omitted on downnested scaffolds.
+
+
+### `--no-list-heading`
+
+Omits the heading of column names that appears above the 1st row of data.
+
+### `--include-object-names`
+
+When you are "Editing X" we specify that X is a ___ (author, book, room, etc)
+
+e.g. "Editing author Edgar Allan Poe" vs "Editing Edgar Allan Poe"
+
+Can also be specified globally in `config/hot_glue.yml`
+
+## Nav Templates and `--no-nav-menu`
+At the namespace level, you can have a file called `_nav.html.erb` to create tabbed bootstrap nav
+
+To create the file for the first time (at each namespace), start by running
+```
+bin/rails generate hot_glue:nav_template --namespace=xyz
+```
+
+This will append the file `_nav.html.erb` to the views folder at `views/xyz`. To begin, this file contains only the following:
+
+```
+<ul class='nav nav-tabs'>
+</ul>
+```
+
+Once the file is present, any further builds in this namespace will:
+
+1) Append to this `_nav.html.erb` file, adding a tab for the new built scaffold
+2) On the list view of the scaffold being built, it will include a render to the _nav partial, passing the name of the currently-viewed thing as the local variable `nav` (this is how the nav template knows which tab to make active).
+```
+<%= render partial: "owner/nav", locals: {nav: "things"} %>
+```
+(In this example `owner/` is the namespace and `things` is the name of the scaffold being built)
+
+To suppress this behavior, add `--no-nav-menu` to the build command and the _nav template will not be touched.
+
+
+
 ## Options With Arguments
 
 All options begin with two dashes (`--`) and a followed by an `=` and a value
@@ -348,7 +508,6 @@ end
 
 ```
 
-
 ### `--nested=`
 
 This object is nested within another tree of objects, and there is a nested route in your `routes.rb` file with the specified parent controllers above this controller. When specifying the parent(s), be sure to use **singular case**.
@@ -771,8 +930,7 @@ Hot Glue gives you automatic field level access control if you create `*_able?`
 The `*_able?` method should return true or false depending on whether or not the field can be edited. No distinction is made between the `new` and `edit` contexts. You may check if the record is new using `new_record?`.
 
 
-**The `*_able?` method is used by Hot Glue only on the new and edit actions. You must incorporate it into the policy's `update?` method as in the example, or else no guard will check prevent the user doesn't pass a value to input it anyway.**
-
+**The `*_able?` method is used by Hot Glue only on the new and edit actions and also affects the strong parameters, so you no longer need to incorporate it into your policy's `update?` method
 
 Add one `*_able?` method to the policy for each field you want to allow field-level access control. 
 
@@ -781,12 +939,8 @@ Replace `*` with the name of the field you want under access control. Remember t
 When the method returns true, the field will be displayed to the user (and allowed) for editing. 
 When the method returns false, the field will be displayed as read-only (viewable) to the user.
 
-Important: These special fields determine *only* display behavior (new and edit), not create and update. 
-
-For create & update field-level access control, you must also implement the `update?` method on the Policy. Notice how in the example policy below, the `update?` method uses the `name_able?` method when it is checking if the name field can be updated, tying the feature together.
-
 You can set Pundit to be enabled globally on the whole project for every build in `config/hot_glue.yml` (then you can leave off the `--pundit` flag from the scaffold command)
-`:pundit_default:` (all builds in that project will use Pundit)
+`:pundit:` (all builds in that project will use Pundit)
 
 
 Here's an example `ThingPolicy` that would allow **editing the name field** only if:
@@ -808,14 +962,11 @@ class ThingPolicy < ApplicationPolicy
   end
   
   def update?
-     if !@user.is_admin?
-       return false
-    elsif record.name_changed? && !name_able?
-      record.errors.add(:name, "cannot be changed.")
-      return false
-    else
-      return true
-    end
+    !@user.is_admin?
+  end
+    
+  def edit?
+    !@user.is_admin?
   end
   
   class Scope < Scope
@@ -828,12 +979,11 @@ class ThingPolicy < ApplicationPolicy
 end
 ```
 
-
 Because Hot Glue detects the `*_able?` methods at build time, if you add them to your policy, you will have to rebuild your scaffold.
 
 
-### `--pundit-policy-override`
-if you use the flag `--pundit-policy-override` your controller operations will bypass the invisible (pundit provided) access control and use the pundit policy you specify.
+### `--pundit-policy-override=`
+if you pass a custom pundit class to `--pundit-policy-override=` your controller operations will bypass the invisible (pundit provided) access control and use the pundit policy you specify.
 
 example
 
@@ -849,6 +999,8 @@ If provided, the output code looks something like (in this example, showing the
 ```
 
 
+
+
 ### `--show-only=`
 (separate field names by COMMA)
 
@@ -860,7 +1012,7 @@ IMPORTANT: By default, all fields that begin with an underscore (`_`) are automa
 This is 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.
 
 
-### `--update-show-only`
+### `--update-show-only=`
 (separate field names by COMMA)
 
 • Make this field appear as viewable only for the edit action (and not allowed in the update action). 
@@ -909,18 +1061,19 @@ Remember, if there's a corresponding `*_able?` method on the policy, it will be
 
 As shown in the method `name_able?` of the example ThingPolicy above, if this field on your policy returns true, the field will be editable. If it returns false, the field will be viewable (read-only).
 
-
-### `--hidden`
-
+### `--hidden=` (affects both create + update actions)
+### `--create-hidden=`
+### `--update-hidden=`
+TODO: RENAME ME TO INVISIBLE 
 Separate list of fields. 
 
-These fields will be hidden from the form but will exist as hidden_field, and so the update will still work.
+These fields will exist on the create or update form exist as hidden_field, and so the update will still work._
 
 
 EXAMPLE:
 
 ```
-bin/rails generate hot_glue:scaffold Wrapper --namespace='account_dashboard' --no-nav-menu --big-edit --smart-layout --stimmify --hidden=raw_source
+bin/rails generate hot_glue:scaffold Wrapper --namespace='account_dashboard' --no-nav-menu --big-edit --smart-layout --stimmify --invisible=raw_source
 ```
 
 In the `wrappers` folder, I am using a special sticky partial `_edit_within_form.html.erb`, which contains code preserved from build-to-build and included in the form:
@@ -992,7 +1145,77 @@ Notice we are also using `--stimmify` to decorate the form with a Stimulus contr
 
 The code above uses Code Mirror to act as a code editor, which requires pulling the value off the hidden form element (putting it into the code mirror interface) and pushing it back into the hidden form element when the Submit button is clicked.
 
+### `--invisible=` 
+### `--create-invisible=`
+### `--update-invisible=`
+(two lists are maintained: create and update. any fields on the unnamed invisible list will be invisible on both create and update actions)
+
+If a field is on the invisible list, the policy will be checked for a `_able?` method.
+If this method returns true, displayed like a normal editable field.
+
+If the policy doesn't allow editing, this field will be made invisible: completely removed from the form.
 
+Like show only, these will check for `*_able?` methods on the object or Policy and will only display the field if the method returns true.
+
+It will also block the field from being updated on the backend, so don't use this if you want to create a hidden_field tag but still allow the controller to update it. (For that, see `--hidden=`.)
+
+
+Like show-only, note special behavior with pundit.
+
+A field can be marked invisible and show-only, in which case the invisible rule take prescedence when the access control is denied (field removed from form) but th show-only rule takes prescedance when the access control is granted,
+
+Hidden can be used with invisible. In this case, the access control will be applied to the field. When editable, the hidden field output will be used.
+
+Must be used with Pundit. Without pundit, see other alternatives: hidden fields, show only fields, or just removing the field completely by using the exclude list or leaving it off the include list. 
+
+|                                        |                                                                                                                                                                                                                                                          | Pundit                                                                                                                                                                                                                                                          |   |   |
+|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|---|
+| fields not on any of these other lists | Included as editable on both the create + update actions or as viewable if Policy access control returns false                                                                                                                                           | Without pundit, everything is editable. With pundit, the Policy is checked for an `_able?` method for each field at build time. When this method returns false, the field is viewable.                                                                          |   |   |
+| Show only                              | Viewable only (non-editable) on both create + edit/update overriding whatever Policy returns.                                                                                                                                                            | Without pundit, this field is viewable only. Overrides whatever policy returns.                                                                                                                                                                                 |   |   |
+| Update Show only                       | Viewable only on the update screen or if Pundit doesn't allow editing                                                                                                                                                                                    | Same as above but apply only to the update screen.                                                                                                                                                                                                              |   |   |
+| Invisible                              | Displayed in the HTML output and received by the controller for create or update action but shown as a hidden_field on the HTML, invisible to the user. You should use this if you want to construct your own form input or set the value via Javascript | Cannot be used without Pundit. With pundit, fields editable via the policy are editable on the screen (unless they are also show-only, in which case they are visible) and non-editable via the policy are made invisible (completely removed) from the screen. |   |   |
+| Hidden                                 | Not displayed or updatable if the field respond false to _able? or the Policy doesn't allow.                                                                                                                                                             | Unrelated to pundit Policy                                                                                                                                                                                                                                      |   |   |
+|                                        |                                                                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                 |   |   |
+
+
+Pundit calls the policy for every action, including the index action. In these cases it passes an association instead of a single record.
+
+Normally, field level access control that applies for show only and invisible is affects each record, in the list view, new page, or edit page.
+
+For that reason, your `_able?` methods may check the individual records, except in the case of the `index` action for which the pundit policy has no individual record.
+
+For these special cases, you might want to hide the entire column itself when the `_able?` return false on the association call (not in the context any of any record).
+
+You'd want to do this for a global switch, unrelated to the record, to show or hide the column itself. When using invisible fields, the column headings are check against the policy's `_able?` fields, too, but since this called on the list, the entire set of objects being returned by the list is passed to the policy. (For example `policy(@things)`)
+
+This makes it impossible to make your access control depend solely on the record itself, so can be used only for context-based access control that is applied to the column headings. 
+
+
+In a case like this, you'll want the `_able?` method on the policy to know if the object is a record or many records.
+
+```
+class ThingPolicy  < ApplicationPolicy
+  attr_reader :user, :thing
+
+  def initialize(user, thing)
+    @user = user
+    @thing = thing 
+  end
+
+  def ccc_able?
+    if thing.is_a?(Thing) # a thing is not a Thing when it is an active relation of many things
+      !!thing.bbb # show or hide ccc based on whether or not bbb is true
+    else 
+      current_user.is_admin? # show or hide the column heading for ccc based on whether or not the current user is an admin
+    end
+  end
+  # more policy method here ...
+end
+```
+Here, for all CRUD actions, the object is a thing, and so the editablility of ccc is dependent on bbb being true.
+If thing is not a Thing, then it is active relation (so this applies to the column headings) and we show it only to admins. 
+
+Remember, since the `_able?` methods are not otherwise called during Pundit's index cycle, this applies only to the list column headings and has no bearing on create, update, read, delete for which the access control can be anything you want that is available to the Poilcy. 
 
 
 
@@ -1014,7 +1237,7 @@ and also fix any Rails apps created since October 2021 by fixing the Gemfile. De
 https://stackoverflow.com/questions/70671324/new-rails-7-turbo-app-doesnt-show-the-data-turbo-confirm-alert-messages-dont-f
 
 
-### `--magic-buttons` 
+### `--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 corresponding bang methods on your models.
@@ -1035,8 +1258,13 @@ Finally, you can raise an ActiveRecord error which will also get passed to the u
 
 For more information see [Example 6 in the Tutorial](https://school.jfbcodes.com/8188)
 
+You can also define methods on your model that have the same name as the button with `_able?` at the end.
+(Prior to v0.6.20, these methods expected names with `able?` but no underscore.)
+
+The button will be display as disabled if the method returns false.
+
 
-### `--downnest`
+### `--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.
@@ -1048,11 +1276,6 @@ 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.
-
-
 
 ### `--record-scope=`
 
@@ -1071,113 +1294,9 @@ scope :is_open, -> {where(state == 'open')}
 
 Now all records displayed through the generated controller 
 
-## FLAGS (Options with no values)
-These options (flags) also uses `--` syntax but do not take any values. Everything is assumed (default) to be false unless specified.
-
-### `--god` or `--gd`
-
-Use this flag to create controllers with no root authentication. You can still use an auth_identifier, which can be useful for a meta-leval authentication to the controller.
-
-For example, FOR ADMIN CONTROLLERS ONLY, supply a auth_identifier and use `--god` flag.
-
-In Gd mode, the objects are loaded directly from the base class (these controllers have full access)
-```
-def load_thing
-    @thing = Thing.find(params[:id])
-end
-
-```
-
-### `--button-icons` (default is no icons)
-You can specify this either as builder flag or as a config setting (in `config/hot_glue.yml`)
-Use `font-awesome` for Font Awesome or `none` for no icons.
-
-
-### `--specs-only`
-
-Produces ONLY the controller spec file, nothing else.
-
-
-### `--no-specs`
-
-Produces all the files except the spec file.
-
-
-### `--no-paginate` (default: false)
-
-Omits pagination. (All list views have pagination by default.)
-
-### `--paginate-per-page-selector` (default: false)
-
-Show a small drop-down below the list to let the user choose 10, 25, or 100 results per page.
-
-
-### `--no-list`
-
-Omits list action. Only makes sense to use this if want to create a view where you only want the create button or to navigate to the update screen alternative ways. (The new/create still appears, as well the edit, update & destroy actions are still created even though there is no natural way to navigate to them.)
-
-
-
-### `--no-create`
-
-Omits new & create actions.
-
-### `--no-delete`
-
-Omits delete button & destroy action.
-
-### `--no-controller`
-
-Omits controller.
-
-### `--no-list`
-
-Omits list views. 
-
-`--new-button-position` (above, below; default: above)
-Show the new button above or below the list.
-
-`--downnest-shows-headings` (default: false)
-Show headings above downnested portals.
-
-
-### `--big-edit`
-
-If you do not want inline editing of your list items but instead want to fallback to full-page style behavior for your edit views, use `--big-edit`. 
-
-The user will be taken to a full-screen edit page instead of an edit-in-place interaction.
-
-When using `--big-edit`, any downnested portals will be displayed on the edit page instead of on the list page. 
-
-Big edit makes all edit and magic button operations happen using `'data-turbo': false`, fully reloading the page and submitting HTML requests instead of TURBO_STREAM requests. 
-
-Likewise, the controller's `update` action always redirects instead of using Turbo.
-
-
-### `--display-list-after-update`
-
-After an update-in-place normally only the edit view is swapped out for the show view of the record you just edited.
-
-Sometimes you might want to redisplay the entire list after you make an update (for example, if your action removes that record from the result set).
-
-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.
-
-### `--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` (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.
-
-This happens using two interconnected mechanisms:
-
-1) by default, all Hot Glue scaffold is wrapped in `turbo_frame_tag`s. The id of these tags is your namespace + the Rails dom_id(...). That means all Hot Glue scaffold is namespaced to the namespaces you use and won't collide with other turbo_frame_tag you might be using elsewhere
-
-2) by appending **model callbacks**, we can automatically broadcast updates to the users who are using the Hot Glue scaffold. The model callbacks (after_update_commit and after_destroy_commit) get appended automatically to the top of your model file. Each model callback targets the scaffold being built (so just this scaffold), using its namespace, and renders the line partial (or destroys the content in the case of delete) from the scaffolding.
-
-please note that *creating* and *deleting* do not yet have a full & complete implementation: Your pages won't re-render the pages being viewed cross-peer (that is, between two users using the app at the same time) if the insertion or deletion causes the pagination to be off for another user.
 
 
-### `--related-sets`
+### `--related-sets=`
 
 Used to show a checkbox set of related records. The relationship should be a `has_and_belongs_to_many` or a `has_many through:` from the object being built.
 
@@ -1196,58 +1315,43 @@ Note this leaves open a privileged escalation attack (a security vulnerability).
 To fix this, you'll need to use Pundit with special syntax designed for this purpose. Please see [Example #17 in the Hot Glue Tutorial](https://school.jfbcodes.com/8188)
 
 
-## "Thing" Label
-
-Note that on a per model basis, you can also globally omit the label or set a unique label value using
-`@@table_label_singular` and `@@table_label_plural` on your model objects.
-
-You have three options to specify labels explicitly with a string, and 1 option to specify a global name for which the words "Delete ___" and "New ___" will be added.
-
-If no `--label` is specified, it will be inferred to be the Capitalized version of the name of the thing you are building, with spaces for two or more words.
-
-### `--label`
+### `--label=`
 
 The general name of the thing, will be applied as "New ___" for the new button & form. Will be *pluralized* for list label heading, so if the word has a non-standard pluralization, be sure to specify it in `config/inflictions.rb`
 
 If you specify anything explicitly, it will be used.
 If not, a specification that exists as `@@tabel_label_singular` from the Model will be used.
-If this does not exist, the Titleized (capitalized) version of the model name. 
+If this does not exist, the Titleized (capitalized) version of the model name.
 
-### `--list-label-heading`
+### `--list-label-heading=`
 The plural of the list of things at the top of the list.
 If not, a specification that exists as `@@tabel_label_plural` from the Model will be used.
 If this does not exist, the UPCASE (all-uppercase) version of the model name.
 
-### `--new-button-label`
-The button on the list that the user clicks onto to create a new record.
-(Follows same rules described in the `--label` option but with the word "New" prepended.)
+### `--new-button-label=`
+Overrides the button on the list that the user clicks onto to create a new record.
+(Default is to follow the same rules described in the `--label` option but with the word "New" prepended.)
 
-### `--new-form-heading`
+### `--new-form-heading=`
 The text at the top of the new form that appears when the new input entry is displayed.
-(Follows same rules described in the `--label` option but with the word "New" prepended.)
-
-### `--no-list-label`
-Omits list LABEL itself above the list. (Do not confuse with the list heading which contains the field labels.)
-
-Note that list labels may  be automatically omitted on downnested scaffolds.
-
+(Default follows the same rules described in the `--label` option but with the word "New" prepended.)
 
 ## Field Labels
 
-### `--form-labels-position` (default: `after`; options are **before**, **after**, and **omit**)
+### `--form-labels-position=` (default: `after`; options are **before**, **after**, and **omit**)
 By default form labels appear after the form inputs. To make them appear before or omit them, use this flag.
 
 See also `--form-placeholder-labels` to use placeolder labels.
 
 
-### `--form-placeholder-labels` (default: false)
+### `--form-placeholder-labels=` (default: false)
 
 When set to true, fields, numbers, and text areas will have placeholder labels.
 Will not apply to dates, times, datetimes, dropdowns (enums + foreign keys), or booleans.
 
 See also setting `--form-labels-position` to control position or omit normal labels.
 
-### `--inline-list-labels` (before, after, omit; default: omit)
+### `--inline-list-labels=` (before, after, omit; default: omit)
 
 Determines if field label will appear on the LIST VIEW. Note that because Hot Glue has no separate show route or page, this affects the `_show` template which is rendered as a partial from the LIST view.
 
@@ -1256,36 +1360,36 @@ Because the labels are already in the heading, this is `omit` by default. (Use w
 Use `before` to make the labels come before or `after` to make them come after. See Version 0.5.1 release notes for an example.
 
 
-### `--no-list-heading`
+### Code insertions
+Insert some code into the `new`, `create` or `update` action actions.
 
-Omits the heading of column names that appears above the 1st row of data.
+Wrapped in quotation marks when specified in the command line, and use semicolons to separate multiple lines of code.
+(Notice the funky indentation of the lines in the generated code. Adjust you input to get the indentation correct.)
 
-### `--include-object-names`
 
-When you are "Editing X" we specify that X is a ___ (author, book, room, etc)
 
-e.g. "Editing author Edgar Allan Poe" vs "Editing Edgar Allan Poe"
+#### `--code-before-create=`
 
-Can also be specified globally in `config/hot_glue.yml`
+called _after authorization_ but _before saving the new record_ 
+(which creates the record, or fails validation).
+Here you can do things like set default values, or modify the params before the record is saved.
 
+#### `--code-after-create=`
+is called after the record is saved (and thus has an id in the case of the create action).
 
-### Code insertions
+#### `--code-before-update=`
+is called in the `update` action _before_ it is saved.
+`
+#### `--code-after-update=`
+is called in the `update` action _after_ it is saved.
 
-`--code-before-create`
-`--code-after-create`
-`--code-before-update`
-`--code-after-update`
+#### `--code-after-new=`
+is called in the `new` after the .new() call
 
-Insert some code into the `create` action or `update` actions.
-The **before code** is called _after authorization_ but _before saving_ (which creates the record, or fails validation).
-The **after create** code is called after the record is saved (and thus has an id in the case of the create action).
-Both should be wrapped in quotation marks when specified in the command line, and use semicolons to separate multiple lines of code.
-(Notice the funky indentation of the lines in the generated code. Adjust you input to get the indentation correct.)
 
 
-## Searching
 
-### `--search` (options: simple, set, false predicate, default: false)
+### `--search=` (options: simple, set, false predicate, default: false)
 
 
 #### Set Search
@@ -1336,24 +1440,12 @@ Here's how you would add a search interface to Example #1 in the [Hot Glue Tutor
 bin/rails generate Book --include=name,author_id --search=set --search-fields=name,author_id
 ```
 
-
-
-
-
-#### Predicate
+#### Predicate Search
 NOT IMPLEMENTED YET
 TODO: implement me
 
 
-
-
-
-
-
-
-## Special Features
-
-### `--attachments`
+### `--attachments=`
 
 #### ActiveStorage Quick Setup
 (For complete docs, refer to https://guides.rubyonrails.org/active_storage_overview.html)
@@ -1397,7 +1489,7 @@ If it finds one, it will render thumbnails from the attachment variant `thumb`.
 
 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=` Long form syntax with 1 parameter
 
 **--attachments='_attachment name_{_variant name_}'** 
 
@@ -1417,7 +1509,7 @@ 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=` Long form syntax with 1st and 2nd parameters
 
 **--attachments='_attachment name_{_variant name_|_field for saving original filename_}'**
 
@@ -1431,7 +1523,7 @@ Note that the `orig_filename` is not part of the inputted parameters,  it simply
 
 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
+#### `--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.
 
@@ -1443,7 +1535,7 @@ If you leave the 2nd parameter blank when using the 3rd parameter, it will defau
 
 `--attachments='avatar{thumbnail||direct}'`
 
-#### `--attachments` Long form syntax with 4 parameters
+#### `--attachments=` Long form syntax with 4 parameters
 
 The final (4th) parameter should be `dropzone` to enable dropzone support for this attachment.
 
@@ -1647,32 +1739,18 @@ Always:
 
 Don't include this last line in your factory code. 
 
-## Nav Templates and `--no-nav-menu`
-At the namespace level, you can have a file called `_nav.html.erb` to create tabbed bootstrap nav 
-
-To create the file for the first time (at each namespace), start by running
-```
-bin/rails generate hot_glue:nav_template --namespace=xyz
-```
 
-This will append the file `_nav.html.erb` to the views folder at `views/xyz`. To begin, this file contains only the following:
+# SPECIAL FEATURES
 
-```
-<ul class='nav nav-tabs'>
-</ul>
-```
 
-Once the file is present, any further builds in this namespace will:
+## "Thing" Label
 
-1) Append to this `_nav.html.erb` file, adding a tab for the new built scaffold
-2) On the list view of the scaffold being built, it will include a render to the _nav partial, passing the name of the currently-viewed thing as the local variable `nav` (this is how the nav template knows which tab to make active). 
-```
-<%= render partial: "owner/nav", locals: {nav: "things"} %>
-```
-(In this example `owner/` is the namespace and `things` is the name of the scaffold being built)
+Note that on a per model basis, you can also globally omit the label or set a unique label value using
+`@@table_label_singular` and `@@table_label_plural` on your model objects.
 
-To suppress this behavior, add `--no-nav-menu` to the build command and the _nav template will not be touched.
+You have three options to specify labels explicitly with a string, and 1 option to specify a global name for which the words "Delete ___" and "New ___" will be added.
 
+If no `--label` is specified, it will be inferred to be the Capitalized version of the name of the thing you are building, with spaces for two or more words.
 
 
 ## Automatic Base Controller
@@ -1715,7 +1793,7 @@ Child portals have the headings omitted automatically (there is a heading identi
 
 
 
-# Note about enums
+## Note about enums
 
 The Rails 7 enum implementation for Postgres is very slick but has a counter-intuitive facet.
 
@@ -1760,7 +1838,7 @@ Now, your labels will show up on the front-end as defined in the `_labels` ("Is
 
 You can modify an enum so that instead of a drop down list, it displays a partial view that you must build. See the [v0.5.23 Release notes](https://github.com/hot-glue-for-rails/hot-glue#2023-10-01---v0523) for details.
 
-### Validation Magic
+## Validation Magic
 
 Use ActiveRecord validations or hooks to validate your data. Hot Glue will automatically display the errors in the UI.
 
@@ -1778,7 +1856,7 @@ end
 
 ```
 
-### Typeahead Foreign Keys
+## Typeahead Foreign Keys
 
 Let's go back to the first Books & Authors example.
 assuming you have created
@@ -1876,7 +1954,7 @@ This means that to find users within the search, the essential piece of informat
 --
 
 
-### TinyMCE
+## TinyMCE
 1. `bundle add tinymce-rails` to add it to your Gemfile
 
 2. Add this inside of your `<head>` tag (at the bottom is fine)
@@ -1954,6 +2032,41 @@ These automatic pickups for partials are detected at build time. This means that
 
 # VERSION HISTORY
 
+
+#### 2025-07-05 v0.6.21
+•Now use new code insertion `--code-after-new` for code that happens directly after `.new()` call. use semicolon (`;`) to create linebreaks; no reason why the factories should insert flash messages
+
+• removes duplicitous flash messages in factory context
+
+• adds documentation for `--code-before-create`, `--code-after-create`, `--code-before-update`, `--code-after-update` (these features were already implemented)
+
+• updates are now built using `.assign_attributes` followed by `.save` (previously, they were updated with one `.update()` call); this allows your Pundit policy to check if the changed values are valid and raise an exception if not allowed based on the changed data (can be checked on Rails models with `.changed` or `.changes`; see https://api.rubyonrails.org/classes/ActiveModel/Dirty.html)
+
+• Fixes to timezone aware input. If your `current_user` (or auth object) has a method `timezone`, your datetime and time inputs will be timezone-aware.
+
+If a timezone is present, datetimes & times will be converted from database-native UTC into the current user's timezone when displayed (either as viewable or editable)
+
+If a user puts a time into the interface, it is assumed to be in the user's timezone and is converted to UTC before being saved. 
+
+
+#### 2025-06-13 v0.6.20
+Breaking changes:
+• the setting in your hot_glue.yml file for `:pundit_default:` has been renamed just `:pundit:`.
+If you fail to rename it in your config file, hot glue will not build if it finds the old config setting.
+
+• previously magic methods had a ability method that was the name of the magic method + `able?` as one word.
+this has been renamed to `_able?` and you must fix your cooresponding magic method ability methods by adding the underscore
+
+
+New Features
+• adds new invisibilty feature with  `--invisible`, `--create-invisible`, and `--update-invisible` see docs above
+• changes previous `--hidden` into `--hidden`, `--create-hidden`, and `--update-hidden`. use hidden to apply to both fields
+• restores functionality of layout builder to magically distribute bootstrap 12 columns
+(4 columns use rows of 3 col widths; 2 columns use 6, 3 uses 4, etc). WHen using specified grouping mode, you
+probably want about 3 or 4 columns. When you have more than 5 it's difficult to build layouts that look good.
+
+
+
 #### 2025-06-10 v0.6.19
 
 • Fixes magic button output behavior to correctly show the string returned by the bang menthod