Document `IAttributeFormField`

diff --git a/docs/php/api/form_builder/form_fields.md b/docs/php/api/form_builder/form_fields.md
index a54843de6fadb3c9619ec63367c64db460761261..6cf0808881f268805af7b95fbbcdeeed800efbc5 100644 (file)
--- a/docs/php/api/form_builder/form_fields.md
+++ b/docs/php/api/form_builder/form_fields.md
@@ -13,7 +13,7 @@ The following form field classes cannot be instantiated directly because they ar
 ### `AbstractNumericFormField`
 
 `AbstractNumericFormField` is the abstract implementation of a form field handling a single numeric value.
-The class implements `IAutoCompleteFormField`, `IImmutableFormField`, `IInputModeFormField`, `IMaximumFormField`, `IMinimumFormField`, `INullableFormField`, `IPlaceholderFormField` and `ISuffixedFormField`.
+The class implements `IAttributeFormField`, `IAutoCompleteFormField`, `IImmutableFormField`, `IInputModeFormField`, `IMaximumFormField`, `IMinimumFormField`, `INullableFormField`, `IPlaceholderFormField` and `ISuffixedFormField`.
 If the property `$integerValues` is `true`, the form field works with integer values, otherwise it works with floating point numbers.
 The methods `step($step = null)` and `getStep()` can be used to set and get the step attribute of the `input` element.
 The default step for form fields with integer values is `1`.
@@ -30,6 +30,7 @@ The following form fields are general reusable fields without any underlying con
 `BooleanFormField` is used for boolean (`0` or `1`, `yes` or `no`) values.
 Objects of this class require a label.
 The return value of `getSaveValue()` is the integer representation of the boolean value, i.e. `0` or `1`.
+The class implements `IAttributeFormField`, `IAutoFocusFormField`, and `IImmutableFormField`.
 
 
 ### `CheckboxFormField`
@@ -58,6 +59,7 @@ Additionally, the default id of a `ClassNameFormField` object is `className`, th
 ### `DateFormField`
 
 `DateFormField` is a form field to enter a date (and optionally a time).
+The class implements `IAttributeFormField`, `IAutoFocusFormField`, `IImmutableFormField`, and `INullableFormField`.
 The following methods are specific to this form field class:
 
 - `earliestDate($earliestDate)` and `getEarliestDate()` can be used to get and set the earliest selectable/valid date and `latestDate($latestDate)` and `getLatestDate()` can be used to get and set the latest selectable/valid date.
@@ -98,6 +100,7 @@ The following methods are specific to this form field class:
 ### `ItemListFormField`
 
 `ItemListFormField` is a form field in which multiple values can be entered and returned in different formats as save value.
+The class implements `IAttributeFormField`, `IAutoFocusFormField`, `IImmutableFormField`, and `IMultipleFormField`.
 The `saveValueType($saveValueType)` and `getSaveValueType()` methods are specific to this form field class and determine the format of the save value.
 The following save value types are supported:
 
@@ -122,14 +125,14 @@ These methods do **not**, however, restrict the number of text rows that canbe e
 ### `MultipleSelectionFormField`
 
 `MultipleSelectionFormField` is a form fields that allows the selection of multiple options out of a predefined list of available options.
-The class implements `IFilterableSelectionFormField`, `IImmutableFormField`, and `INullableFormField`.
+The class implements `IAttributeFormField`, `IFilterableSelectionFormField`, `IImmutableFormField`, and `INullableFormField`.
 If the field is nullable and no option is selected, `null` is returned as the save value.
 
 
 ### `RadioButtonFormField`
 
 `RadioButtonFormField` is a form fields that allows the selection of a single option out of a predefined list of available options using radiobuttons.
-The class implements `IImmutableFormField` and `ISelectionFormField`.
+The class implements `IAttributeFormField`, `IImmutableFormField`, and `ISelectionFormField`.
 
 
 ### `RatingFormField`
@@ -168,7 +171,7 @@ If the field is nullable and the current form field value is considered `empty`
 ### `TextFormField`
 
 `TextFormField` is a form field that allows entering a single line of text.
-The class implements `IAutoCompleteFormField`, `IImmutableFormField`, `II18nFormField`, `IInputModeFormField`, `IMaximumLengthFormField`, `IMinimumLengthFormField`, `IPatternFormField`, and `IPlaceholderFormField`.
+The class implements `IAttributeFormField`, `IAutoCompleteFormField`, `IImmutableFormField`, `II18nFormField`, `IInputModeFormField`, `IMaximumLengthFormField`, `IMinimumLengthFormField`, `IPatternFormField`, and `IPlaceholderFormField`.
 
 
 ### `TitleFormField`
@@ -250,6 +253,7 @@ The following methods are specific to this form field class:
 ### `TagFormField`
 
 `TagFormField` is a form field to enter tags.
+The class implements `IAttributeFormField` and `IObjectTypeFormNode`.
 Arrays passed to `TagFormField::values()` can contain tag names as strings and `Tag` objects.
 The default label of instances of this class is `wcf.tagging.tags` and their default description is `wcf.tagging.tags.description`.
 
@@ -288,7 +292,7 @@ The relevant `UserProfile` objects can be accessed via the `getUsers()` method.
 !!! info "Only available since version 5.4."
 
 `UserPasswordField` is a form field for users' to enter their current password.
-The class implements `IAttributeFormField`, `IAutoCompleteFormField`, `IAutoFocusFormField`, and `IPlaceholderFormField`
+The class implements `IAttributeFormField`, `IAttributeFormField`, `IAutoCompleteFormField`, `IAutoFocusFormField`, and `IPlaceholderFormField`
 
 
 ### `UserGroupOptionFormField`
@@ -301,7 +305,7 @@ The default label of instances of this class is `wcf.form.field.userGroupOption`
 ### `UsernameFormField`
 
 `UsernameFormField` is used for entering one non-existing username.
-The class implements `IImmutableFormField`, `IMaximumLengthFormField`, `IMinimumLengthFormField`, `INullableFormField`, and `IPlaceholderFormField`.
+The class implements `IAttributeFormField`, `IImmutableFormField`, `IMaximumLengthFormField`, `IMinimumLengthFormField`, `INullableFormField`, and `IPlaceholderFormField`.
 As usernames have a system-wide restriction of a minimum length of 3 and a maximum length of 100 characters, these values are also used as the default value for the field’s minimum and maximum length.
 
 
@@ -393,7 +397,7 @@ WysiwygFormContainer::create('message')
 
 `WysiwygFormField` is used for wysiwyg editor form fields.
 This class should, in general, not be used directly but only via `WysiwygFormContainer`.
-The class implements `IMaximumLengthFormField`, `IMinimumLengthFormField`, and `IObjectTypeFormNode` and requires an object type of the object type definition `com.woltlab.wcf.message`.
+The class implements `IAttributeFormField`, `IMaximumLengthFormField`, `IMinimumLengthFormField`, and `IObjectTypeFormNode` and requires an object type of the object type definition `com.woltlab.wcf.message`.
 The following methods are specific to this form field class:
 
 - `autosaveId($autosaveId)` and `getAutosaveId()` can be used enable automatically saving the current editor contents in the browser using the given id.

diff --git a/docs/php/api/form_builder/structure.md b/docs/php/api/form_builder/structure.md
index a1d7e3447be64f002f36ee325945a81be68861f8..990f0f7191d674787423be08da6996caf01fae6f 100644 (file)
--- a/docs/php/api/form_builder/structure.md
+++ b/docs/php/api/form_builder/structure.md
@@ -244,6 +244,18 @@ An overview of the form fields provided by default can be found [here](form_fiel
 
 WoltLab Suite Core provides a variety of interfaces and matching traits with default implementations for several common features of form fields:
 
+#### `IAttributeFormField`
+
+!!! info "Only available since version 5.4."
+
+`IAttributeFormField` has to be implemented by form fields for which attributes can be added to the actual form element (in addition to adding attributes to the surrounding element via the attribute-related methods of `IFormNode`).
+The implementing class has to implement the methods `fieldAttribute(string $name, string $value = null): self` and `getFieldAttribute(string $name): self`/`getFieldAttributes(): array`, which are used to add and get the attributes, respectively.
+Additionally, `hasFieldAttribute(string $name): bool` has to implemented to check if a certain attribute is present, `removeFieldAttribute(string $name): self` to remove an attribute, and `static validateFieldAttribute(string $name)` to check if the attribute is valid for this specific class.
+`TAttributeFormField` provides a default implementation of these methods and `TInputAttributeFormField` specializes the trait for `input`-based form fields.
+These two traits also ensure that if a specific interface that handles a specific attribute is implemented, like `IAutoCompleteFormField` handling `autocomplete`, this attribute cannot be set with this API.
+Instead, the dedicated API provided by the relevant interface has to be used.
+
+
 
 #### `IAutoCompleteFormField`