FAPI: Attribute #allow_focus used for creating readonly fields is not documented

[klonos]

Related to #132

This was introduced in D7 as part of https://www.drupal.org/project/drupal/issues/426056 (commit: https://git.drupalcode.org/project/drupal/-/commit/33f0b0830baa8d584c8cce180fa2d8a0b94e39fd) but never documented: https://www.drupal.org/project/documentation/issues/2605088

It is not documented, that setting #allow_focus to TRUE on an element which has #disabled set to TRUE will make it readonly in HTML instead of disabled.

It is crucial for providing fields that do not allow user input but can be selected with most browsers. See related issue.

FF recommends setting readonly instead of disabled for elements that should be copyable. The Drupal Form API documentation doesn't show the way to do it (manually setting the #attributes tag to have the readonly element instead of using disabled would bypass Drupal's security checks that do not allow disabled elements to be returned with modified data - this is on line 2075 of form.inc in Drupal 7.39). However, I could find in the code that setting #allow_focus on a #disabled element would make it readonly (form.inc line 2060), so this is the correct way of doing it, but it's not yet documented on the Form API page.

Also see https://api.drupal.org/api/drupal/developer%21topics%21forms_api_reference.html/7.x?page=1#comment-62189

If you want to set your <input> or <textarea> input elements to be 'readonly=readonly' you need to set the element to be disabled = TRUE && #allow_focus = TRUE.. Documentation is coming soon, follow here https://www.drupal.org/node/2605088

Also see the spec on Read-only here https://www.w3.org/TR/html401/interact/forms.html#read-only

#disabled is not always going to work because the values do not get sent in $_POST, therefore do not make it to $form_state['input'].

[klonos]

...relevant code: https://github.com/backdrop/backdrop/blob/1.x/core/includes/form.inc#L2109

  // Setting #disabled to TRUE results in user input being ignored, regardless
  // of how the element is themed or whether JavaScript is used to change the
  // control's attributes. However, it's good UI to let the user know that input
  // is not wanted for the control. HTML supports two attributes for this:
  // http://www.w3.org/TR/html401/interact/forms.html#h-17.12. If a form wants
  // to start a control off with one of these attributes for UI purposes only,
  // but still allow input to be processed if it's sumitted, it can set the
  // desired attribute in #attributes directly rather than using #disabled.
  // However, developers should think carefully about the accessibility
  // implications of doing so: if the form expects input to be enterable under
  // some condition triggered by JavaScript, how would someone who has
  // JavaScript disabled trigger that condition? Instead, developers should
  // consider whether a multi-step form would be more appropriate (#disabled can
  // be changed from step to step). If one still decides to use JavaScript to
  // affect when a control is enabled, then it is best for accessibility for the
  // control to be enabled in the HTML, and disabled by JavaScript on document
  // ready.
  if (!empty($element['#disabled'])) {
    if (!empty($element['#allow_focus'])) {
      $element['#attributes']['readonly'] = 'readonly';
    }
    else {
      $element['#attributes']['disabled'] = 'disabled';
    }
  }

[bugfolder]

@klonos, I've added #allow_focus to FAPI:

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

Any comments or suggestions to make it clearer?