From da5043c15e70249433f363deb7d0f432d6c30929 Mon Sep 17 00:00:00 2001
From: Matthias Schmidt <gravatronics@live.com>
Date: Sun, 3 Mar 2019 09:17:26 +0100
Subject: [PATCH] Add form builder button API

Close 2860
---
 com.woltlab.wcf/templates/__form.tpl          |  20 +++-
 com.woltlab.wcf/templates/__formButton.tpl    |  15 +++
 syncTemplates.json                            |   1 +
 .../install/files/acp/templates/__form.tpl    |  20 +++-
 .../files/acp/templates/__formButton.tpl      |  15 +++
 .../form/builder/FormDocument.class.php       |  83 +++++++++++++-
 .../form/builder/IFormDocument.class.php      |  37 ++++++
 .../form/builder/button/FormButton.class.php  | 105 ++++++++++++++++++
 .../form/builder/button/IFormButton.class.php |  50 +++++++++
 9 files changed, 335 insertions(+), 11 deletions(-)
 create mode 100644 com.woltlab.wcf/templates/__formButton.tpl
 create mode 100644 wcfsetup/install/files/acp/templates/__formButton.tpl
 create mode 100644 wcfsetup/install/files/lib/system/form/builder/button/FormButton.class.php
 create mode 100644 wcfsetup/install/files/lib/system/form/builder/button/IFormButton.class.php

diff --git a/com.woltlab.wcf/templates/__form.tpl b/com.woltlab.wcf/templates/__form.tpl
index dff9c392ce..08d72dccdf 100644
--- a/com.woltlab.wcf/templates/__form.tpl
+++ b/com.woltlab.wcf/templates/__form.tpl
@@ -5,17 +5,27 @@
 	});
 </script>
 
-<form method="{@$form->getMethod()}" action="{@$form->getAction()}" id="{@$form->getId()}"{if !$form->getClasses()|empty} class="{implode from=$form->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{foreach from=$form->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}>
+<form method="{@$form->getMethod()}" {*
+	*}action="{@$form->getAction()}" {*
+	*}id="{@$form->getId()}"{*
+	*}{if !$form->getClasses()|empty} class="{implode from=$form->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{*
+	*}{foreach from=$form->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{*
+*}>
 	{foreach from=$form item='child'}
 		{if $child->isAvailable()}
 			{@$child->getHtml()}
 		{/if}
 	{/foreach}
 	
-	<div class="formSubmit">
-		<input type="submit" value="{lang}wcf.global.button.submit{/lang}" accesskey="s">
-		{@SECURITY_TOKEN_INPUT_TAG}
-	</div>
+	{if !$form->getButtons()|empty}
+		<div class="formSubmit">
+			{foreach from=$form->getButtons() item=button}
+				{@$button->getHtml()}
+			{/foreach}
+		</div>
+	{/if}
+	
+	{@SECURITY_TOKEN_INPUT_TAG}
 </form>
 
 <script data-relocate="true">
diff --git a/com.woltlab.wcf/templates/__formButton.tpl b/com.woltlab.wcf/templates/__formButton.tpl
new file mode 100644
index 0000000000..f5be9fcdb9
--- /dev/null
+++ b/com.woltlab.wcf/templates/__formButton.tpl
@@ -0,0 +1,15 @@
+{if $button->isSubmit()}
+	<input id="{@$button->getPrefixedId()}" {*
+		*}type="submit" {*
+		*}value="{$button->getLabel()}"{*
+		*}{if $button->getAccessKey()} accesskey="{$button->getAccessKey()}"{/if}{*
+		*}{if !$button->getClasses()|empty} class="{implode from=$button->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{*
+		*}{foreach from=$button->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{*
+		*}>
+{else}
+	<button id="{@$button->getPrefixedId()}"{*
+		*}{if !$button->getClasses()|empty} class="{implode from=$button->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{*
+		*}{foreach from=$button->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{*
+		*}{if $button->getAccessKey()} accesskey="{$button->getAccessKey()}"{/if}{*
+	*}>{$button->getLabel()}</button>
+{/if}
diff --git a/syncTemplates.json b/syncTemplates.json
index a2097268ce..03b7378f65 100644
--- a/syncTemplates.json
+++ b/syncTemplates.json
@@ -10,6 +10,7 @@
     "__devtoolsLanguageChooser",
     "__dialogForm",
     "__form",
+    "__formButton",
     "__formContainer",
     "__formContainerChildren",
     "__formContainerDependencies",
diff --git a/wcfsetup/install/files/acp/templates/__form.tpl b/wcfsetup/install/files/acp/templates/__form.tpl
index dff9c392ce..08d72dccdf 100644
--- a/wcfsetup/install/files/acp/templates/__form.tpl
+++ b/wcfsetup/install/files/acp/templates/__form.tpl
@@ -5,17 +5,27 @@
 	});
 </script>
 
-<form method="{@$form->getMethod()}" action="{@$form->getAction()}" id="{@$form->getId()}"{if !$form->getClasses()|empty} class="{implode from=$form->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{foreach from=$form->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}>
+<form method="{@$form->getMethod()}" {*
+	*}action="{@$form->getAction()}" {*
+	*}id="{@$form->getId()}"{*
+	*}{if !$form->getClasses()|empty} class="{implode from=$form->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{*
+	*}{foreach from=$form->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{*
+*}>
 	{foreach from=$form item='child'}
 		{if $child->isAvailable()}
 			{@$child->getHtml()}
 		{/if}
 	{/foreach}
 	
-	<div class="formSubmit">
-		<input type="submit" value="{lang}wcf.global.button.submit{/lang}" accesskey="s">
-		{@SECURITY_TOKEN_INPUT_TAG}
-	</div>
+	{if !$form->getButtons()|empty}
+		<div class="formSubmit">
+			{foreach from=$form->getButtons() item=button}
+				{@$button->getHtml()}
+			{/foreach}
+		</div>
+	{/if}
+	
+	{@SECURITY_TOKEN_INPUT_TAG}
 </form>
 
 <script data-relocate="true">
diff --git a/wcfsetup/install/files/acp/templates/__formButton.tpl b/wcfsetup/install/files/acp/templates/__formButton.tpl
new file mode 100644
index 0000000000..f5be9fcdb9
--- /dev/null
+++ b/wcfsetup/install/files/acp/templates/__formButton.tpl
@@ -0,0 +1,15 @@
+{if $button->isSubmit()}
+	<input id="{@$button->getPrefixedId()}" {*
+		*}type="submit" {*
+		*}value="{$button->getLabel()}"{*
+		*}{if $button->getAccessKey()} accesskey="{$button->getAccessKey()}"{/if}{*
+		*}{if !$button->getClasses()|empty} class="{implode from=$button->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{*
+		*}{foreach from=$button->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{*
+		*}>
+{else}
+	<button id="{@$button->getPrefixedId()}"{*
+		*}{if !$button->getClasses()|empty} class="{implode from=$button->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{*
+		*}{foreach from=$button->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{*
+		*}{if $button->getAccessKey()} accesskey="{$button->getAccessKey()}"{/if}{*
+	*}>{$button->getLabel()}</button>
+{/if}
diff --git a/wcfsetup/install/files/lib/system/form/builder/FormDocument.class.php b/wcfsetup/install/files/lib/system/form/builder/FormDocument.class.php
index d7126b2d5f..a96ecadb8b 100644
--- a/wcfsetup/install/files/lib/system/form/builder/FormDocument.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/FormDocument.class.php
@@ -1,6 +1,8 @@
 <?php
 namespace wcf\system\form\builder;
 use wcf\data\IStorableObject;
+use wcf\system\form\builder\button\FormButton;
+use wcf\system\form\builder\button\IFormButton;
 use wcf\system\form\builder\container\IFormContainer;
 use wcf\system\form\builder\data\FormDataHandler;
 use wcf\system\form\builder\data\IFormDataHandler;
@@ -12,6 +14,9 @@ use wcf\system\WCF;
 /**
  * Represents a "whole" form (document).
  * 
+ * The default button of this class is a button with id `submitButton`, label `wcf.global.button.submit`,
+ * access key `s` and CSS class `buttonPrimary`.
+ * 
  * @author	Matthias Schmidt
  * @copyright	2001-2019 WoltLab GmbH
  * @license	GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
@@ -31,6 +36,12 @@ class FormDocument implements IFormDocument {
 	 */
 	protected $action;
 	
+	/**
+	 * `true` if the default button is added and `false` otherwise
+	 * @var	boolean
+	 */
+	protected $addDefaultButton = true;
+	
 	/**
 	 * `true` if form is requested via an AJAX request or processes data via an AJAX request
 	 * and `false` otherwise
@@ -39,7 +50,13 @@ class FormDocument implements IFormDocument {
 	protected $ajax;
 	
 	/**
-	 * data handler for this document
+	 * buttons registered for this form document
+	 * @var	IFormButton[]
+	 */
+	protected $buttons = [];
+	
+	/**
+	 * data handler for this form document
 	 * @var	IFormDataHandler
 	 */
 	protected $dataHandler;
@@ -97,6 +114,30 @@ class FormDocument implements IFormDocument {
 		return $this;
 	}
 	
+	/**
+	 * @inheritDoc
+	 */
+	public function addButton(IFormButton $button) {
+		$this->buttons[] = $button;
+		
+		$button->parent($this);
+		
+		return $this;
+	}
+	
+	/**
+	 * @inheritDoc
+	 */
+	public function addDefaultButton($addDefaultButton = true) {
+		if ($this->isBuilt) {
+			throw new \BadMethodCallException("After the form document has already been built, changing whether the default button is added is no possible anymore.");
+		}
+		
+		$this->addDefaultButton = $addDefaultButton;
+		
+		return $this;
+	}
+	
 	/**
 	 * @inheritDoc
 	 */
@@ -114,6 +155,11 @@ class FormDocument implements IFormDocument {
 			throw new \BadMethodCallException("Form document has already been built.");
 		}
 		
+		// add default button
+		if ($this->hasDefaultButton()) {
+			$this->createDefaultButton();
+		}
+		
 		$nodeIds = [];
 		$doubleNodeIds = [];
 		
@@ -135,6 +181,15 @@ class FormDocument implements IFormDocument {
 			}
 		}
 		
+		foreach ($this->getButtons() as $button) {
+			if (in_array($button->getId(), $nodeIds)) {
+				$doubleNodeIds[] = $button->getId();
+			}
+			else {
+				$nodeIds[] = $button->getId();
+			}
+		}
+		
 		if (!empty($doubleNodeIds)) {
 			throw new \LogicException("Non-unique node id" . (count($doubleNodeIds) > 1 ? 's' : '') . " '" . implode("', '", $doubleNodeIds) . "'.");
 		}
@@ -144,6 +199,18 @@ class FormDocument implements IFormDocument {
 		return $this;
 	}
 	
+	/**
+	 * Creates the default button for this form document.
+	 */
+	protected function createDefaultButton() {
+		$this->addButton(
+			FormButton::create('submitButton')
+				->label('wcf.global.button.submit')
+				->accessKey('s')
+				->addClass('buttonPrimary')
+		);
+	}
+	
 	/**
 	 * @inheritDoc
 	 */
@@ -172,6 +239,13 @@ class FormDocument implements IFormDocument {
 		return $this->action;
 	}
 	
+	/**
+	 * @inheritDoc
+	 */
+	public function getButtons() {
+		return $this->buttons;
+	}
+
 	/**
 	 * @inheritDoc
 	 */
@@ -277,6 +351,13 @@ class FormDocument implements IFormDocument {
 		return $this->requestData;
 	}
 	
+	/**
+	 * @inheritDoc
+	 */
+	public function hasDefaultButton() {
+		return $this->addDefaultButton;
+	}
+	
 	/**
 	 * @inheritDoc
 	 */
diff --git a/wcfsetup/install/files/lib/system/form/builder/IFormDocument.class.php b/wcfsetup/install/files/lib/system/form/builder/IFormDocument.class.php
index 5f37e7ab57..ba9314b8ce 100644
--- a/wcfsetup/install/files/lib/system/form/builder/IFormDocument.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/IFormDocument.class.php
@@ -1,6 +1,7 @@
 <?php
 namespace wcf\system\form\builder;
 use wcf\data\IStorableObject;
+use wcf\system\form\builder\button\IFormButton;
 use wcf\system\form\builder\data\IFormDataHandler;
 
 /**
@@ -35,6 +36,24 @@ interface IFormDocument extends IFormParentNode {
 	 */
 	public function action($action);
 	
+	/**
+	 * Adds the given button to the `formSubmit` element at the end of the form and returns this
+	 * document.
+	 * 
+	 * @param	IFormButton	$button		added button
+	 * @return	static				this document
+	 */
+	public function addButton(IFormButton $button);
+	
+	/**
+	 * Sets whether the default button is added to the form during in the `build()` method.
+	 * 
+	 * @param	boolean		$addDefaultButton
+	 * @return	static				this document
+	 * @throws	\BadMethodCallException		if the form has already been built
+	 */
+	public function addDefaultButton($addDefaultButton = true);
+	
 	/**
 	 * Sets whether this form is requested via an AJAX request or processes data via an AJAX
 	 * request and returns his document.
@@ -77,6 +96,13 @@ interface IFormDocument extends IFormParentNode {
 	 */
 	public function getAction();
 	
+	/**
+	 * Returns the buttons registered for this form document.
+	 * 
+	 * @return	IFormButton[]
+	 */
+	public function getButtons();
+	
 	/**
 	 * Returns the array passed as the `$parameters` argument of the constructor
 	 * of a database object action.
@@ -147,6 +173,17 @@ interface IFormDocument extends IFormParentNode {
 	 */
 	public function getRequestData($index = null);
 	
+	/**
+	 * Returns `true` if the default button is added to the form during in the `build()` method
+	 * and `false` otherwise.
+	 * 
+	 * By default, the default button is added.
+	 * Each implementing class can define itself what it considers its default button.
+	 * 
+	 * @return	boolean
+	 */
+	public function hasDefaultButton();
+	
 	/**
 	 * Returns `true` if there is any request data or, if a parameter is given, if
 	 * there is request data with a specific index.
diff --git a/wcfsetup/install/files/lib/system/form/builder/button/FormButton.class.php b/wcfsetup/install/files/lib/system/form/builder/button/FormButton.class.php
new file mode 100644
index 0000000000..e3262e7191
--- /dev/null
+++ b/wcfsetup/install/files/lib/system/form/builder/button/FormButton.class.php
@@ -0,0 +1,105 @@
+<?php
+namespace wcf\system\form\builder\button;
+use wcf\system\form\builder\TFormChildNode;
+use wcf\system\form\builder\TFormElement;
+use wcf\system\WCF;
+
+/**
+ * Default implementation of a form button.
+ * 
+ * @author	Matthias Schmidt
+ * @copyright	2001-2019 WoltLab GmbH
+ * @license	GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @package	WoltLabSuite\Core\System\Form\Builder\Button
+ * @since	5.2
+ */
+class FormButton implements IFormButton {
+	use TFormChildNode;
+	use TFormElement;
+	
+	/**
+	 * access key for this form button or `null` if no access key has been set
+	 * @var	null|string
+	 */
+	protected $accessKey;
+	
+	/**
+	 * `true` this button is an `input[type=submit]` element and `false` if it is a `button` element
+	 * @var	boolean
+	 */
+	protected $submit = false;
+	
+	/**
+	 * @inheritDoc
+	 */
+	protected $templateName = '__formButton';
+	
+	/**
+	 * @inheritDoc
+	 */
+	public function accessKey($accessKey = null) {
+		// the value [of the accesskey attribute] must be an ordered set of unique
+		// space-separated tokens that are case-sensitive, each of which must be exactly
+		// one Unicode code point in length.
+		// Source: https://www.w3.org/TR/html50/editing.html#the-accesskey-attribute
+		if ($accessKey !== null) {
+			$splitAccessKey = array_unique(explode(' ', $accessKey));
+			foreach ($splitAccessKey as $accessKey) {
+				if (mb_strlen($accessKey) !== 1) {
+					throw new \InvalidArgumentException("The given access key contains an access key longer than one character: '{$accessKey}'.");
+				}
+			}
+		}
+		
+		$this->accessKey = $accessKey;
+		
+		return $this;
+	}
+	
+	/**
+	 * @inheritDoc
+	 */
+	public function getAccessKey() {
+		return $this->accessKey;
+	}
+	
+	/**
+	 * @inheritDoc
+	 */
+	public function getHtml() {
+		return WCF::getTPL()->fetch(
+			$this->templateName,
+			'wcf',
+			[
+				'button' => $this
+			]
+		);
+	}
+	
+	/**
+	 * @inheritDoc
+	 */
+	public function isSubmit() {
+		return $this->submit;
+	}
+	
+	/**
+	 * @inheritDoc
+	 */
+	public function submit($submit = true) {
+		$this->submit = $submit;
+		
+		if ($this->isSubmit() && $this->getLabel() === null) {
+			$this->label('wcf.global.button.submit');
+		}
+		
+		return $this;
+	}
+	
+	/**
+	 * @inheritDoc
+	 */
+	public function validate() {
+		// does nothing
+	}
+}
diff --git a/wcfsetup/install/files/lib/system/form/builder/button/IFormButton.class.php b/wcfsetup/install/files/lib/system/form/builder/button/IFormButton.class.php
new file mode 100644
index 0000000000..62bf969d53
--- /dev/null
+++ b/wcfsetup/install/files/lib/system/form/builder/button/IFormButton.class.php
@@ -0,0 +1,50 @@
+<?php
+namespace wcf\system\form\builder\button;
+use wcf\system\form\builder\IFormChildNode;
+use wcf\system\form\builder\IFormElement;
+
+/**
+ * Represents a form button that is shown at the end of the form.
+ * 
+ * @author	Matthias Schmidt
+ * @copyright	2001-2019 WoltLab GmbH
+ * @license	GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @package	WoltLabSuite\Core\System\Form\Builder\Button
+ * @since	5.2
+ */
+interface IFormButton extends IFormChildNode, IFormElement {
+	/**
+	 * Sets the access key for this form button and returns this form button. If `null` is passed,
+	 * the previously set access key is unset.
+	 * 
+	 * @param	null|string	$accessKey	button access key
+	 * @return	static				this form button
+	 * @throws	\InvalidArgumentException	if the given access key is invalid
+	 */
+	public function accessKey($accessKey = null);
+	
+	/**
+	 * Returns the access key for this form button or `null` if no access key has been set.
+	 * 
+	 * By default, no access key is set.
+	 * 
+	 * @return	null|string
+	 */
+	public function getAccessKey();
+	
+	/**
+	 * Returns `true` this button is an `input[type=submit]` element and `false` if it is a `button`
+	 * element.
+	 * 
+	 * @return	boolean
+	 */
+	public function isSubmit();
+	
+	/**
+	 * Sets whether this button is an `input[type=submit]` element or a `button` element. 
+	 * 
+	 * @param	boolean		$submitButton
+	 * @return	static				this form button
+	 */
+	public function submit($submitButton = true);
+}
-- 
2.20.1