Adding descriptions to the form fields from schema

Created on 26 March 2025, 3 months ago

Problem/Motivation

For the forms, we usually need to provide not only the label, but also a description text to make it more clear for users.

Proposed resolution

Would be good to implement an ability to set the description in the schema and use it in the form building. Is it hard to implement?

✨ Feature request
Status

Active

Version

1.1

Component

Code

Created by

πŸ‡¦πŸ‡²Armenia murz Yerevan, Armenia

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @murz
  • πŸ‡ΏπŸ‡¦South Africa rudolfbyker South Africa

    I'm not sure if this is possible without changing Drupal core. If you would add custom properties not listed in https://www.drupal.org/docs/drupal-apis/configuration-api/configuration-... β†’ to your schema, it will not be valid according to Drupal core.

  • πŸ‡¦πŸ‡²Armenia murz Yerevan, Armenia

    Hmm, I thought that we can add more custom properties without breaking the schema. If not, maybe we can suggest extending the schema then? Cuz field labels without descriptions make too little sense for users :)

  • πŸ‡ΏπŸ‡¦South Africa rudolfbyker South Africa

    A few more thoughts:

    • I just noticed that "title" is also not part of the schema, at least not according to my IDE. Yet, it works. So in theory, I guess we could add more properties.
    • Currently, this module uses 'title' for the short title of the form element, and 'label' as the longer description below it. Why does that not suffice?
    • In your class that extends AutoConfigFormBase, you can override any of the protected or public methods you wish, and either replace them with your own implementation, or call the parent implementation and modify the result before returning. One that might be of special interest to you is protected function getCommonElementAttributes.
  • Pipeline finished with Success
    3 months ago
    Total: 144s
    #473028
  • πŸ‡¦πŸ‡²Armenia murz Yerevan, Armenia

    Yes, the "title" is already not a part of the schema, so adding the "description" will not make the thing worse ;)

    So, I created an MR https://git.drupalcode.org/project/auto_config_form/-/merge_requests/3 with extending the current form field generation:
    - It now uses the "title" value as the default, if set, if not - falls back to "label" that should be present in every schema.
    - If the "description" is present, it generates the description from this value. If the "description" is missing and the "title" is present, it renders the "label" as the field description.

    Please review and share your thoughts about this implementation.

  • πŸ‡ΏπŸ‡¦South Africa rudolfbyker South Africa

    Thanks for the MR. I will try to review it next week.

    In the mean time, you still have to answer my question from #4:

    Currently, this module uses 'title' for the short title of the form element, and 'label' as the longer description below it. Why does that not suffice?

  • Pipeline finished with Success
    3 months ago
    Total: 143s
    #473210
  • πŸ‡¦πŸ‡²Armenia murz Yerevan, Armenia

    Currently, this module uses 'title' for the short title of the form element, and 'label' as the longer description below it. Why does that not suffice?

    The "label" value is used in Drupal UI when you translate, export, import config, so actually it's a kind of "Title" not the description at all.

    So, the current approach to use "title" as Title and "label" as Description looks not very good, because in the description we usually describe the things in more details, even with some examples, and keep the title as short as possible.

    So, from my point of view, it's better to use the "label" field as the element title, and the "description" field for the description. But in my MR I implemented a workaround to keep the current behavior too, to keep the compatibility with previous configurations.

    What do you think about this?

  • πŸ‡ΏπŸ‡¦South Africa rudolfbyker South Africa

    OK, I can see how using "label" for the title was not ideal. We could make "title" and "description" required in the next major version of this module.

    We should add tests before merging this. Would you be able to do that? If not, I'll do it, but I can't guarantee a time frame. Luckily, I already set up CI for this module earlier this month!

    It's probably best to use unit tests with a mocked ContainerInterface, or a kernel test. Then create a class like TestAutoConfigFormBase, instantiate it, and call buildForm. Do this with various combinations of config schemas, and assert that the form looks as expected. We should include a test that ensures backward compatibility with the old way of doing things, where "label" is used instead of "title". We should clearly mark those tests, saying that we'll remove them in the next major version.

Production build 0.71.5 2024