From 310fbddfb53599827213122d461adef9d7dfc54e Mon Sep 17 00:00:00 2001
From: Matthias Schmidt <gravatronics@live.com>
Date: Thu, 21 May 2020 20:18:38 +0200
Subject: [PATCH] Mark required fields in output when using form builder
 (#3296)

Close #3265
---
 com.woltlab.wcf/templates/__form.tpl          |  8 +++++++
 com.woltlab.wcf/templates/__formContainer.tpl |  4 ++--
 com.woltlab.wcf/templates/__formField.tpl     |  2 +-
 .../install/files/acp/templates/__form.tpl    |  8 +++++++
 .../files/acp/templates/__formContainer.tpl   |  4 ++--
 .../files/acp/templates/__formField.tpl       |  2 +-
 .../form/builder/FormDocument.class.php       | 23 +++++++++++++++++++
 .../form/builder/IFormDocument.class.php      |  8 +++++++
 .../builder/container/FormContainer.class.php |  8 +++++++
 .../container/IFormContainer.class.php        |  8 +++++++
 .../wysiwyg/WysiwygFormContainer.class.php    |  8 +++++++
 wcfsetup/install/files/style/layout/form.scss |  1 +
 12 files changed, 78 insertions(+), 6 deletions(-)

diff --git a/com.woltlab.wcf/templates/__form.tpl b/com.woltlab.wcf/templates/__form.tpl
index 8719c7e04b..d6ad54d0e6 100644
--- a/com.woltlab.wcf/templates/__form.tpl
+++ b/com.woltlab.wcf/templates/__form.tpl
@@ -61,6 +61,14 @@
 	</form>
 {/if}
 
+{if $form->needsRequiredFieldsInfo()}
+	<div class="section requiredFieldsInfo">
+		<p><span class="formFieldRequired">*</span> {lang}wcf.global.form.required{/lang}</p>
+		
+		{event name='requiredFieldsInfo'}
+	</div>
+{/if}
+
 <script data-relocate="true">
 	{* after all dependencies have been added, check them *}
 	require(['WoltLabSuite/Core/Form/Builder/Field/Dependency/Manager'], function(FormBuilderFieldDependencyManager) {
diff --git a/com.woltlab.wcf/templates/__formContainer.tpl b/com.woltlab.wcf/templates/__formContainer.tpl
index eec1c6606b..b7ff418e62 100644
--- a/com.woltlab.wcf/templates/__formContainer.tpl
+++ b/com.woltlab.wcf/templates/__formContainer.tpl
@@ -6,11 +6,11 @@
 	{if $container->getLabel() !== null}
 		{if $container->getDescription() !== null}
 			<header class="sectionHeader">
-				<h2 class="sectionTitle">{@$container->getLabel()}</h2>
+				<h2 class="sectionTitle">{@$container->getLabel()}{if $container->markAsRequired()} <span class="formFieldRequired">*</span>{/if}</h2>
 				<p class="sectionDescription">{@$container->getDescription()}</p>
 			</header>
 		{else}
-			<h2 class="sectionTitle">{@$container->getLabel()}</h2>
+			<h2 class="sectionTitle">{@$container->getLabel()}{if $container->markAsRequired()} <span class="formFieldRequired">*</span>{/if}</h2>
 		{/if}
 	{/if}
 	
diff --git a/com.woltlab.wcf/templates/__formField.tpl b/com.woltlab.wcf/templates/__formField.tpl
index d726d5aa69..d59c467b7d 100644
--- a/com.woltlab.wcf/templates/__formField.tpl
+++ b/com.woltlab.wcf/templates/__formField.tpl
@@ -1,5 +1,5 @@
 <dl id="{@$field->getPrefixedId()}Container" {if !$field->getClasses()|empty} class="{implode from=$field->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{foreach from=$field->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{if !$field->checkDependencies()} style="display: none;"{/if}>
-	<dt>{if $field->getLabel() !== null}<label for="{@$field->getPrefixedId()}">{@$field->getLabel()}</label>{/if}</dt>
+	<dt>{if $field->getLabel() !== null}<label for="{@$field->getPrefixedId()}">{@$field->getLabel()}</label>{if $field->isRequired()} <span class="formFieldRequired">*</span>{/if}{/if}</dt>
 	<dd>
 		{@$field->getFieldHtml()}
 		
diff --git a/wcfsetup/install/files/acp/templates/__form.tpl b/wcfsetup/install/files/acp/templates/__form.tpl
index 8719c7e04b..d6ad54d0e6 100644
--- a/wcfsetup/install/files/acp/templates/__form.tpl
+++ b/wcfsetup/install/files/acp/templates/__form.tpl
@@ -61,6 +61,14 @@
 	</form>
 {/if}
 
+{if $form->needsRequiredFieldsInfo()}
+	<div class="section requiredFieldsInfo">
+		<p><span class="formFieldRequired">*</span> {lang}wcf.global.form.required{/lang}</p>
+		
+		{event name='requiredFieldsInfo'}
+	</div>
+{/if}
+
 <script data-relocate="true">
 	{* after all dependencies have been added, check them *}
 	require(['WoltLabSuite/Core/Form/Builder/Field/Dependency/Manager'], function(FormBuilderFieldDependencyManager) {
diff --git a/wcfsetup/install/files/acp/templates/__formContainer.tpl b/wcfsetup/install/files/acp/templates/__formContainer.tpl
index eec1c6606b..b7ff418e62 100644
--- a/wcfsetup/install/files/acp/templates/__formContainer.tpl
+++ b/wcfsetup/install/files/acp/templates/__formContainer.tpl
@@ -6,11 +6,11 @@
 	{if $container->getLabel() !== null}
 		{if $container->getDescription() !== null}
 			<header class="sectionHeader">
-				<h2 class="sectionTitle">{@$container->getLabel()}</h2>
+				<h2 class="sectionTitle">{@$container->getLabel()}{if $container->markAsRequired()} <span class="formFieldRequired">*</span>{/if}</h2>
 				<p class="sectionDescription">{@$container->getDescription()}</p>
 			</header>
 		{else}
-			<h2 class="sectionTitle">{@$container->getLabel()}</h2>
+			<h2 class="sectionTitle">{@$container->getLabel()}{if $container->markAsRequired()} <span class="formFieldRequired">*</span>{/if}</h2>
 		{/if}
 	{/if}
 	
diff --git a/wcfsetup/install/files/acp/templates/__formField.tpl b/wcfsetup/install/files/acp/templates/__formField.tpl
index d726d5aa69..d59c467b7d 100644
--- a/wcfsetup/install/files/acp/templates/__formField.tpl
+++ b/wcfsetup/install/files/acp/templates/__formField.tpl
@@ -1,5 +1,5 @@
 <dl id="{@$field->getPrefixedId()}Container" {if !$field->getClasses()|empty} class="{implode from=$field->getClasses() item='class' glue=' '}{$class}{/implode}"{/if}{foreach from=$field->getAttributes() key='attributeName' item='attributeValue'} {$attributeName}="{$attributeValue}"{/foreach}{if !$field->checkDependencies()} style="display: none;"{/if}>
-	<dt>{if $field->getLabel() !== null}<label for="{@$field->getPrefixedId()}">{@$field->getLabel()}</label>{/if}</dt>
+	<dt>{if $field->getLabel() !== null}<label for="{@$field->getPrefixedId()}">{@$field->getLabel()}</label>{if $field->isRequired()} <span class="formFieldRequired">*</span>{/if}{/if}</dt>
 	<dd>
 		{@$field->getFieldHtml()}
 		
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 8fe3d7a93d..88308ebbe7 100644
--- a/wcfsetup/install/files/lib/system/form/builder/FormDocument.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/FormDocument.class.php
@@ -527,6 +527,29 @@ class FormDocument implements IFormDocument {
 		return $this->invalid;
 	}
 	
+	/**
+	 * @inheritDoc
+	 * @since	5.3
+	 */
+	public function needsRequiredFieldsInfo() {
+		/** @var IFormNode $node */
+		foreach ($this->getIterator() as $node) {
+			if (
+				$node->isAvailable()
+				&& $node instanceof IFormElement
+				&& $node->getLabel() !== null
+				&& (
+					($node instanceof IFormContainer && $node->markAsRequired())
+					|| ($node instanceof IFormField && $node->isRequired())
+				)
+			) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+	
 	/**
 	 * @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 7025fc9495..6009d40b2d 100644
--- a/wcfsetup/install/files/lib/system/form/builder/IFormDocument.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/IFormDocument.class.php
@@ -287,6 +287,14 @@ interface IFormDocument extends IFormParentNode {
 	 */
 	public function invalid($invalid = true);
 	
+	/**
+	 * Returns `true` if the information about required fields has to be shown below the form.
+	 * 
+	 * @return	bool
+	 * @since	5.3
+	 */
+	public function needsRequiredFieldsInfo();
+	
 	/**
 	 * Sets the updated object (and loads the field values from the given object) and returns
 	 * this document.
diff --git a/wcfsetup/install/files/lib/system/form/builder/container/FormContainer.class.php b/wcfsetup/install/files/lib/system/form/builder/container/FormContainer.class.php
index 008a3cda3b..ef92e4140d 100644
--- a/wcfsetup/install/files/lib/system/form/builder/container/FormContainer.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/container/FormContainer.class.php
@@ -58,6 +58,14 @@ class FormContainer implements IFormContainer {
 		);
 	}
 	
+	/**
+	 * @inheritDoc
+	 * @since	5.3
+	 */
+	public function markAsRequired() {
+		return false;
+	}
+	
 	/**
 	 * @inheritDoc
 	 */
diff --git a/wcfsetup/install/files/lib/system/form/builder/container/IFormContainer.class.php b/wcfsetup/install/files/lib/system/form/builder/container/IFormContainer.class.php
index efdbbb9420..e654776f28 100644
--- a/wcfsetup/install/files/lib/system/form/builder/container/IFormContainer.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/container/IFormContainer.class.php
@@ -15,6 +15,14 @@ use wcf\system\form\builder\IFormParentNode;
  * @since	5.2
  */
 interface IFormContainer extends IFormChildNode, IFormElement, IFormParentNode {
+	/**
+	 * Returns `true` if the whole container should be marked as required in the form output.
+	 * 
+	 * @return	bool
+	 * @since	5.3
+	 */
+	public function markAsRequired();
+	
 	/**
 	 * Informs the form container of the updated object and this method is called by
 	 * `IFormDocument::updatedObject()` to inform the container that object data is being loaded.
diff --git a/wcfsetup/install/files/lib/system/form/builder/container/wysiwyg/WysiwygFormContainer.class.php b/wcfsetup/install/files/lib/system/form/builder/container/wysiwyg/WysiwygFormContainer.class.php
index 51c645528c..c90f89314d 100644
--- a/wcfsetup/install/files/lib/system/form/builder/container/wysiwyg/WysiwygFormContainer.class.php
+++ b/wcfsetup/install/files/lib/system/form/builder/container/wysiwyg/WysiwygFormContainer.class.php
@@ -316,6 +316,14 @@ class WysiwygFormContainer extends FormContainer {
 		return $this->required;
 	}
 	
+	/**
+	 * @since	5.3
+	 * @inheritDoc
+	 */
+	public function markAsRequired() {
+		return $this->getWysiwygField()->isRequired();
+	}
+	
 	/**
 	 * Sets the message object type used by the wysiwyg form field.
 	 * 
diff --git a/wcfsetup/install/files/style/layout/form.scss b/wcfsetup/install/files/style/layout/form.scss
index 29dc64b66c..50d1f39181 100644
--- a/wcfsetup/install/files/style/layout/form.scss
+++ b/wcfsetup/install/files/style/layout/form.scss
@@ -279,6 +279,7 @@ input {
 	}
 }
 
+.formFieldRequired,
 .customOptionRequired {
 	color: rgba(204, 0, 1, 1) !important;
 }
-- 
2.20.1