From 943ebcb5f1459e5c2c9a75c08684c987939201f1 Mon Sep 17 00:00:00 2001 From: claudiob Date: Fri, 19 Dec 2014 12:49:50 -0800 Subject: Better docs for AV::RecordIdentifier This commit intends to clarify the scope of ActionView::RecordIdentifier methods `dom_id` and `dom_class`. Most of the current documentation comes from da257eb8 (7 years ago) when the decoupling of ActionView, ActiveRecord and ActiveModel was not a concern. Since then, steps have been taken to reach such decoupling, especially 8ca17926 which duplicated ActionController::ModelNaming into ActionView::ModelNaming explaining that: > These are just a simple helpers for decoupling Active Model, so it does not > make sense to extract it to Active Support, but the point is to decouple also > Action View and Action Pack As of today, ActionView::RecordIdentifier only includes `dom_id` and `dom_class` so it makes sense to explicitly document those two methods, and leaving the details of helpers like `div_for` in the corresponding files. Moreover, I think it's important to mention in the documentation that ActionView::RecordIdentifier **does not strictly depend on the ActiveRecord API**: any class `Post` implementing `post.to_key` and `post.model_name.param_key` will work. [ci skip] --- actionview/lib/action_view/record_identifier.rb | 60 +++++++++++++++++-------- 1 file changed, 42 insertions(+), 18 deletions(-) (limited to 'actionview/lib/action_view/record_identifier.rb') diff --git a/actionview/lib/action_view/record_identifier.rb b/actionview/lib/action_view/record_identifier.rb index 63f645431a..818a60103f 100644 --- a/actionview/lib/action_view/record_identifier.rb +++ b/actionview/lib/action_view/record_identifier.rb @@ -2,29 +2,53 @@ require 'active_support/core_ext/module' require 'action_view/model_naming' module ActionView - # The record identifier encapsulates a number of naming conventions for dealing with records, like Active Records or - # pretty much any other model type that has an id. These patterns are then used to try elevate the view actions to - # a higher logical level. + # RecordIdentifier encapsulates methods used by various ActionView helpers + # to associate records with DOM elements. # - # # routes - # resources :posts + # Consider for example the following code that displays the body of a post: # - # # view - # <%= div_for(post) do %>
- # <%= post.body %> What a wonderful world! - # <% end %>
+ # <%= div_for(post) do %> + # <%= post.body %> + # <% end %> # - # # controller - # def update - # post = Post.find(params[:id]) - # post.update(params[:post]) + # When +post+ is a new, unsaved ActiveRecord::Base intance, the resulting HTML + # is: # - # redirect_to(post) # Calls polymorphic_url(post) which in turn calls post_url(post) - # end + #
+ #
+ # + # When +post+ is a persisted ActiveRecord::Base instance, the resulting HTML + # is: + # + #
+ # What a wonderful world! + #
+ # + # In both cases, the +id+ and +class+ of the wrapping DOM element are + # automatically generated, following naming conventions encapsulated by the + # RecordIdentifier methods #dom_id and #dom_class: + # + # dom_id(Post.new) # => "new_post" + # dom_class(Post.new) # => "post" + # dom_id(Post.find 42) # => "post_42" + # dom_class(Post.find 42) # => "post" # - # As the example above shows, you can stop caring to a large extent what the actual id of the post is. - # You just know that one is being assigned and that the subsequent calls in redirect_to expect that - # same naming convention and allows you to write less code if you follow it. + # Note that these methods do not strictly require +Post+ to be a subclass of + # ActiveRecord::Base. + # Any +Post+ class will do as long as its instances respond to +post.to_key+ + # and +post.model_name.param_key+; for instance: + # + # class Post + # attr_accessor :to_key + # + # def model_name + # OpenStruct.new param_key: 'post' + # end + # + # def self.find(id) + # new.tap{|post| post.to_key = [id]} + # end + # end module RecordIdentifier extend self extend ModelNaming -- cgit v1.2.3