There is no documentation of the #description_display property on the Form API page

[swampopus]

Howdy all,

I was trying to figure out how to get my description under a textarea, and had no idea there was a "#description_display" property. ChatGPT didn't help at all; flatly told me I had to write a template function.

I checked on the form_api page, but nothing was listed.

I finally found answers in an issues post for core, where #description_display was actually added to 1.30.0.

Anyway-- it should really be part of the Form API page.

EDIT: Quick link to current page: https://docs.backdropcms.org/form_api

[yorkshire-pudding]

The relevant issue is backdrop/backdrop-issues#1403

We need to document for the property itself:

• Description
• Values
• Usage Example

Look at existing Form API properties for a steer

Then we need to document which elements it should be added to. Is it any with a description property or will it not be applicable to some?
Each element for which this property is applicable will need this property referenced within it.

[swampopus]

Elements tables sections

I envision this appearing just below the #description link in the tables, just like the #title_display is right below the #title.
Ex:

This new #description_display checkboxes row would be in both the "Simple Elements" table, as well as the "Structural Elements" table and "Complex Elements" table.

Content for the #description_display section

I believe this would appear fairly similar to the #title_display section, and would be available for any element which can have a #description.

Eg:

#description_display

Used By
ajax, button, checkbox, checkboxes, color, container, contextual_links, date, email, fieldset, field_ui_table, file, form, head_tag, html_date, html_datetime, html_time, image_button, item, link_field, machine_name, managed_file, number, options, password, password_confirm, radio, radios, range, scripts, search, select, styles, submit, tableselect, tel, textarea, textfield, text_format, token, url, weight

Description
Indicates how the description for an element (if defined) should be rendered. Most elements display the description after the widget by default, while others display the description before the widget.

Values
String.

Possible values:

• before: The description is output before the element. This is the default for textareas and some other special elements.
• after: The description is output after the element. This is the default for textfields, radios, etc.
• invisible: The description is not displayed.

Usage Example

<?php
  $form['example'] = array(
    '#type' => 'textarea',
    '#title' => t('Address'),
    '#description' => t('Please enter your full mailing address.'),
    '#description_display' => 'after',
  );
?>

[NormPlum]

description_display is already documented: https://docs.backdropcms.org/form_api#description_display
It's just not "used by" anything, so doesn't show up in the table where you'd expect it...

[bugfolder]

I've created the description_display FAPI property on the docs site (this page only visible to admins):

https://docs.backdropcms.org/form_api/description_display

The property will need to be added individually to each of the FAPI Elements listed above (ajax, button, checkbox...). However, the ajax for adding FAPI Properties to a FAPI Element seems to be broken, generating this error in the browser console:

Failed to load resource: the server responded with a status of 500 (Service unavailable (with message))

So we're kind of stuck at the moment.

Paragraphs on the docs site is at version 1.33, and the current version is 1.38, so upgrading the docs site to current Backdrop and current modules might be helpful.

[swampopus]

description_display is already documented: https://docs.backdropcms.org/form_api#description_display It's just not "used by" anything, so doesn't show up in the table where you'd expect it...

@NormPlum I think that's because @bugfolder (or someone?) just added it. I swear it wasn't there a few hours ago! Plus, its description is literally what I wrote :)

[bugfolder]

I think that's because @bugfolder just added it.

Correct.

[bugfolder]

Playing with a local copy of the docs site reveals that the problem with adding FAPI properties to FAPI elements is indeed due to the ancientosity of Paragraphs module. I'll update docs.b.org to the latest versions of all modules (including core, which was behind) and then continue with this.

[bugfolder]

Starting to work through these now. A few points and questions about the documentation.

• In the "Used by" list above, some elements are listed that don't have a #description property (e.g., ajax, button, etc.). I'm not adding #description_display to those, of course.
• In the description of the values, before is "the default for textareas and some other special elements." What are those "other special elements"? (The default value is specified for each element/property combination in FAPI so I'll need to set those when I get to them.)

You can now start to see some of the checkmarks appear in https://docs.backdropcms.org/form_api.

[swampopus]

Re: the "special elements", that verbiage might just be removed or modified. But, I know that textarea, fieldset, and text_format are some. I am testing others now.

[swampopus]

Okay-- in system.module, line 422 - 444, these element types have 'description_display' set to 'before':

textarea, radios, checkboxes

EDIT: So the grand total I can determine from searching the code are:

textarea, text_format, fieldset, radios, checkboxes

[bugfolder]

EDIT: So the grand total I can determine from searching the code are:

textarea, text_format, fieldset, radios, checkboxes

Thanks! And so for all others, the default value is set to after (as opposed to no default value), right?

[bugfolder]

These are all done. https://docs.backdropcms.org/form_api

Leaving the issue open for the moment for proofreading, modifications, or other comments.

[swampopus]

Awesome! I do have a nitpick already :)

So, I was wrong in my initial "possible values." "after" is NOT the default for radios.

Perhaps the Possible values: should read as follows:

Possible values:

• before: The description is displayed before the element. This is the default for certain elements (eg, textarea, radios, checkboxes, fieldset).
• after: The description is displayed after the element. This is the default for most elements.
• invisible: The description is not displayed.

(Edit: changed "output" to "displayed")

[bugfolder]

I made your edits, thanks. I also reordered the values, so that the most common default value (after) comes first in the order.