Issue #2486989 by metzlerd, jhodgdon: Create Documentation For Container Form Elements

core/lib/Drupal/Core/Render/Element/Actions.php

@@ -13,8 +13,18 @@
 /**
  * Provides a wrapper element to group one or more buttons in a form.
  *
- * Use of the 'actions' element as an array key helps to ensure proper styling
- * in themes and to enable other modules to properly alter a form's actions.
+ * Use of a single Actions element with an array key of 'actions' to group the
+ * primary submit buttons on a form helps to ensure proper styling in themes,
+ * and enables other modules to properly alter a form's actions.
+ *
+ * Usage example:
+ * @code
+ * $form['actions'] = array('#type' => 'actions');
+ * $form['actions']['submit'] = array(
+ *   '#type' => 'submit',
+ *   '#value' => t('Save'),
+ * );
+ * @endcode
  *
  * @RenderElement("actions")
  */

core/lib/Drupal/Core/Render/Element/Container.php

@@ -16,6 +16,31 @@
  * Surrounds child elements with a <div> and adds attributes such as classes or
  * an HTML ID.
  *
+ * Usage example:
+ * @code
+ * $form['needs_accommodation'] = array(
+ *   '#type' => 'checkbox',
+ *   '#title' => 'Need Special Accommodations?',
+ * );
+ *
+ * $form['accommodation'] = array(
+ *   '#type' => 'container',
+ *   '#attributes' => array(
+ *     'class' => 'accommodation',
+ *   ),
+ *   '#states' => array(
+ *     'invisible' => array(
+ *       'input[name="needs_accommodation"]' => array('checked' => FALSE),
+ *     ),
+ *   ),
+ * );
+ *
+ * $form['accommodation']['diet'] = array(
+ *   '#type' => 'textfield',
+ *   '#title' => t('Dietary Restrictions'),
+ * );
+ * @endcode
+ *
  * @RenderElement("container")
  */
 class Container extends RenderElement {

core/lib/Drupal/Core/Render/Element/Details.php

@@ -13,9 +13,29 @@
  * Provides a render element for a details element, similar to a fieldset.
  *
  * Fieldsets can only be used in forms, while details elements can be used
- * outside of forms.
+ * outside of forms.  Users click on the the title to open or close the details
+ * element, showing or hiding the contained elements.
+ *
+ * Properties:
+ * - #title: The title of the details container. Defaults to "Details".
+ * - #open: Indicates whether the container should be open by default.
+ *   Defaults to FALSE.
+ *
+ * Usage example:
+ * @code
+ * $form['author'] = array(
+ *   '#type' => 'details',
+ *   '#title' => 'Author',
+ * );
+ *
+ * $form['author']['name'] = array(
+ *   '#type' => 'textfield',
+ *   '#title' => t('Name'),
+ * );
+ * @endcode
  *
  * @see \Drupal\Core\Render\Element\Fieldset
+ * @see \Drupal]Core\Render\Element\VerticalTabs
  *
  * @RenderElement("details")
  */

core/lib/Drupal/Core/Render/Element/Fieldgroup.php

@@ -11,7 +11,10 @@
  * Provides a render element for a group of form elements.
  *
  * In default rendering, the only difference between a 'fieldgroup' and a
- * 'fieldset' is the CSS class applied to the containing HTML element.
+ * 'fieldset' is the CSS class applied to the containing HTML element. Normally
+ * use a fieldset.
+ *
+ * @see \Drupal\Core\Render\Element\Fieldset for documentation and usage.
  *
  * @see \Drupal\Core\Render\Element\Fieldset
  * @see \Drupal\Core\Render\Element\Details

core/lib/Drupal/Core/Render/Element/Fieldset.php

@@ -12,8 +12,18 @@
 /**
  * Provides a render element for a group of form elements.
  *
- * In default rendering, the only difference between a 'fieldgroup' and a
- * 'fieldset' is the CSS class applied to the containing HTML element.
+ * Usage example:
+ * @code
+ * $form['author'] = array(
+ *   '#type' => 'fieldset',
+ *   '#title' => 'Author',
+ * );
+ *
+ * $form['author']['name'] = array(
+ *   '#type' => 'textfield',
+ *   '#title' => t('Name'),
+ * );
+ * @endcode
  *
  * @see \Drupal\Core\Render\Element\Fieldgroup
  * @see \Drupal\Core\Render\Element\Details

core/lib/Drupal/Core/Render/Element/Table.php

@@ -17,6 +17,41 @@
  * Note: Although this extends FormElement, it can be used outside the
  * context of a form.
  *
+ * Properties:
+ * - #header: An array of table header labels.
+ * - #rows: An array of the rows to be displayed. Each row is either an array
+ *   of cell contents or an array of properties as described in table.html.twig
+ *   Alternatively specify the data for the table as child elements of the table
+ *   element. Table elements would contain rows elements that would in turn
+ *   contain column elements.
+ * - #empty: Text to display when no rows are present.
+ * - #responsive: Indicates whether to add the drupal.responsive_table library
+ *   providing responsive tables.  Defaults to TRUE.
+ * - #sticky: Indicates whether to add the drupal.tableheader library that makes
+ *   table headers always visible at the top of the page. Defaults to FALSE.
+ *
+ * Usage example:
+ * @code
+ * $form['contacts'] = array(
+ *   '#type' => 'table',
+ *   '#title' => 'Sample Table',
+ *   '#header' => array('Name', 'Phone'),
+ * );
+ *
+ * for ($i=1; $i<=4; $i++) {
+ *   $form['contacts'][$i]['name'] = array(
+ *     '#type' => 'textfield',
+ *     '#title' => t('Name'),
+ *     '#title_display' => 'invisible',
+ *   );
+ *
+ *   $form['contacts'][$i]['phone'] = array(
+ *     '#type' => 'tel',
+ *     '#title' => t('Phone'),
+ *     '#title_display' => 'invisible',
+ *   );
+ * }
+ * @endcode
  * @see \Drupal\Core\Render\Element\Tableselect
  *
  * @FormElement("table")

core/lib/Drupal/Core/Render/Element/VerticalTabs.php

@@ -13,8 +13,42 @@
 /**
  * Provides a render element for vertical tabs in a form.
  *
- * Formats all child fieldsets and all non-child fieldsets whose #group is
- * assigned this element's name as vertical tabs.
+ * Formats all child and non-child details elements whose #group is assigned
+ * this element's name as vertical tabs.
+ *
+ * Properties:
+ * - #default_tab: The HTML ID of the rendered details element to be used as
+ *   the default tab. View the source of the rendered page to determine the ID.
+ *
+ * Usage example:
+ * @code
+ * $form['information'] = array(
+ *   '#type' => 'vertical_tabs',
+ *   '#default_tab' => 'edit-publication',
+ * );
+ *
+ * $form['author'] = array(
+ *   '#type' => 'details',
+ *   '#title' => 'Author',
+ *   '#group' => 'information',
+ * );
+ *
+ * $form['author']['name'] = array(
+ *   '#type' => 'textfield',
+ *   '#title' => t('Name'),
+ * );
+ *
+ * $form['publication'] = array(
+ *   '#type' => 'details',
+ *   '#title' => t('Publication'),
+ *   '#group' => 'information',
+ * );
+ *
+ * $form['publication']['publisher'] = array(
+ *   '#type' => 'textfield',
+ *   '#title' => t('Publisher'),
+ * );
+ * @endcode
  *
  * @FormElement("vertical_tabs")
  */