Posted by CrookedNumber on May 20, 2010 at 8:55pm
| Project: | Drupal core |
| Version: | 7.x-dev |
| Component: | documentation |
| Category: | bug report |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
Now that fields are translatable, the fields attached to entities (e.g., nodes or users) are significantly more complex.
This comment is perhaps the best overview:
http://drupal.org/node/367595#comment-1767882
And as webchick said in http://drupal.org/node/367595#comment-1950888:
We'll need to make absolutely sure that we document this well in the theme/module upgrade guide as well as the general module/themer information because that will be a complete WTF.
And as someone who found about these changes in a very circuitous, head-scratching way, I'm hoping I can spare others the pain -- at least those who start with the docblock for drupal_form_submit()
Comments
#1
Patch
#2
The last submitted patch, drupal-better_drupal_form_submit_comments-804870.patch, failed testing.
#3
#1: drupal-better_drupal_form_submit_comments-804870.patch queued for re-testing.
#4
The last submitted patch, drupal-better_drupal_form_submit_comments-804870.patch, failed testing.
#5
One more time, rolling patch from drupal root (hat tip to catch).
#6
#7
This patch has a few problems:
a) The code comments that were added to the sample code do not follow our coding standards for comments.
http://drupal.org/coding-standards#comment
b) I don't think it is OK that we put into a docblock a link to someone's comment on an issue as the source for better documentation. Is there any information in the Handbook on this, or elsewhere in docblocks in the Drupal source code? If not, there should be.
c) If we are going to use this particular example, we should at least note what 'und' means.
d) We don't need to use the word "now" in there or explain that it is "more complex". We document the current state of Drupal in docblocks, without commenting on what may have been the case in the past. So please change the comment into something that would be appropriate for this as stand-alone D7 code, rather than a lesson on how to upgrade from D6 to D7.
#8
Regarding (c) in the previous comment, it would be better to use the self-documenting constant
LANGUAGE_NONE
rather than 'und'.
#9
Thanks for the feedback. Most appreciated.
I could add that handbook page. It seems, at least for now, that the most logical place for a piece on programmatically adding nodes / translatable fields would be a child page(s) added here:
http://drupal.org/node/443536
Does that make sense?
#10
Looking closer at http://api.drupal.org/api/function/drupal_form_submit/7 ...
I'm not actually sure the node form example is a good one to include. With the advent of fields in core, not all nodes even have bodies, the Expert install profile doesn't include the "story" content type at all, and is the title also translatable? Also, there could be other required fields for some content types.
So I would be in favor of just removing this example from drupal_form_submit(), rather than trying to patch it up. I think one example in there (the user password form, which is always available) is enough of an illustration.
As far as addressing the issue of a lack of documentation for translatable fields, yes I think the Field API section of the Handbook would be a good place to address that. Maybe make a page generally about the PHP object/array structure of field values on the node object? It would be useful for:
- drupal_form_submit()
- theming (what does $node look like when you do a node_load() with fields)
- simpletest
#11
Thanks. New patch forthcoming. And I'll start looking into documentation.
FYI -- as far as I can tell, titles are not translatable (at least not in D7 core -- http://drupal.org/node/367595#comment-1782244)
#12
#13
I think this patch is fine - removes the node example, leaving the password example only.
After committing, we should move this to the Documentation project issue queue for follow-up (see #10).
#14
The last submitted patch, drupal-better_drupal_form_submit_comments-804870-10.patch, failed testing.
#15
#12: drupal-better_drupal_form_submit_comments-804870-10.patch queued for re-testing.
#16
#17
Committed to CVS HEAD.
Moving to the Documentation project per #10.
#18
#19
I decided to file a separate issue about this for the Handbook documentation.
#824434: Add documentation about making fields translatable
#20
Automatically closed -- issue fixed for 2 weeks with no activity.