From 8b2e3f07b281cb842e440a7ae1cced9081c3904c Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Wed, 9 Sep 2015 13:46:15 +0100
Subject: [PATCH] Issue #2486989 by metzlerd, jhodgdon: Create Documentation
For Container Form Elements
---
.../Drupal/Core/Render/Element/Actions.php | 14 ++++++-
.../Drupal/Core/Render/Element/Container.php | 25 ++++++++++++
.../Drupal/Core/Render/Element/Details.php | 22 ++++++++++-
.../Drupal/Core/Render/Element/Fieldgroup.php | 5 ++-
.../Drupal/Core/Render/Element/Fieldset.php | 14 ++++++-
core/lib/Drupal/Core/Render/Element/Table.php | 35 +++++++++++++++++
.../Core/Render/Element/VerticalTabs.php | 38 ++++++++++++++++++-
7 files changed, 145 insertions(+), 8 deletions(-)
diff --git a/core/lib/Drupal/Core/Render/Element/Actions.php b/core/lib/Drupal/Core/Render/Element/Actions.php
index 674e229ec06f..ec54183adca2 100644
--- a/core/lib/Drupal/Core/Render/Element/Actions.php
+++ b/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")
*/
diff --git a/core/lib/Drupal/Core/Render/Element/Container.php b/core/lib/Drupal/Core/Render/Element/Container.php
index 9c58f544a3f3..63a6f8e998fd 100644
--- a/core/lib/Drupal/Core/Render/Element/Container.php
+++ b/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 {
diff --git a/core/lib/Drupal/Core/Render/Element/Details.php b/core/lib/Drupal/Core/Render/Element/Details.php
index cf57bc7f4d13..a7fab35249d0 100644
--- a/core/lib/Drupal/Core/Render/Element/Details.php
+++ b/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")
*/
diff --git a/core/lib/Drupal/Core/Render/Element/Fieldgroup.php b/core/lib/Drupal/Core/Render/Element/Fieldgroup.php
index 56840b88fa3d..902b861829bb 100644
--- a/core/lib/Drupal/Core/Render/Element/Fieldgroup.php
+++ b/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
diff --git a/core/lib/Drupal/Core/Render/Element/Fieldset.php b/core/lib/Drupal/Core/Render/Element/Fieldset.php
index 9ef2070467bc..417fb9f94faf 100644
--- a/core/lib/Drupal/Core/Render/Element/Fieldset.php
+++ b/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
diff --git a/core/lib/Drupal/Core/Render/Element/Table.php b/core/lib/Drupal/Core/Render/Element/Table.php
index d636ee8bac92..c13b62312b16 100644
--- a/core/lib/Drupal/Core/Render/Element/Table.php
+++ b/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")
diff --git a/core/lib/Drupal/Core/Render/Element/VerticalTabs.php b/core/lib/Drupal/Core/Render/Element/VerticalTabs.php
index adf6bd0f7c0a..447fc06d30ab 100644
--- a/core/lib/Drupal/Core/Render/Element/VerticalTabs.php
+++ b/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")
*/
--
GitLab