From: Matthias Schmidt Date: Sat, 16 Jan 2021 08:26:34 +0000 (+0100) Subject: Document `IAttributeFormField` X-Git-Tag: 5.6.final~316^2~3 X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=a03fbb80ed5a19515a1e423e4c0db1b9011d80f6;p=GitHub%2FWoltLab%2Fwoltlab.github.io.git Document `IAttributeFormField` --- diff --git a/docs/php/api/form_builder/form_fields.md b/docs/php/api/form_builder/form_fields.md index a54843de..6cf08088 100644 --- 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 a1d7e344..990f0f71 100644 --- 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`