Issue #2486999 by metzlerd, er.pushpinderrana, jhodgdon: Create Documentation For Button Form Elements

4 files changed, 65 insertions, 0 deletions

diff --git a/core/lib/Drupal/Core/Render/Element/Button.php b/core/lib/Drupal/Core/Render/Element/Button.php
index a64615744e2..29ed48a068f 100644
--- a/core/lib/Drupal/Core/Render/Element/Button.php
+++ b/core/lib/Drupal/Core/Render/Element/Button.php
@@ -16,6 +16,23 @@ use Drupal\Core\Render\Element;
  * When the button is pressed, the form will be submitted to Drupal, where it is
  * validated and rebuilt. The submit handler is not invoked.
  *
+ * Properties:
+ * - #limit_validation_errors: An array of form element keys that will block
+ *   form submission when validation for these elements or any child elements
+ *   fails. Specify an empty array to suppress all form validation errors.
+ * - #value: The text to be shown on the button.
+ *
+ *
+ * Usage Example:
+ * @code
+ * $form['actions']['preview'] = array(
+ *   '#type' => 'button',
+ *   '#value => $this->t('Preview'),
+ * );
+ * @endcode
+ *
+ * @see \Drupal\Core\Render\Element\Submit
+ *
  * @FormElement("button")
  */
 class Button extends FormElement {
diff --git a/core/lib/Drupal/Core/Render/Element/Dropbutton.php b/core/lib/Drupal/Core/Render/Element/Dropbutton.php
index 76fab8960d4..f84d7044f15 100644
--- a/core/lib/Drupal/Core/Render/Element/Dropbutton.php
+++ b/core/lib/Drupal/Core/Render/Element/Dropbutton.php
@@ -10,6 +10,36 @@ namespace Drupal\Core\Render\Element;
 /**
  * Provides a render element for a set of links rendered as a drop-down button.
  *
+ * By default, this element sets #theme so that the 'links' theme hook is used
+ * for rendering, with suffixes so that themes can override this specifically
+ * without overriding all links theming. If the #subtype property is provided in
+ * your render array with value 'foo', #theme is set to links__dropbutton__foo;
+ * if not, it's links__dropbutton; both of these can be overridden by setting
+ * the #theme property in your render array. See template_preprocess_links()
+ * for documentation on the other properties used in theming; for instance, use
+ * element property #links to provide $variables['links'] for theming.
+ *
+ * Properties:
+ * - #links: An array of links to actions. See template_preprocess_links() for
+ *   documentation the properties of links in this array.
+ *
+ * Usage Example:
+ * @code
+ * $form['actions']['extra_actions'] = array(
+ *   '#type' => 'dropbutton',
+ *   '#links' => array(
+ *     'simple_form' => array(
+ *       'title' => $this->t('Simple Form'),
+ *       'url' => Url::fromRoute('fapi_example.simple_form'),
+ *     ),
+ *     'demo' => array(
+ *       'title' => $this->t('Build Demo'),
+ *       'url' => Url::fromRoute('fapi_example.build_demo'),
+ *     ),
+ *   ),
+ * );
+ * @endcode
+ *
  * @see \Drupal\Core\Render\Element\Operations
  *
  * @RenderElement("dropbutton")
diff --git a/core/lib/Drupal/Core/Render/Element/Operations.php b/core/lib/Drupal/Core/Render/Element/Operations.php
index 89bc68b729d..dd3e3c9d745 100644
--- a/core/lib/Drupal/Core/Render/Element/Operations.php
+++ b/core/lib/Drupal/Core/Render/Element/Operations.php
@@ -14,6 +14,8 @@ namespace Drupal\Core\Render\Element;
  * difference is that it offers themes the possibility to render it differently
  * through a theme suggestion.
  *
+ * @see \Drupal|Core\Render\Element\DropButton
+ *
  * @RenderElement("operations")
  */
 class Operations extends Dropbutton {
diff --git a/core/lib/Drupal/Core/Render/Element/Submit.php b/core/lib/Drupal/Core/Render/Element/Submit.php
index 41e592d3b48..8b262273088 100644
--- a/core/lib/Drupal/Core/Render/Element/Submit.php
+++ b/core/lib/Drupal/Core/Render/Element/Submit.php
@@ -13,6 +13,22 @@ namespace Drupal\Core\Render\Element;
  * Submit buttons are processed the same as regular buttons, except they trigger
  * the form's submit handler.
  *
+ * Properties:
+ * - #submit: Specifies an alternate callback for form submission when the
+ *   submit button is pressed.  Use '::methodName' format or an array containing
+ *   the object and method name (for example, [ $this, 'methodName'] ).
+ * - #value: The text to be shown on the button.
+ *
+ * Usage Example:
+ * @code
+ * $form['actions']['submit'] = array(
+ *   '#type' => 'submit,
+ *   '#value' => $this->t('Save'),
+ * );
+ * @endcode
+ *
+ * @see \Drupal\Core\Render\Element\Button
+ *
  * @FormElement("submit")
  */
 class Submit extends Button {