Posted by sun on September 21, 2011 at 6:32pm
13 followers
Jump to:
| Project: | Drupal core |
| Version: | 8.x-dev |
| Component: | documentation |
| Category: | task |
| Priority: | major |
| Assigned: | Unassigned |
| Status: | active |
| Issue tags: | DrupalWTF, needs backport to D7 |
Issue Summary
In #1230534: allowed_views should be an instance setting, not a field setting (Viewfield) and other issues on d.o, there's lots of uncertainty around this part of the current hook_field_info() docs:
- settings: An array whose keys are the names of the settings available for the field type, and whose values are the default values for those settings.
- instance_settings: An array whose keys are the names of the settings available for instances of the field type, and whose values are the default values for those settings. Instance-level settings can have different values on each field instance, and thus allow greater flexibility than field-level settings. It is recommended to put settings at the instance level whenever possible. Notable exceptions: settings acting on the schema definition, or settings that Views needs to use across field instances (for example, the list of allowed values).
It is entirely not clear when it is valid to use instance settings (such as "allowed values", which can vary depending on field type).
Furthermore, according to the current docs, Drupal core seems to contain and provide invalid examples. Most field type modules in core only have field settings (and no instance settings), whereas most of the field settings do not affect the field schema, so according to and strictly following these docs, they should be instance settings.
So what? Clarification please.
Comments
#1
#2
+1 It's really not clear what settings could be used on instance level and what limits for settings on field level
#3
I regularly get confused by this.
#4
Thank you for raising this issue @sun. Like you, I am confused by these two settings arrays.
#5
subscribing. I really wish that doc-only issues would just get filed in the Documentation component. And FYI as far as I know, in Drupal Core no one monitors the 'documentation' tag... There are tag guidelines (see link below the tags field, and sub-pages that actually list the tags to use and not use), and this is clearly stated there. Thanks!
#6
I'll follow so as to learn more on this.
EDIT: deleted potentialy confusing content, as it used incorrect concept of "instance".
#7
EDIT: deleted potentialy confusing content, as it used incorrect concept of "instance".
#8
Before this issue gets out of control...
Looks like no one really knows about any other non-obvious implications (also not concerning Views or whatever), so we should heavily shorten and clarify the documentation to state:
#9
Yep. 'settings' should only affect the field schema. Anything else should be 'instance_settings'.
#10
From my understanding this shouldn't break views in any place: the views-data doesn't rely on any field/instance settings
and the rendering part is using just plain fieldapi functions.
Fhe formatter settings are setup in views directly but this is not part of the issue.
#11
views are rely on formatter settings which is other thing, but I think views are using field setting to know about the storage of the fields
#12
Thanks for all the discussion! So it looks like we need a patch based on comment #8. Moving to docs component now since it's a purely docs issue.
#14
This may be the wrong place for this, but where ... on Gods green earth, can I find WHAT the "settings" array should include?!?!
If this is confusing for veterans, imagine my frustration just starting out.
#15
[Powered by #1115636: Issue Macros and Templates]
Please do not change the core version. Please read http://drupal.org/node/767608 for the reasons why.
#16
RE #14 - http://api.drupal.org/api/drupal/modules!field!field.module/group/field/7
There are some issues to move this information elsewhere but it hasn't been done yet.
#17
@la2texas: the issue summary has #1230534: allowed_views should be an instance setting, not a field setting as initial problem. The patch over there maybe helps.
That page is indeed horrible http://api.drupal.org/api/drupal/modules!field!field.module/group/field/7 (and why is the link not formatted accordingly?)
@jhodgdon
- do you have these related issues?
- how it that page generated?
#18
RE #17 -
- API docs on api.drupal.org are generated by the API module from comments in the code.
- Not sure why that URL did not turn into a link; probably a bug in the core URL text formatter.
- Related issues:
#1391118: Clean up Field Types API topic and add settings form hooks
#1345654: hook_field_info should have clear link to the field_types topic, and that topic should say which hooks are needed