Merge pull request rails#49114 from gmcgibbon/cpk_id_guides

Add composite primary key examples to Rails guides

Author: eileencodes

guides/source/action_controller_overview.md

@@ -186,6 +186,34 @@ In this case, when a user opens the URL `/clients/active`, `params[:status]` wil
 [`controller_name`]: https://api.rubyonrails.org/classes/ActionController/Metal.html#method-i-controller_name
 [`action_name`]: https://api.rubyonrails.org/classes/AbstractController/Base.html#method-i-action_name
 
+### Composite Key Parameters
+
+Composite key parameters contain multiple values in one parameter. For this reason, we need to be able to extract each value and pass them to Active Record. We can leverage the `extract_value` method for this use-case.
+
+Given the following controller:
+
+```ruby
+class BooksController < ApplicationController
+  def show
+    # Extract the composite ID value from URL parameters.
+    id = params.extract_value(:id)
+    # Find the book using the composite ID.
+    @book = Book.find(id)
+    # use the default rendering behaviour to render the show view.
+  end
+end
+```
+
+And the following route:
+
+```ruby
+get '/books/:id', to: 'books#show'
+```
+
+When a user opens the URL `/books/4_2`, the controller will extract the composite
+key value `["4", "2"]` and pass it to `Book.find` to render the right record in the view.
+The `extract_value` method may be used to extract arrays out of any delimited parameters.
+
 ### `default_url_options`
 
 You can set global default parameters for URL generation by defining a method called `default_url_options` in your controller. Such a method must return a hash with the desired defaults, whose keys must be symbols:

guides/source/action_view_helpers.md

@@ -468,6 +468,9 @@ url_for @profile
 
 url_for [ @hotel, @booking, page: 2, line: 3 ]
 # => /hotels/1/bookings/1?line=3&page=2
+
+url_for @post # given a composite primary key [:blog_id, :id]
+# => /posts/1_2
 ```
 
 #### link_to
@@ -481,6 +484,9 @@ when passing models to `link_to`.
 ```ruby
 link_to "Profile", @profile
 # => <a href="/profiles/1">Profile</a>
+
+link_to "Book", @book # given a composite primary key [:author_id, :id]
+# => <a href="/books/2_1">Book</a>
 ```
 
 You can use a block as well if your link target can't fit in the name parameter. ERB example:

guides/source/form_helpers.md

@@ -236,6 +236,43 @@ There are several things to notice here:
 
 TIP: Conventionally your inputs will mirror model attributes. However, they don't have to! If there is other information you need you can include it in your form just as with attributes and access it via `params[:article][:my_nifty_non_attribute_input]`.
 
+#### Composite primary key forms
+
+Forms may also be built with composite primary key models. In this case, the form
+building syntax is the same with slightly different output.
+
+Given a `@book` model object with a composite key `[:author_id, :id]`:
+
+```ruby
+@book = Book.find([2, 25])
+# => #<Book id: 25, title: "Some book", author_id: 2>
+```
+
+The following form:
+
+```erb
+<%= form_with model: @book do |form| %>
+  <%= form.text_field :title %>
+  <%= form.submit %>
+<% end %>
+```
+
+Outputs:
+
+```html
+<form action="/books/2_25" method="post" accept-charset="UTF-8" >
+  <input name="authenticity_token" type="hidden" value="..." />
+  <input type="text" name="book[title]" id="book_title" value="My book" />
+  <input type="submit" name="commit" value="Update Book" data-disable-with="Update Book">
+</form>
+```
+
+Note the generated URL contains the `author_id` and `id` delimited by an underscore.
+Once submitted, the controller can [extract each primary key value][] from parameters
+and update the record as it would with a singular primary key.
+
+[extract each primary key value]: action_controller_overview.html#composite-key-parameters
+
 #### The `fields_for` Helper
 
 The [`fields_for`][] helper creates a similar binding but without rendering a