Improve documentation for Third Party Settings

There is a test in core that does exactly what you're after to a contact form, that should be a good reference point

That test looks a lot like your lightening talk. ;)

Yep I think I wrote it over in #2342551: Implement ThirdPartySettingsInterface in contact module for contact form config entity

I'm a bit confused here. Where is this documentation proposed to be added/improved?

If it's pages on drupal.org, then please go ahead and edit them, or else move the issue to the Documentation project. You can tag with "d8 docs" and "developer".

If it's stuff in Drupal Core files, the issue should remain here.

No one but me really looks at issues in the documentation component, so. You'll be better off pinging people directly in IRC. Not sure who to ask, but you can ping one of the people in the know to figure that out.

fwiw the phrase "the core devs" creates barriers and implies there are different classes of contributors. We are all Drupal contributors. Please avoid it.

Can we work to turn the example in the contact module tests 'send me a pony' into documentation?

Hi,

just wondering if this was ever completed - I am looking for some help on using TPS.

Cheers.

Ok in my case I wanted to add in the TPS into the field settings form... this is how it is done:

function my_module_form_alter(&$form, FormStateInterface $form_state, $form_id) {

  $entity = $form_state->getFormObject()->getEntity();

  $form['third_party_settings']['my_module']['my_field_setting'] = array(
    '#type' => 'textfield',
    '#title' => t('My custom field setting'),
    '#default_value' => $entity->getThirdPartySetting('my_module', 'my_field_setting'),
  );
}

Obviously you will need a way to check that it is the right field in my case I just name them in particular way and I query the field_name.

I am currently on a D8 project so it may be feasible for me to have a shot at writing the documentation. As far as I can see the previousnext lightning talk covers one part of it and what I have done above covers another part.

+1 for actually documenting this, as I deal with #2613336: Convert migration_group to a third party setting.

Please how do i retrieve the value the user selects? I want to be able to make some comparison based on the value selected in my template.twig file. I have set this in a custom module

E.g, {% set value = $block->getThirdPartySetting('helper_module', 'collapse') %}

Hmm, puzzling with this too. As far as i can see,

@Michelle asked in the summary:

The core content translation module uses "$form['field']['third_party_settings']['content_translation']['translation_sync'] = $element;" to do the autosaving of third party data on fields but then it uses "$config->setThirdPartySetting('content_translation', 'enabled', $value)->save();" when it wants to add third party settings to something that is not a field.

I have been trying to figure out what makes fields different but keep getting in over my head. Is this actually implemented differently for fields or am I just missing something? If it is different, was that intentional or is it unfinished or an oversight that the others don't have the automatic saving?

* core.entity_view_display.*.*.*::third_party_settings are a builtin of any config entity, defined in core.config_entity schema in drupal/core/config/schema/core.data_types.schema.yml and supported by builtin \Drupal\Core\Config\Entity\ConfigEntityBase::getThirdPartySettings
* OTOH core.entity_view_display.*.*.*::content.*.third_party_settings is defined in core.entity_view_display.*.*.* schema in drupal/core/config/schema/core.entity.schema.yml and *not* supported by a builtin config entity method

@Michelle asked in #2:

Also, is there a reason for using #entity_builders for saving the TPS rather than #submit?

I think it is just more natural to
* prepare the entity content in #entity_builders
* store tne entity content in #submit

If this is not documented, it really should.

Hope this helpz.

Hi @axel.rutz and all others,
thank you very much for the discussion.

I still couldn't find any general documentation in TPS yet. Only this issue. What I'd need is first of all general information about TPS and what to (not) use it for.

General questions could be:

• What are third party settings?
• What are third party settings intended for? Which problem do they solve?
• What's typical use of third party settings? (Usage examples / showcases from modules)
• What's typical misuse of third party settings?
• Are third party settings saved into the database automatically using set() or are they only runtime? (which might also be helpful in some cases) - like variable_get and variable_set TPS might be used wrongly.

And perhaps others...

Who could answer that for a first documentation? I only recognized TPC in kint so far and I'm afraid of misuing them...

If there is a documentation page already, please link it here and close the issue.

Daniel Sipos wrote an excellent tutorial on this:

https://www.sitepoint.com/drupal-8-third-party-settings-and-pseudo-fields/

Perhaps parts can be taken over for Drupal-Docs.

https://www.heididev.com/how-alter-configuration-entity-data-drupal-8-or...

I agree 100% that the third party settings system needs to be better documented. Some feedback on the most recently post links:
- The post in #20 took a very long time to get to the actual usage of TPS, it seemed to be focused on a very narrow case using entirely custom forms. The page was so loaded with ads that I had trouble scrolling through, and Chrome warned me of two separate embedded ad page that had crashed the browser
- The post in #21 was much more succinct, but specified the definition and use of a save handler, which isn't really necessary if you're just adding something into a field's config

The reference in #11 was perfect for me. When I needed to retrieve the setting with the code for my custom field, I only needed to do this:

$field_def = $this->fieldDefinition;
$allow_recurring = $field_def->getThirdPartySetting('my_module', 'my_field_setting');

I totally agree with @mandclu, especially in that #21 is an absolutely helpful (working) documentation that's straight up to the point and would surely make a good candidate for documentation on drupal.org as well, maybe additionally sorting out in which case it's necessary to use the entity_builders callback.

Thanks @mandclu for the TLDR; version.
In D8.9.1 for a content type form (ie /admin/structure/types/manage/*), I needed to add a submit handler to save the value:

function my_module_form_alter(&$form, &$form_state, $form_id) {
if ($form_id === 'node_type_edit_form') {
$entity = $form_state->getFormObject()->getEntity();
$form['third_party_settings']['my_module']['my_field'] = array(
'#type' => 'textfield',
'#title' => t('My Field'),
'#default_value' => $entity->getThirdPartySetting('my_module', 'my_field'),
);
$form['actions']['submit']['#submit'][] = 'my_module_submit_node_type_form';
}
}

function my_module_submit_node_type_form(&$form, FormStateInterface $form_state) {
$entity = $form_state->getFormObject()->getEntity();
$entity->setThirdPartySetting('my_module', 'my_field', $form_state->getValue('my_field'));
$entity->save(); //didn't work without saving here
}

To get the value in my twig:
function my_module_preprocess_node(&$variables) {
$type = $variables['node']->getType();
$node_type = \Drupal::entityManager()->getStorage('node_type')->load($type);
$variables['my_field'] = $node_type->getThirdPartySetting('my_module', 'my_field');
}

@rick.kowal: You should probably better use the "entity_builders" callback in form_alter

$form['#entity_builders'][] = 'your_module_node_type_builder'; (naming is up to you)

see link from #21: https://www.heididev.com/how-alter-configuration-entity-data-drupal-8-or...

That way no entity->save() should be necessary (which imho can lead to serious problems if used during the regular entity processing).

as of #25

The part I'm struggling with is base fields on a custom entity type. I'm not using the Drupal UI; instead I'm using vuejs and need to set third party settings on base fields. Since form api isn't used, form_alter hooks doesn't help me much.

I would have thought something like this would work, but it doesn't:

$fields['my_field'] = BaseFieldDefinition::create('boolean')
      ->setLabel(new TranslatableMarkup('My Field))
      ->setDefaultValue(TRUE)
      ->setRevisionable(TRUE)
      ->setTranslatable(TRUE)
      ->setRequired(TRUE)
      ->setSetting('on_label', t('Enabled'))
      ->setSetting('off_label', t('Disabled'))
      ->setDisplayConfigurable('view', TRUE)
      ->setDisplayConfigurable('form', TRUE)
      ->setDisplayOptions('form', [
        'type' => 'options_buttons',
        'weight' => 0,
        'third_party_settings' => [
          'my_field' => [
            'widget_options' => [
              'buttons' => TRUE,
            ],
          ],
        ],
      ]);

There are no third party settings for base fields. But you can still expose the field ui admin route for your entity type and then manage the third party settings there for the form display.