Does build/view/formatter terminology make sense?

I agree that _view() is better than _build() across the board if what's being built is a render array that represents the "view" of something. And I'd be in favor changing node_build() to node_view() and hook_node_build_alter() to hook_node_view_alter() in D8.

Also, _view() is the chosen term within FieldAPI, which at least makes field_attach_view() consistent with hook_node_view(). So I agree that hook_field_formatter_view() would be better than hook_field_formatter_build().

So my preference is to change hook_field_formatter() to hook_field_formatter_view(). I think it would also be ideal to change hook_field_widget() to hook_field_widget_form() (since it's called from field_default_form()).

What do you guys think? Would either/both of these be an improvement? Are either/both do-able for D7? Does it make sense to do one if we don't also do the other?

Here's a patch that might be too much for D7, but what the heck, I'll throw it up here for comments and we can remove hunks if needed. Here's what the patch does:

• Changes hook_field_formatter() to hook_field_formatter_view().
• Changes hook_field_widget() to hook_field_widget_form().
• Changes (comment|node|user|contextual_links|toolbar)_build() to *_view().
• Changes (comment|node|user)_build_multiple() to *_view_multiple().
• Changes hook_(comment|node|user)_build_alter() to hook_*_view_alter().

This patch does NOT:

• Change variable names or parameter names (e.g., $build and $build_mode remain as variable names throughout these functions).
• Change hook_page_build() or hook_page_alter().
• Change (comment|node|user)_build_content().

Here's my reasoning. I understand that in D6 and before, "view" implied returning HTML or modifying an object property with HTML. And that as the D7 render model was being worked on, we needed to draw attention to the difference between returning a structured array and returning HTML. But now that the render model has very nicely progressed to where it is, we're pretty much dealing with render arrays everywhere. Within HEAD, hook_(node|comment|user)_view($obj) work on $obj->content as a render array. hook_block_view() returns $data that contains 'subject' and 'content', and 'content' should be set to a render array, and hook_block_view_alter() can modify $data['content'], but should also keep it as a render array while doing so. aggregator_block_view(), block_block_view(), and blog_block_view() still set the content to an HTML string, but that can potentially still be fixed prior to release; OTOH, book_block_view() sets $data['content'] to a render array as is proper. Page callbacks should return render arrays, and node_page_view() does; aggregator_view() returns HTML, but this can still be fixed prior to release. And, at this point, FieldAPI always returns render arrays from all of its display functions, and those functions end in _view().

So basically, we nearly succeeded (and may yet fully succeed) in making all core module functions use render arrays and not output HTML except in theme functions that are invoked after page rendering has started. And those functions, of course, all start with 'theme_', so we can reclaim the word 'view' to be less tied to the HTML format, but instead refer to the more abstract concept of "a representation of a display", and because PHP is the way it is, our representation of choice is a render array. And by using that representation, we allow for more altering further down the pipeline, and in contrib and maybe in D8 core, we'll start seeing code that renders that representation to non-HTML formats. But as cool as all of that is, it doesn't change the fact that a render array is still a representation of a display. In MVC terminology, it's not the model (the $node object as it comes from the database and after hook_load() is the model), and it's not the controller (the various drupal functions involved in getting it so that node_build()/node_view() is called is the controller). No, the output of node_build()/node_view() is the view, even if a somewhat abstract one.

Meanwhile, we use the term 'build' to refer to all sorts of things other than render arrays. We build menu router items, forms (which while render arrays, are MORE than render arrays), the theme registry, batch information, etc., and for all of these, the term 'build' refers to model/controller related code.

The reason I don't think we need to change *_build_content() is because the word 'content' clarifies the meaning. And I don't think we need to change hook_page_build() and hook_page_alter(), because the word 'page' makes it clear what's going on. But for the other objects ('node', 'comment', 'user', 'toolbar', 'field', etc.), I believe 'view' is the more accurate description of the process than is 'build'.

But, this patch will likely require many other patches in the queue to be re-rolled, and will likely break modules that have already been ported to D7, so we need to decide if the benefits of clearer and more consistent terminology is worth that.

@moshe: Is any of this convincing or do you still think we should leave things in their inconsistent state or change FieldAPI to use 'build' instead of 'view'?

Is it OK to have a hook / function ending in _form() that does not return / act on a full $form but only a sub part ?

Well, in addition to FieldAPI functions that already do this (field_default_form(), field_multiple_value_form()), we also have filter_form() and image_resize_form() and its variants, so I think it's okay, but someone please speak up if it isn't.

Not sure who else needs to review it before it's RTBC, but changing the "component" attribute of the issue and adding tags to reflect the nature of the patch.

What's needed for this to be RTBC? Is there a key person (or people) who should review it?

I opened a separate issue to get doc team help with this: #675212: How should a reversion be documented in the D6->D7 module upgrade doc?.

Actually, I guess just because the other issue was opened to get some help doesn't make this one fixed, does it? Since webchick sent out the email to the dev list asking for people to work on the "Needs Documentation" queue, perhaps this should be "needs work" so it gets attention.

Got an answer in #675212-1: How should a reversion be documented in the D6->D7 module upgrade doc?, but noticed that at least some trace of information exists on the module upgrade page for other things that have been reverted, so I made a compromise by removing the body of the information, but leaving the title in DEL tags: http://drupal.org/node/224333/revisions/view/893868/894800.