The FAPI docs for D7 are missing documentation of the #title_display property. Below are the docs, as I understand them.

Drupal 7 provides a #title_display property that can be used with any form element that supports the #title property. The #title_display property tells the form system how to render #title and supports four possible values.

before
(default*) #title is rendered as a label element before the form element in the page markup.

after
#title is rendered as a label element after the form element in the page markup. (*note: this is the default value for radio and checkbox form element types.)

attribute
(only applies to radio and checkbox elements) #title is rendered as the title attribute of the form element

invisible
#title is rendered as a label element before the form element in the page markup, and is made invisible with the Drupal 7 .element-invisible system CSS class (system.base.css).
This makes #title remain available to screen-reader users, but hides it from being displayed visually in the browser.

CommentFileSizeAuthor
#6 fapi.title_display.937018.6.patch.txt9.51 KBduellj
Members fund testing for the Drupal project. Drupal Association Learn more

Comments

bowersox’s picture

This documentation looks perfect. Where does it go (and how do we get it there)?

Everett Zufelt’s picture

You need a CVS account to edit the doc, it is at:

http://drupalcode.org/viewvc/drupal/contributions/docs/developer/topics/

forms_api_reference.html

I would edit it myself, but it is a pretty complicated file and I fear messing it up editing with a screen-reader. I can take a crack at it if nobody else has the time.

Edit:

Anyone with a CVS account can edit the doc, no special permission is required.

Stevel’s picture

There is some documentation of #title_display, in the API docs of theme_form_element() (http://api.drupal.org/api/function/theme_form_element/7).

There seems to be one option missing ('none'), but that might be for internal use only (as I see it, it's used when #title is not set, and does the same as 'attribute', except it does not set the tooltip).

duellj’s picture

Assigned: Unassigned » duellj

I'm going to take a stab at including #title_display in the FAPI docs. I think that value docs from theme_form_element() should work for the FAPI docs. I'll post a patch here first before I edit the doc directly.

duellj’s picture

Status: Active » Needs review
FileSize
9.51 KB

Attached patch (with .txt to prevent bot testing). If someone wants to give this a quick look over, I can commit it to CVS.

Stevel’s picture

Status: Needs review » Reviewed & tested by the community

Applied this locally and it looks good, so RTBC

Everett Zufelt’s picture

Status: Reviewed & tested by the community » Needs work
> <ul>
>   <li><strong>before</strong>: The label is output before the element. This is the default. The label includes the #title and the required marker, if #required.</li>
>   <li><strong>after</strong>: The label is output after the element. For example, this is used for radio and checkbox #type elements  as set in system_elements().
If the #title is empty but the field is #required, the label will contain only the required marker.</li>

* Can we separate info on #required from info on the attributes for #title_display, perhaps putting it before or after this list.  Also, let's make sure that it is clear that after is "default" for radio and checkbox.

>   <li><strong>invisible</strong>: Labels are critical for screen readers to enable them to properly navigate through  forms but can be visually distracting. This property hides the label for everyone except screen readers.</li>

* Incorrect, so if this is in an inline comment in theme_form_element it needs to be corrected as well.  It is a WCAG 2.0 level A requirement that form fields have accessible names, this can be done through a label, a title, or some other way.  It is * not * critical to use a label.

>   <li><strong>attribute</strong>: Set the title attribute on the element to create a tooltip but output no label element. This is upported only for checkboxes and radios in form_pre_render_conditional_form_element(). It is used where a visual label is not needed, such as a table of checkboxes where
the row and column provide the context. The tooltip will include the title and required marker.</li>
> </ul>
mgifford’s picture

Everett, are you going to work this into a patch? I'm not clear what was wrong with SteveL's patch other than that it didn't end with .patch. I didn't look any further.

Everett Zufelt’s picture

@mgifford

Since we aren't patching core it isn't necessary to test the patch. We're patching a doc that just happens to live in CVS. So, there will be no automated testing of the patch, just inspection and then someone can patch the file in CVS and commit the change.

duellj’s picture

Status: Needs work » Needs review

If there's nothing else wrong with the patch in #6, I think we can go ahead and commit it, since the problems in #8 primarily affect the docblock for theme_form_element(). We can then redirect this issue to rework the wording for theme_form_element().

Everett Zufelt’s picture

Status: Needs review » Needs work

@duellj

Other than what I pointed out in #8 I don't think there is anything wrong with the patch in #6. It would seem, with the suggested changes, to be following what @brandonojc and I have both confirmed as accurate above.

Everett Zufelt’s picture

Status: Needs work » Needs review
mgifford’s picture

Everett, can you re-roll the patch then & see if we can't get it RTBC'd to better reflect how it works.

Everett Zufelt’s picture

Not until the beginning of next month. I have already provided the docs, Brandon confirmed they were correct, someone just needs to update the file.

duellj’s picture

Status: Needs review » Needs work

I'll be able to update the file later today.

duellj’s picture

Status: Needs work » Needs review

What does everyone think of the following?

Description: Indicates how the label should be rendered. The label includes the #title and the required marker, if #required. If the #title is empty but the field is #required, the label will contain only the required marker.

Values: String.

Possible values

  • before: The label is output before the element. This is the default for most elements.
  • after: The label is output after the element. For example, this is the default used for radio and checkbox #type elements as set in system_element_info().
  • invisible: #title is rendered as a label element before the form element in the page markup, and is made invisible with the Drupal 7 .element-invisible system CSS class (system.base.css). This makes #title remain available to screen-reader users, but hides it from being displayed visually in the browser.
  • attribute: Set the title attribute on the element to create a tooltip but output no label element. This is supported only for checkboxes and radios in form_pre_render_conditional_form_element(). It is used where a visual label is not needed, such as a table of checkboxes where the row and column provide the context. The tooltip will include the title and required marker.
Everett Zufelt’s picture

+1

bowersox’s picture

Looks great! Thanks, @duellj.

Everett Zufelt’s picture

Status: Needs review » Reviewed & tested by the community

Yes, thanks @duellj. I think this is good to go now.

duellj’s picture

Commited: http://drupal.org/cvs?commit=438608 Thanks everyone!

Should we open a new issue to fix the docblock in theme_form_element()?

Dries’s picture

Status: Reviewed & tested by the community » Fixed

Sounds like this is fixed?

Everett Zufelt’s picture

@duellj

If you think that the docs in theme_form_element need improvement then yes, please open a new issue.

@Dries

Yes, this appears to be fixed.

Status: Fixed » Closed (fixed)
Issue tags: -accessibility

Automatically closed -- issue fixed for 2 weeks with no activity.