Merge branch 'development'

docs/develop/Code/Features/scaffolding.md

@@ -92,9 +92,11 @@ Refer to [Rails migration documentation](https://guides.rubyonrails.org/active_r
 
 Within `config/routes/data.rb` find the `resource:` block for your new model (e.g. search for `organizations`) then:
 
-* Add `concerns [:data_routes]`
+* Ensure the `resources:` block is present if it wasn't scaffolded
+* Include `concerns [:data_routes]`
 * Move the code block into alphabetic order within the file
 
+Your block should look like:
 ```Ruby
   resources :organizations do
     concerns [:data_routes]
@@ -116,6 +118,7 @@ In `app/models/organization.rb`:
   # ... others
   include Shared::IsData
 ```
+    * You'll need to remove `belongs_to :project_id` if present, it's convered in the `Housekeeping`
     * If the model is community:
 ```Ruby
   include Housekeeping::Users
@@ -125,15 +128,19 @@ In `app/models/organization.rb`:
 ```
 * If the model as a `project_id` register it in the `MANIFEST` constant in [`app/models/project.rb`](https://github.com/SpeciesFileGroup/taxonworks/blob/development/app/models/project.rb)
 * Add at least 1-2 model tests (e.g. in `spec/models/organization_spec.rb`)
-* Register the model in [`config/interface/hub/data.yml`](https://github.com/SpeciesFileGroup/taxonworks/blob/development/config/interface/hub/data.yml). See details therein.
+
 
 :::tip
 At this point when you restart the server you should see a clickable card on `Data`
 :::
 
+## Config
+
+* Register the model in [`config/interface/hub/data.yml`](https://github.com/SpeciesFileGroup/taxonworks/blob/development/config/interface/hub/data.yml). See details therein.
+
 ## Controller
 
-Controllers are at, for example app/controllers/organizations_controller.  See the `otus_controller` for example patterns.
+Controllers are at `app/controller/`, for example `app/controllers/organizations_controller.rb`.  See the `otus_controller.rb` for example patterns.
 
 :::tip
 Rails has naming conventions for pluralization. Models are singular, controllers are plural.
@@ -149,11 +156,35 @@ class OrganizationsController < ApplicationController
 ```Ruby
   include DataControllerConfiguration::SharedDataControllerConfiguration
 ```
-* Update `def index` to use `@recent_objects` 
+* Add the pagination `after_action` pattern if required
+* Update `def index` to stub in some variables for an html and json response  (these become more sophisticated down the road):
+  * Use `@recent_objects` in the html response
+  * Use `@organizations` (or the model name) in the json response
+  * Together it will look something like this:
+```Ruby
+  def index
+    respond_to do |format|
+      format.html do
+        @recent_objects = Organization.where(project_id: sessions_current_project_id).order(updated_at: :desc).limit(10)
+        render '/shared/data/all/index'
+      end
+      format.json {
+        @sounds = Organization.where(project_id: sessions_current_project_id)
+          .page(params[:page])
+          .per(params[:per])
+      }
+    end
+  end
+```
+
 * Ensure `.permit()` calls permit writable attributes
 * Add an`autocomplete` action (method)
 * Add a`list` action
 
+:::tip
+At the point of updating the controller running the application and clicking through the model's card will raise errors on things missed or stubbed in error above.
+:::
+
 ### Controller tests
 
 _We do not add new controller specs, but the generated specs are easily modified to work, so we typically modify them to follow an overall pattern, then leave them alone. The pattern has variously evolved, but generally it follows something like that below._
@@ -208,9 +239,10 @@ Reference existing patterns in `app/views/otus/` for details.
 
 * Delete `index.html.erb`
 * Follow Rails conventions for `_form.html.erb`. See any other `_form.html.erb` for TaxonWorks conventions and markup. Replace the partials as needed (e.g. `/shared/errors`)
-* Ensure you have JSON responses for `show` and `index` actions, see `_attributes.json.jbuilder` pattern in most models
+* Ensure you have JSON responses for `show` and `index` actions
+  * Rename the `_organization.json.jbuilder` partial to `_attributes.json.jbuilder`
 * Most models can use an autocomplete, add `autocomplete.json.jbuilder`.
-* Update `show.html.erb` to use a shared view. 
+* Update `show.html.erb` to use a shared view replacing everything with `<%= render(partial: 'shared/data/project/show', locals: {object: @organization}) -%>`
 * Add `_attributes.html.erb` so that shared view can render attributes
 * Add a `list.html.erb`
 

docs/guide/Manual/Keys/README.md

@@ -40,11 +40,108 @@ These keys can be used on-or offline using the [pinpoint](https://github.com/Spe
 TaxonWorks exports print-ready formats with features including:
 * Auto numbering of the key on demand 
 * Markdown markup for eBook or further styling (coming)
-
 ### API 
 
 Standard keys can be exported as one JSON object.  This object is what is used by pinpoint.  It could also be used as a data-object in a larger integrated or aggregating format.  The model is in progress.
 
+### Tutorial: Standard Key
+
+What follows are the steps for entering data to create a basic dichotomous (standard) key. Please note carefully the logic of when and where key elements are entered as these intricacies are critical.
+
+The instructions that follow will allow you to recreate the key shown here:
+
+```
+Key to the males of Rhopalopsole species from Yunnan Province of China from 
+Yang, X. & Du, Y.-Z. (2024) A new species of Rhopalopsole (Plecoptera, Leuctridae) from Yunnan Province, China. Biodiversity Data Journal, 12, e134258: 10 pages. https://doi.org/10.3897/bdj.12.e134258.
+
+1 Lateral processes of tergum 10 bifurcate…………………………………………………….... 2
+
+– Lateral processes of tergum 10 not bifurcate……………………………………………….… 4
+
+2 Epiproct triangulate in dorsal view ………………………….R. brevidigitata Qian & Du, 2017
+
+– Epiproct not triangulated in dorsal view…………………………………..……………………. 3
+
+3 Antennae with long hairs…………………………………….…R. sinensis Yang & Yang, 1993
+
+– Antennae without long hairs……………………………..….R. yunnana Sivec & Harper, 2008
+
+4 Subanal lobes are divided into three parts……………………..…….R. dentiloba (Wu, 1973)
+
+– Subanal lobes are not divided into three parts…………………………..……………………. 5
+
+5 Lateral projections of tergum 10 nearly parallel-sided in lateral view……...R. emeishan Sivec & Harper, 2008
+
+– Lateral projections of tergum 10 gradually taper towards the apex in the lateral view……. 6
+
+6 Tergum 10 with central sclerite is about the same length and width…… R. faciursina Qian & Du, 2017
+
+– Tergum 10 with central sclerite distinctly broader than long…………………………………. 7
+
+7 Tergum 9 with a T-shaped weakly sclerotised area in the median……. R. siculiformis Qian & Du, 2012
+
+– Tergum 9 without a T-shaped weakly sclerotised area in the median………………..…….. 8
+
+8 The cercus with a small spine and tergum 9 is mostly sclerotised, somewhat less so in the median pentagonal area with a paired posterior process with sensilla basiconica………………………………………………………R. dulongjianga Yang & Du, sp. nov.
+
+– The cercus without spine and tergum 9 without a pentagonal weakly sclerotised area in the median………………………..R. bispina (Wu, 1949)
+```
+
+Starting from `New Dichotomous key` task:
+
+* In the `Key metadata` box, enter a `title` and `description`.
+* `Search` for and `select` the taxon for which the key was written, in this case the genus _Rhopalopsole_.
+* Check the `Is publicly accessible` box.
+* `Save` the metadata, then
+* Enter the `citation` for the source of the key using the `radial annotator` that will appear in the upper right corner.
+
+#left[**Legend**: Elements of Key Metadata](https://sfg.taxonworks.org/s/0jo5bf)
+
+* Next type `1` in the `couplet from citation` box.
+* Cut and paste couplet 1a into the top left text box, and 1b into the top right text box.
+* Click the `Update` button.
+
+#left[**Legend**: Entering couplet 1](https://sfg.taxonworks.org/s/lvvz60)
+
+* Note that since 1a (left column) directs the user to couplet 2, `create and edit the next couplet` must originate from the left hand column. 
+  * Click on `create and edit the next couplet` in the left column.
+* Type `2` in the `couplet from citation` box.
+* Cut and paste couplet 2a into the top left text box, and 2b into the top right text box.
+* Search for _`brevidigitata`_ in the left OTU box and `select` the correct one from those shown.
+* Click the `Update` button.
+
+#left[**Legend**: Entering couplet 2](https://sfg.taxonworks.org/s/06f0yv)
+
+* Now, in the `Previous couplets` box, `click` on couplet 1.
+* This time, in the right hand column (couplet 1b), click on `Create and edit the next` couplet.
+* Note that couplet 1b directs the user to couplet 4. 
+  * Type `4` in the `Couplet number from citation` box.
+* Cut and paste couplet 4a into the top left text box, and 4b into the top right text box.
+* Search for _`dentilobata`_ in the left OTU box and `select` the correct one from those shown.
+* Click the `Update` button.
+
+* In the `Previous couplets` box, `click` on `couplet 1`. 
+  * Then go to bottom of left column and `click` on `couplet 2` to return to couplet 2.
+* Note that couplet 2b directs the user to couplet 3. Go to top of right column and `click` on `Create and edit next couplet`.
+* Type `3` in the `Couplet number from citation` box.
+* Cut and paste couplet 3a into the top left text box, and 3b into the top right text box.
+
+* Search for _`sinensis`_ in the left OTU box and `select` the correct one from those shown.
+* Search for _`yunnana`_ in the right OTU box and `select` the correct one from those shown.
+* Click the `Update` button.
+
+#left[**Legend**: Entering couplet 3](https://sfg.taxonworks.org/s/0vdwvg)
+
+* In the `Previous couplets box`, click on `couplet 1`.
+* Go to bottom of right column and `click` on `Couplet 4` to return to couplet 4.
+* Note that couplet 4b directs the use to 5, so go to top of right column and `click` on `Create and edit next couplet`.
+* Type `5` in the `Couplet number from citation` box.
+* Cut and paste couplet 5a into the top left text box, and 5b into the top right text box.
+* Search for _`emeishan`_ in the left OTU box and `select` the correct one from those shown.
+* Click the `Update` button.
+
+Enter the rest of the couplets following the above pattern. Once the key is complete use the `radial navigator` button in the upper right to go to `Use dichotomous key` to check your work.
+
 ## Multi-entry keys
 
 An observation matrix in TaxonWorks can be used as a multi-entry key within or outside of TaxonWorks using the app [distinguish](https://github.com/SpeciesFileGroup/distinguish). Internally this integration extends the role of a multi-entry key engine far beyond its use in diagnosing taxa.  For example the interface can be used to: