[D8] Port and merge Field Formatter Settings in core

[klonos]

Another module that's merged in D8 core: https://www.drupal.org/project/field_formatter_settings

Part of #378

The Field API in Drupal core lacks the ability for other modules to easily alter field formatter settings forms and the formatter summaries. This module is a small API provider for other modules since it's too late to get the hooks into Drupal 7 core.

Drupal 8
This module's API have been added to Drupal 8 via hook_field_formatter_third_party_settings() and hook_field_formatter_settings_summary_alter(). See #945524: Field formatter settings hooks in core for the Drupal 8 core issue.

D8 change record: https://www.drupal.org/node/2130757

Introduced hooks to extend field formatters and widgets with third-party settings
As of Drupal 8.x, four new hooks are available in Field UI API:

• hook_field_formatter_third_party_settings_form()
• hook_field_formatter_settings_summary_alter()
• hook_field_widget_third_party_settings_form()
• hook_field_widget_settings_summary_alter()

The new hooks allow developers to extend field formatters and widgets with third-party settings elements in the Manage Display tabs provided by Field UI. A typical use-case is to extend a field formatter with a new setting, which can be used later when rendering the field, e.g. in hook_preprocess_field().

Comparable hooks were previously provided in Drupal 7.x by the Field Formatter Settings API module in Contrib.

@mattfarina https://www.drupal.org/project/drupal/issues/945524#comment-3591916

This is sort of a regression and sort of a new feature that has been largely unused by many.

In CCK Formatters did not have settings. So, they did a few things to overcome this. One example is the way imagecache worked with imagefield for the display settings. Since you couldn't specify settings all the available settings were listed for each imagecache preset. This list could be altered fairly easily. Another example is the swftools module that created a global config and housed it on custom config pages. These could be easily form altered and were straight forward forms.

But, the way D7 does it is totally new. Formatter settings are not bolted on through something else and this was a late addition to D7. So, we went from CCK with a bolt on formatter setting solution you could easily alter (even if just at the form level in fairly straight forward forms) to native formatter settings you have to be a FAPI guru with a lot of patience to begin to hack on (the formatter settings forms are not trivial to work on).

Because this is done in a whole new way from D6 CCK and we are just now finding in real usage there are some problems I like this patch. It does not change the API but does add two new alter calls (which are only called on the formatter settings page). I've already seen two separate use cases for this functionality. One I linked to.

Hope this helps.

Modules that require the Field formatter settings module:

• Field Injector
• Field Formatter Class
• Field Delimiter
• Field Multiple Limit
• Field Word Boundary
• Field HTML Trim
• Linked Field
• Empty Fields
• Field Formatter Conditions

Current usage count at the time of writing (Feb, 2019): ~52k

---

PR by @opi: backdrop/backdrop#2493

[laryn]

https://www.drupal.org/node/2719575

[klonos]

Thanx @laryn 😉

[laryn]

@klonos FYI: https://github.com/backdrop-contrib/field_formatter_settings

Barely needed to be touched from what I could tell, it works for me (at least as far as Field Multiple Limit is concerned, which listed it as a dependency).

[opi]

RAW Pull-Request backdrop/backdrop#2493

late night testing with https://github.com/backdrop-contrib/field_multiple_limit, and it seems to work !

[opi]

Adding documentation from field_formatter_settings to our field.api.php.

[herbdool]

Is it ready to be reviewed and what would be the best way?

[klonos]

@herbdool I have added some additional info in the issue summary in the hopes that that would make it easier to understand how the contrib module worked.

I guess best way to test is to try to install a contrib module such as https://github.com/backdrop-contrib/field_multiple_limit or https://github.com/backdrop-contrib/field_html_trim that have https://github.com/backdrop-contrib/field_formatter_settings as a dependency, but without installing field_formatter_settings (edit the https://github.com/backdrop-contrib/field_multiple_limit/blob/1.x-1.x/field_multiple_limit.info file and remove or comment out the dependencies[] = field_formatter_settings line). Then see if the module still works as expected.

Another thing that would help is the code example in the D8 change record: https://www.drupal.org/node/2130757

[klonos]

...so:

1. manually download https://github.com/backdrop-contrib/field_multiple_limit/releases/download/1.x-1.0.0/field_multiple_limit.zip and extract it in your /modules directory.
2. Edit /modules/field_multiple_limit/field_multiple_limit.info and put a ; in front of the dependencies[] = field_formatter_settings line.
3. Enable Field Multiple Limit from /admin/modules
4. Navigate to /admin/structure/types/manage/post/display/default (or the "Manage displays" tab of any content type that has a multi-value field)
5. Edit the "Default" display -> notice that there is no "Configure" button for tags 👎
6. Apply the code changes from the PR.
7. Navigate to /admin/structure/types/manage/post/display/default again -> the "Configure" button is available and it works 👍

[klonos]

I have tested this with https://github.com/backdrop-contrib/field_multiple_limit and it works as expected, so RTBC. Adding milestone candidate for 1.13

PS: Noting that the Views UI settings for field_multiple_limit might be redundant, since core views provides that, but that is not a problem of this PR, rather than a problem with the contrib module (backdrop-contrib/field_multiple_limit#6).

[opi]

Thanks @klonos for all these useful comments <3

[opi]

Any thought for adding a milestone here ? @jenlampton @quicksketch @klonos

[jenlampton]

Yes, I agree with the milestone candidate label. Adding to 1.13 :)

[quicksketch]

I hate to be the bad guy again here, but we need test coverage in order to add this feature. Anything that adds functionality that is not directly used by core needs a test module that uses that functionality, then tests that ensure it works. Otherwise we'd have no way of knowing if we broke functionality of something provided but not utilized by core.

[herbdool]

The Drupal patch seems to include tests which probably work here without too much trouble. https://www.drupal.org/project/drupal/issues/945524#comment-6843398

[opi]

I hate to be the bad guy again here

but you're right. I need to learn how to write nice tests for Backdrop!

[herbdool]

@opi I tried out this patch for tests https://www.drupal.org/files/945524-55-tests_only.patch. It mostly works except one failure which I can't figure out. I might push it to your PR and can get more eyes on it.

[herbdool]

@opi tests are passing now.

[quicksketch]

I've merged backdrop/backdrop#2493 into 1.x for 1.13.0. Thanks @opi, @laryn, @klonos, and @herbdool!

We need a follow-up here though to add field_formatter_settings to backdrop_merged_modules() so we don't end up in the same situation as we did with Options Element with function name conflicts

[quicksketch]

Follow-up issue: #3742