docs/php/api/form_builder/structure.md

   1 # Structure of Form Builder
   2
   3 Forms built with form builder consist of three major structural elements listed from top to bottom:
   4
   5 1. form document,
   6 1. form container,
   7 1. form field.
   8
   9 The basis for all three elements are form nodes.
  10
  11 !!! info "The form builder API uses fluent interfaces heavily, meaning that unless a method is a getter, it generally returns the objects itself to support method chaining."
  12
  13
  14 ## Form Nodes
  15
  16 - `IFormNode` is the base interface that any node of a form has to implement.
  17 - `IFormChildNode` extends `IFormNode` for such elements of a form that can be a child node to a parent node.
  18 - `IFormParentNode` extends `IFormNode` for such elements of a form that can be a parent to child nodes.
  19 - `IFormElement` extends `IFormNode` for such elements of a form that can have a description and a label.
  20
  21
  22 ### `IFormNode`
  23
  24 `IFormNode` is the base interface that any node of a form has to implement and it requires the following methods:
  25
  26 - `addClass($class)`, `addClasses(array $classes)`, `removeClass($class)`, `getClasses()`, and `hasClass($class)` add, remove, get, and check for CSS classes of the HTML element representing the form node.
  27   If the form node consists of multiple (nested) HTML elements, the classes are generally added to the top element.
  28   `static validateClass($class)` is used to check if a given CSS class is valid.
  29   By default, a form node has no CSS classes.
  30 - `addDependency(IFormFieldDependency $dependency)`, `removeDependency($dependencyId)`, `getDependencies()`, and `hasDependency($dependencyId)` add, remove, get, and check for dependencies of this form node on other form fields.
  31   `checkDependencies()` checks if **all** of the node’s dependencies are met and returns a boolean value reflecting the check’s result.
  32   The [form builder dependency documentation](dependencies.md) provides more detailed information about dependencies and how they work.
  33   By default, a form node has no dependencies.
  34 - `attribute($name, $value = null)`, `removeAttribute($name)`, `getAttribute($name)`, `getAttributes()`, `hasAttribute($name)` add, remove, get, and check for attributes of the HTML element represting the form node.
  35   The attributes are added to the same element that the CSS classes are added to.
  36   `static validateAttribute($name)` is used to check if a given attribute is valid.
  37   By default, a form node has no attributes.
  38 - `available($available = true)` and `isAvailable()` can be used to set and check if the node is available.
  39   The availability functionality can be used to easily toggle form nodes based, for example, on options without having to create a condition to append the relevant.
  40   This way of checking availability makes it easier to set up forms.
  41   By default, every form node is available.
  42
  43   The following aspects are important when working with availability:
  44
  45   - Unavailable fields produce no output, their value is not read, they are not validated and they are not checked for save values.
  46   - Form fields are also able to mark themselves as unavailable, for example, a selection field without any options.
  47   - Form containers are automatically unavailable if they contain no available children.
  48
  49   Availability sets the static availability for form nodes that does not change during the lifetime of a form.
  50   In contrast, dependencies represent a dynamic availability for form nodes that depends on the current value of certain form fields.
  51 - `cleanup()` is called after the whole form is not used anymore to reset other APIs if the form fields depends on them and they expect such a reset.
  52   This method is not intended to clean up the form field’s value as a new form document object is created to show a clean form.
  53 - `getDocument()` returns the `IFormDocument` object the node belongs to.
  54   (As `IFormDocument` extends `IFormNode`, form document objects simply return themselves.)
  55 - `getHtml()` returns the HTML representation of the node.
  56   `getHtmlVariables()` return template variables (in addition to the form node itself) to render the node’s HTML representation.
  57 - `id($id)` and `getId()` set and get the id of the form node.
  58   Every id has to be unique within a form.
  59   `getPrefixedId()` returns the prefixed version of the node’s id (see `IFormDocument::getPrefix()` and `IFormDocument::prefix()`).
  60   `static validateId($id)` is used to check if a given id is valid.
  61 - `populate()` is called by `IFormDocument::build()` after all form nodes have been added.
  62   This method should finilize the initialization of the form node after all parent-child relations of the form document have been established.
  63   This method is needed because during the construction of a form node, it neither knows the form document it will belong to nor does it know its parent.
  64 - `validate()` checks, after the form is submitted, if the form node is valid.
  65   A form node with children is valid if all of its child nodes are valid.
  66   A form field is valid if its value is valid.
  67 - `static create($id)` is the factory method that has to be used to create new form nodes with the given id.
  68
  69 `TFormNode` provides a default implementation of most of these methods.
  70
  71
  72 ### `IFormChildNode`
  73
  74 `IFormChildNode` extends `IFormNode` for such elements of a form that can be a child node to a parent node and it requires the `parent(IFormParentNode $parentNode)` and `getParent()` methods used to set and get the node’s parent node.
  75 `TFormChildNode` provides a default implementation of these two methods and also of `IFormNode::getDocument()`.
  76
  77
  78 ### `IFormParentNode`
  79
  80 `IFormParentNode` extends `IFormNode` for such elements of a form that can be a parent to child nodes.
  81 Additionally, the interface also extends `\Countable` and `\RecursiveIterator`.
  82 The interface requires the following methods:
  83
  84 - `appendChild(IFormChildNode $child)`, `appendChildren(array $children)`, `insertAfter(IFormChildNode $child, $referenceNodeId)`, and `insertBefore(IFormChildNode $child, $referenceNodeId)` are used to insert new children either at the end or at specific positions.
  85   `validateChild(IFormChildNode $child)` is used to check if a given child node can be added.
  86   A child node cannot be added if it would cause an id to be used twice.
  87 - `children()` returns the direct children of a form node.
  88 - `getIterator()` return  a recursive iterator for a form node.
  89 - `getNodeById($nodeId)` returns the node with the given id by searching for it in the node’s children and recursively in all of their children.
  90   `contains($nodeId)` can be used to simply check if a node with the given id exists.
  91 - `hasValidationErrors()` checks if a form node or any of its children has a validation error (see `IFormField::getValidationErrors()`).
  92 - `readValues()` recursively calls `IFormParentNode::readValues()` and `IFormField::readValue()` on its children.
  93
  94
  95 ### `IFormElement`
  96
  97 `IFormElement` extends `IFormNode` for such elements of a form that can have a description and a label and it requires the following methods:
  98
  99 - `label($languageItem = null, array $variables = [])` and `getLabel()` can be used to set and get the label of the form element.
 100   `requiresLabel()` can be checked if the form element requires a label.
 101   A label-less form element that requires a label will prevent the form from being rendered by throwing an exception.
 102 - `description($languageItem = null, array $variables = [])` and `getDescription()` can be used to set and get the description of the form element.
 103
 104
 105 ### `IObjectTypeFormNode`
 106
 107 `IObjectTypeFormField` has to be implemented by form nodes that rely on a object type of a specific object type definition in order to function.
 108 The implementing class has to implement the methods `objectType($objectType)`, `getObjectType()`, and `getObjectTypeDefinition()`.
 109 `TObjectTypeFormNode` provides a default implementation of these three methods.
 110
 111
 112 ### `CustomFormNode`
 113
 114 `CustomFormNode` is a form node whose contents can be set directly via `content($content)`.
 115
 116 !!! warning "This class should generally not be relied on. Instead, `TemplateFormNode` should be used."
 117
 118
 119 ### `TemplateFormNode`
 120
 121 `TemplateFormNode` is a form node whose contents are read from a template.
 122 `TemplateFormNode` has the following additional methods:
 123
 124 - `application($application)` and `getApplicaton()` can be used to set and get the abbreviation of the application the shown template belongs to.
 125   If no template has been set explicitly, `getApplicaton()` returns `wcf`.
 126 - `templateName($templateName)` and `getTemplateName()` can be used to set and get the name of the template containing the node contents.
 127   If no template has been set and the node is rendered, an exception will be thrown.
 128 - `variables(array $variables)` and `getVariables()` can be used to set and get additional variables passed to the template.
 129
 130
 131 ## Form Document
 132
 133 A form document object represents the form as a whole and has to implement the `IFormDocument` interface.
 134 WoltLab Suite provides a default implementation with the `FormDocument` class.
 135 `IFormDocument` should not be implemented directly but instead `FormDocument` should be extended to avoid issues if the `IFormDocument` interface changes in the future.
 136
 137 `IFormDocument` extends `IFormParentNode` and requires the following additional methods:
 138
 139 - `action($action)` and `getAction()` can be used set and get the `action` attribute of the `<form>` HTML element.
 140 - `addButton(IFormButton $button)` and `getButtons()` can be used add and get form buttons that are shown at the bottom of the form.
 141   `addDefaultButton($addDefaultButton)` and `hasDefaultButton()` can be used to set and check if the form has the default button which is added by default unless specified otherwise.
 142   Each implementing class may define its own default button.
 143   `FormDocument` has a button with id `submitButton`, label `wcf.global.button.submit`, access key `s`, and CSS class `buttonPrimary` as its default button.
 144 - `ajax($ajax)` and `isAjax()` can be used to set and check if the form document is requested via an AJAX request or processes data via an AJAX request.
 145   These methods are helpful for form fields that behave differently when providing data via AJAX.
 146 - `build()` has to be called once after all nodes have been added to this document to trigger `IFormNode::populate()`.
 147 - `formMode($formMode)` and `getFormMode()` sets the form mode.
 148   Possible form modes are:
 149
 150   - `IFormDocument::FORM_MODE_CREATE` has to be used when the form is used to create a new object.
 151   - `IFormDocument::FORM_MODE_UPDATE` has to be used when the form is used to edit an existing object.
 152 - `getData()` returns the array containing the form data and which is passed as the `$parameters` argument of the constructor of a database object action object.
 153 - `getDataHandler()` returns the data handler for this document that is used to process the field data into a parameters array for the constructor of a database object action object.
 154 - `getEnctype()` returns the encoding type of the form.
 155   If the form contains a `IFileFormField`, `multipart/form-data` is returned, otherwise `null` is returned.
 156 - `loadValues(array $data, IStorableObject $object)` is used when editing an existing object to set the form field values by calling `IFormField::loadValue()` for all form fields.
 157   Additionally, the form mode is set to `IFormDocument::FORM_MODE_UPDATE`.
 158 - <span class="label label-info">5.4+</span> `markRequiredFields(bool $markRequiredFields = true): self` and `marksRequiredFields(): bool` can be used to set and check whether fields that are required are marked (with an asterisk in the label) in the output.
 159 - `method($method)` and `getMethod()` can be used to set and get the `method` attribute of the `<form>` HTML element.
 160   By default, the method is `post`.
 161 - `prefix($prefix)` and `getPrefix()` can be used to set and get a global form prefix that is prepended to form elements’ names and ids to avoid conflicts with other forms.
 162   By default, the prefix is an empty string.
 163   If a prefix of `foo` is set, `getPrefix()` returns `foo_` (additional trailing underscore).
 164 - `requestData(array $requestData)`, `getRequestData($index = null)`, and `hasRequestData($index = null)` can be used to set, get and check for specific request data.
 165   In most cases, the relevant request data is the `$_POST` array.
 166   In default AJAX requests handled by database object actions, however, the request data generally is in `AbstractDatabaseObjectAction::$parameters`.
 167   By default, `$_POST` is the request data.
 168
 169 The last aspect is relevant for `DialogFormDocument` objects.
 170 `DialogFormDocument` is a specialized class for forms in dialogs that, in contrast to `FormDocument` do not require an `action` to be set.
 171 Additionally, `DialogFormDocument` provides the `cancelable($cancelable = true)` and `isCancelable()` methods used to determine if the dialog from can be canceled.
 172 By default, dialog forms are cancelable.
 173
 174
 175 ## Form Button
 176
 177 A form button object represents a button shown at the end of the form that, for example, submits the form.
 178 Every form button has to implement the `IFormButton` interface that extends `IFormChildNode` and `IFormElement`.
 179 `IFormButton` requires four methods to be implemented:
 180
 181 - `accessKey($accessKey)` and `getAccessKey()` can be used to set and get the access key with which the form button can be activated.
 182   By default, form buttons have no access key set.
 183 - `submit($submitButton)` and `isSubmit()` can be used to set and check if the form button is a submit button.
 184   A submit button is an `input[type=submit]` element.
 185   Otherwise, the button is a `button` element.
 186
 187
 188 ## Form Container
 189
 190 A form container object represents a container for other form containers or form field directly.
 191 Every form container has to implement the `IFormContainer` interface which requires the following method:
 192
 193 - `loadValues(array $data, IStorableObject $object)` is called by `IFormDocument::loadValuesFromObject()` to inform the container that object data is loaded.
 194   This method is *not* intended to generally call `IFormField::loadValues()` on its form field children as these methods are already called by `IFormDocument::loadValuesFromObject()`.
 195   This method is intended for specialized form containers with more complex logic.
 196
 197 There are multiple default container implementations:
 198
 199 1. `FormContainer` is the default implementation of `IFormContainer`.
 200 1. `TabMenuFormContainer` represents the container of tab menu, while
 201 1. `TabFormContainer` represents a tab of a tab menu and
 202 1. `TabTabMenuFormContainer` represents a tab of a tab menu that itself contains a tab menu.
 203 1. The children of `RowFormContainer` are shown in a row and should use `col-*` classes.
 204 1. The children of `RowFormFieldContainer` are also shown in a row but does not show the labels and descriptions of the individual form fields.
 205    Instead of the individual labels and descriptions, the container's label and description is shown and both span all of fields.
 206 1. `SuffixFormFieldContainer` can be used for one form field with a second selection form field used as a suffix.
 207
 208 The methods of the interfaces that `FormContainer` is implementing are well documented, but here is a short overview of the most important methods when setting up a form or extending a form with an event listener:
 209
 210 - `appendChild(IFormChildNode $child)`, `appendChildren(array $children)`, and `insertBefore(IFormChildNode $child, $referenceNodeId)` are used to insert new children into the form container.
 211 - `description($languageItem = null, array $variables = [])` and `label($languageItem = null, array $variables = [])` are used to set the description and the label or title of the form container.
 212
 213
 214 ## Form Field
 215
 216 A form field object represents a concrete form field that allows entering data.
 217 Every form field has to implement the `IFormField` interface which extends `IFormChildNode` and `IFormElement`.
 218
 219 `IFormField` requires the following additional methods:
 220
 221 - `addValidationError(IFormFieldValidationError $error)` and `getValidationErrors()` can be used to get and set validation errors of the form field (see [form validation](validation_data.md#form-validation)).
 222 - `addValidator(IFormFieldValidator $validator)`, `getValidators()`, `removeValidator($validatorId)`, and `hasValidator($validatorId)` can be used to get, set, remove, and check for validators for the form field (see [form validation](validation_data.md#form-validation)).
 223 - `getFieldHtml()` returns the field's HTML output without the surrounding `dl` structure.
 224 - `objectProperty($objectProperty)` and `getObjectProperty()` can be used to get and set the object property that the field represents.
 225   When setting the object property is set to an empty string, the previously set object property is unset.
 226   If no object property has been set, the field’s (non-prefixed) id is returned.
 227
 228   The object property allows having different fields (requiring different ids) that represent the same object property which is handy when available options of the field’s value depend on another field.
 229   Having object property allows to define different fields for each value of the other field and to use form field dependencies to only show the appropriate field.
 230 - `readValue()` reads the form field value from the request data after the form is submitted.
 231 - `required($required = true)` and `isRequired()` can be used to determine if the form field has to be filled out.
 232   By default, form fields do not have to be filled out.
 233 - `value($value)` and `getSaveValue()` can be used to get and set the value of the form field to be used outside of the context of forms.
 234   `getValue()`, in contrast, returns the internal representation of the form field’s value.
 235   In general, the internal representation is only relevant when validating the value in additional validators.
 236   `loadValue(array $data, IStorableObject $object)` extracts the form field value from the given data array (and additional, non-editable data from the object if the field needs them).
 237
 238 `AbstractFormField` provides default implementations of many of the listed methods above and should be extended instead of implementing `IFormField` directly.
 239
 240 An overview of the form fields provided by default can be found [here](form_fields.md).
 241
 242
 243 ### Form Field Interfaces and Traits
 244
 245 WoltLab Suite Core provides a variety of interfaces and matching traits with default implementations for several common features of form fields:
 246
 247 #### `IAttributeFormField`
 248
 249 !!! info "Only available since version 5.4."
 250
 251 `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`).
 252 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.
 253 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.
 254 `TAttributeFormField` provides a default implementation of these methods and `TInputAttributeFormField` specializes the trait for `input`-based form fields.
 255 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.
 256 Instead, the dedicated API provided by the relevant interface has to be used.
 257
 258
 259 #### `IAutoCompleteFormField`
 260
 261 !!! info "Only available since version 5.4."
 262
 263 `IAutoCompleteFormField` has to be implemented by form fields that support the [`autocomplete` attribute](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofilling-form-controls:-the-autocomplete-attribute).
 264 The implementing class has to implement the methods `autoComplete(?string $autoComplete): self` and `getAutoComplete(): ?string`, which are used to set and get the autocomplete value, respectively.
 265 `TAutoCompleteFormField` provides a default implementation of these two methods and `TTextAutoCompleteFormField` specializes the trait for text form fields.
 266 When using `TAutoCompleteFormField`, you have to implement the `getValidAutoCompleteTokens(): array` method which returns all valid `autocomplete` tokens.
 267
 268
 269 #### `IAutoFocusFormField`
 270
 271 `IAutoFocusFormField` has to be implemented by form fields that can be auto-focused.
 272 The implementing class has to implement the methods `autoFocus($autoFocus = true)` and `isAutoFocused()`.
 273 By default, form fields are not auto-focused.
 274 `TAutoFocusFormField` provides a default implementation of these two methods.
 275
 276
 277 #### `ICssClassFormField`
 278
 279 !!! info "Only available since version 5.4."
 280
 281 `ICssClassFormField` has to be implemented by form fields for which CSS classes can be added to the actual form element (in addition to adding CSS classes to the surrounding element via the class-related methods of `IFormNode`).
 282 The implementing class has to implement the methods `addFieldClass(string $class): self`/`addFieldClasses(array $classes): self` and `getFieldClasses(): array`, which are used to add and get the CSS classes, respectively.
 283 Additionally, `hasFieldClass(string $class): bool` has to implemented to check if a certain CSS class is present and `removeFieldClass(string $class): self` to remove a CSS class.
 284 `TCssClassFormField` provides a default implementation of these methods.
 285
 286
 287 #### `IFileFormField`
 288
 289 `IFileFormField` has to be implemented by every form field that uploads files so that the `enctype` attribute of the form document is `multipart/form-data` (see `IFormDocument::getEnctype()`).
 290
 291
 292 #### `IFilterableSelectionFormField`
 293
 294 `IFilterableSelectionFormField` extends `ISelectionFormField` by the possibilty for users when selecting the value(s) to filter the list of available options.
 295 The implementing class has to implement the methods `filterable($filterable = true)` and `isFilterable()`.
 296 `TFilterableSelectionFormField` provides a default implementation of these two methods.
 297
 298
 299 #### `II18nFormField`
 300
 301 `II18nFormField` has to be implemented by form fields if the form field value can be entered separately for all available languages.
 302 The implementing class has to implement the following methods:
 303
 304 - `i18n($i18n = true)` and `isI18n()` can be used to set whether a specific instance of the class actually supports multilingual input.
 305 - `i18nRequired($i18nRequired = true)` and `isI18nRequired()` can be used to set whether a specific instance of the class requires separate values for all languages.
 306 - `languageItemPattern($pattern)` and `getLanguageItemPattern()` can be used to set the pattern/regular expression for the language item used to save the multilingual values.
 307 - `hasI18nValues()` and `hasPlainValue()` check if the current value is a multilingual or monolingual value.
 308
 309 `TI18nFormField` provides a default implementation of these eight methods and additional default implementations of some of the `IFormField` methods.
 310 If multilingual input is enabled for a specific form field, classes using `TI18nFormField` register a [custom form field data processor](validation_data.md#customformfielddataprocessor) to add the array with multilingual input into the `$parameters` array directly using `{$objectProperty}_i18n` as the array key.
 311 If multilingual input is enabled but only a monolingual value is entered, the custom form field data processor does nothing and the form field’s value is added by the `DefaultFormDataProcessor` into the `data` sub-array of the `$parameters` array.
 312
 313 !!! info "`TI18nFormField` already provides a default implementation of `IFormField::validate()`."
 314
 315
 316 #### `IImmutableFormField`
 317
 318 `IImmutableFormField` has to be implemented by form fields that support being displayed but whose value cannot be changed.
 319 The implementing class has to implement the methods `immutable($immutable = true)` and `isImmutable()` that can be used to determine if the value of the form field is mutable or immutable.
 320 By default, form field are mutable.
 321
 322
 323 #### `IInputModeFormField`
 324
 325 !!! info "Only available since version 5.4."
 326
 327 `IInputModeFormField` has to be implemented by form fields that support the [`inputmode` attribute](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute).
 328 The implementing class has to implement the methods `inputMode(?string $inputMode): self` and `getInputMode(): ?string`, which are used to set and get the input mode, respectively.
 329 `TInputModeFormField` provides a default implementation of these two methods.
 330
 331
 332 #### `IMaximumFormField`
 333
 334 `IMaximumFormField` has to be implemented by form fields if the entered value must have a maximum value.
 335 The implementing class has to implement the methods `maximum($maximum = null)` and `getMaximum()`.
 336 A maximum of `null` signals that no maximum value has been set.
 337 `TMaximumFormField` provides a default implementation of these two methods.
 338
 339 !!! warning "The implementing class has to validate the entered value against the maximum value manually."
 340
 341
 342 #### `IMaximumLengthFormField`
 343
 344 `IMaximumLengthFormField` has to be implemented by form fields if the entered value must have a maximum length.
 345 The implementing class has to implement the methods `maximumLength($maximumLength = null)`, `getMaximumLength()`, and `validateMaximumLength($text, Language $language = null)`.
 346 A maximum length of `null` signals that no maximum length has been set.
 347 `TMaximumLengthFormField` provides a default implementation of these two methods.
 348
 349 !!! warning "The implementing class has to validate the entered value against the maximum value manually by calling `validateMaximumLength()`."
 350
 351
 352 #### `IMinimumFormField`
 353
 354 `IMinimumFormField` has to be implemented by form fields if the entered value must have a minimum value.
 355 The implementing class has to implement the methods `minimum($minimum = null)` and `getMinimum()`.
 356 A minimum of `null` signals that no minimum value has been set.
 357 `TMinimumFormField` provides a default implementation of these three methods.
 358
 359 !!! warning "The implementing class has to validate the entered value against the minimum value manually."
 360
 361
 362 #### `IMinimumLengthFormField`
 363
 364 `IMinimumLengthFormField` has to be implemented by form fields if the entered value must have a minimum length.
 365 The implementing class has to implement the methods `minimumLength($minimumLength = null)`, `getMinimumLength()`, and `validateMinimumLength($text, Language $language = null)`.
 366 A minimum length of `null` signals that no minimum length has been set.
 367 `TMinimumLengthFormField` provides a default implementation of these three methods.
 368
 369 !!! warning "The implementing class has to validate the entered value against the minimum value manually by calling `validateMinimumLength()`."
 370
 371
 372 #### `IMultipleFormField`
 373
 374 `IMinimumLengthFormField` has to be implemented by form fields that support selecting or setting multiple values.
 375 The implementing class has to implement the following methods:
 376
 377 - `multiple($multiple = true)` and `allowsMultiple()` can be used to set whether a specific instance of the class actually should support multiple values.
 378   By default, multiple values are not supported.
 379 - `minimumMultiples($minimum)` and `getMinimumMultiples()` can be used to set the minimum number of values that have to be selected/entered.
 380   By default, there is no required minimum number of values.
 381 - `maximumMultiples($minimum)` and `getMaximumMultiples()` can be used to set the maximum number of values that have to be selected/entered.
 382   By default, there is no maximum number of values.
 383   `IMultipleFormField::NO_MAXIMUM_MULTIPLES` is returned if no maximum number of values has been set and it can also be used to unset a previously set maximum number of values.
 384
 385 `TMultipleFormField` provides a default implementation of these six methods and classes using `TMultipleFormField` register a [custom form field data processor](validation_data.md#customformfielddataprocessor) to add the `HtmlInputProcessor` object with the text into the `$parameters` array directly using `{$objectProperty}_htmlInputProcessor` as the array key.
 386
 387 !!! warning "The implementing class has to validate the values against the minimum and maximum number of values manually."
 388
 389
 390 #### `INullableFormField`
 391
 392 `INullableFormField` has to be implemented by form fields that support `null` as their (empty) value.
 393 The implementing class has to implement the methods `nullable($nullable = true)` and `isNullable()`.
 394 `TNullableFormField` provides a default implementation of these two methods.
 395
 396 `null` should be returned by `IFormField::getSaveValue()` is the field is considered empty and the form field has been set as nullable.
 397
 398
 399 #### `IPackagesFormField`
 400
 401 `IPackagesFormField` has to be implemented by form fields that, in some way, considers packages whose ids may be passed to the field object.
 402 The implementing class has to implement the methods `packageIDs(array $packageIDs)` and `getPackageIDs()`.
 403 `TPackagesFormField` provides a default implementation of these two methods.
 404
 405
 406 #### `IPatternFormField`
 407
 408 !!! info "Only available since version 5.4."
 409
 410 `IPatternFormField` has to be implemented by form fields that support the [`pattern` attribute](https://html.spec.whatwg.org/multipage/input.html#the-pattern-attribute).
 411 The implementing class has to implement the methods `pattern(?string $pattern): self` and `getPattern(): ?string`, which are used to set and get the pattern, respectively.
 412 `TPatternFormField` provides a default implementation of these two methods.
 413
 414
 415 #### `IPlaceholderFormField`
 416
 417 `IPlaceholderFormField` has to be implemented by form fields that support a placeholder value for empty fields.
 418 The implementing class has to implement the methods `placeholder($languageItem = null, array $variables = [])` and `getPlaceholder()`.
 419 `TPlaceholderFormField` provides a default implementation of these two methods.
 420
 421
 422 #### `ISelectionFormField`
 423
 424 `ISelectionFormField` has to be implemented by form fields with a predefined set of possible values.
 425 The implementing class has to implement the getter and setter methods `options($options, $nestedOptions = false, $labelLanguageItems = true)` and `getOptions()` and additionally two methods related to nesting, i.e. whether the selectable options have a hierarchy:
 426 `supportsNestedOptions()` and `getNestedOptions()`.
 427 `TSelectionFormField` provides a default implementation of these four methods.
 428
 429
 430 #### `ISuffixedFormField`
 431
 432 `ISuffixedFormField` has to be implemented by form fields that support supports displaying a suffix behind the actual input field.
 433 The implementing class has to implement the methods `suffix($languageItem = null, array $variables = [])` and `getSuffix()`.
 434 `TSuffixedFormField` provides a default implementation of these two methods.
 435
 436
 437 #### `TDefaultIdFormField`
 438
 439 Form fields that have a default id have to use `TDefaultIdFormField` and have to implement the method `getDefaultId()`.
 440
 441
 442 ## Displaying Forms
 443
 444 The only thing to do in a template to display the **whole** form including all of the necessary JavaScript is to put
 445
 446 ```smarty
 447 {@$form->getHtml()}
 448 ```
 449
 450 into the template file at the relevant position.