docs/php_api_form_builder-form_fields.md

   1 # Form Builder Fields
   2
   3 ## Abstract Form Fields
   4
   5 The following form field classes cannot be instantiated directly because they are abstract, but they can/must be used when creating own form field classes.
   6
   7
   8 ### `AbstractFormField`
   9
  10 `AbstractFormField` is the abstract default implementation of the `IFormField` interface and it is expected that every implementation of `IFormField` implements the interface by extending this class.
  11
  12
  13 ### `AbstractNumericFormField`
  14
  15 `AbstractNumericFormField` is the abstract implementation of a form field handling a single numeric value.
  16 The class implements `IImmutableFormField`, `IMaximumFormField`, `IMinimumFormField`, `INullableFormField`, `IPlaceholderFormField` and `ISuffixedFormField`.
  17 If the property `$integerValues` is `true`, the form field works with integer values, otherwise it works with floating point numbers.
  18 The methods `step($step = null)` and `getStep()` can be used to set and get the step attribute of the `input` element.
  19 The default step for form fields with integer values is `1`.
  20 Otherwise, the default step is `any`.
  21
  22
  23 ## General Form Fields
  24
  25 The following form fields are general reusable fields without any underlying context.
  26
  27
  28 ### `BooleanFormField`
  29
  30 `BooleanFormField` is used for boolean (`0` or `1`, `yes` or `no`) values.
  31 Objects of this class require a label.
  32 The return value of `getSaveValue()` is the integer representation of the boolean value, i.e. `0` or `1`.
  33
  34
  35 ### `ClassNameFormField`
  36
  37 `ClassNameFormField` is a [text form field](#textformfield) that supports additional settings, specific to entering a PHP class name:
  38
  39 - `classExists($classExists = true)` and `getClassExists()` can be used to ensure that the entered class currently exists in the installation.
  40   By default, the existance of the entered class is required.
  41 - `implementedInterface($interface)` and `getImplementedInterface()` can be used to ensure that the entered class implements the specified interface.
  42   By default, no interface is required.
  43 - `parentClass($parentClass)` and `getParentClass()` can be used to ensure that the entered class extends the specified class.
  44   By default, no parent class is required.
  45 - `instantiable($instantiable = true)` and `isInstantiable()` can be used to ensure that the entered class is instantiable.
  46   By default, entered classes have to instantiable.
  47
  48 Additionally, the default id of a `ClassNameFormField` object is `className`, the default label is `wcf.form.field.className`, and if either an interface or a parent class is required, a default description is set if no description has already been set (`wcf.form.field.className.description.interface` and `wcf.form.field.className.description.parentClass`, respectively).
  49
  50
  51 ### `DateFormField`
  52
  53 `DateFormField` is a form field to enter a date (and optionally a time).
  54 The following methods are specific to this form field class:
  55
  56 - `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.
  57   The date passed to the setters must have the same format as set via `saveValueFormat()`.
  58   If a custom format is used, that format has to be set via `saveValueFormat()` before calling any of the setters.
  59 - `saveValueFormat($saveValueFormat)` and `getSaveValueFormat()` can be used to specify the date format of the value returned by `getSaveValue()`.
  60   By default, `U` is used as format.
  61   The [PHP manual](https://secure.php.net/manual/en/function.date.php) provides an overview of supported formats.
  62 - `supportTime($supportsTime = true)` and `supportsTime()` can be used to toggle whether, in addition to a date, a time can also be specified.
  63   By default, specifying a time is disabled.
  64
  65
  66 ### `DescriptionFormField`
  67
  68 `DescriptionFormField` is a [multi-line text form field](#multilinetextformfield) with `description` as the default id and `wcf.global.description` as the default label.
  69
  70
  71 ### `FloatFormField`
  72
  73 `FloatFormField` is an implementation of [AbstractNumericFormField](#abstractnumericformfield) for floating point numbers.
  74
  75
  76 ### `IconFormField`
  77
  78 `IconFormField` is a form field to select a FontAwesome icon.
  79
  80
  81 ### `IntegerFormField`
  82
  83 `IntegerFormField` is an implementation of [AbstractNumericFormField](#abstractnumericformfield) for integers.
  84
  85
  86 ### `IsDisabledFormField`
  87
  88 `IsDisabledFormField` is a [boolean form field](#booleanformfield) with `isDisabled` as the default id.
  89
  90
  91 ### `ItemListFormField`
  92
  93 `ItemListFormField` is a form field in which multiple values can be entered and returned in different formats as save value.
  94 The `saveValueType($saveValueType)` and `getSaveValueType()` methods are specific to this form field class and determine the format of the save value.
  95 The following save value types are supported:
  96
  97 - `ItemListFormField::SAVE_VALUE_TYPE_ARRAY` adds a custom data processor that writes the form field data directly in the parameters array and not in the data sub-array of the parameters array.
  98 - `ItemListFormField::SAVE_VALUE_TYPE_CSV` lets the value be returned as a string in which the values are concatenated by commas.
  99 - `ItemListFormField::SAVE_VALUE_TYPE_NSV` lets the value be returned as a string in which the values are concatenated by `\n`.
 100 - `ItemListFormField::SAVE_VALUE_TYPE_SSV` lets the value be returned as a string in which the values are concatenated by spaces.
 101
 102 By default, `ItemListFormField::SAVE_VALUE_TYPE_CSV` is used.
 103
 104 If `ItemListFormField::SAVE_VALUE_TYPE_ARRAY` is used as save value type, `ItemListFormField` objects register a [custom form field data processor](php_api_form_builder-validation_data.md#customformfielddataprocessor) to add the relevant array into the `$parameters` array directly using the object property as the array key.
 105
 106
 107 ### `MultilineTextFormField`
 108
 109 `MultilineTextFormField` is a [text form field](#textformfield) that supports multiple rows of text.
 110 The methods `rows($rows)` and `getRows()` can be used to set and get the number of rows of the `textarea` elements.
 111 The default number of rows is `10`.
 112 These methods do **not**, however, restrict the number of text rows that canbe entered.
 113
 114
 115 ### `MultipleSelectionFormField`
 116
 117 `MultipleSelectionFormField` is a form fields that allows the selection of multiple options out of a predefined list of available options.
 118 The class implements `IFilterableSelectionFormField`, `IImmutableFormField`, and `INullableFormField`.
 119 If the field is nullable and no option is selected, `null` is returned as the save value.
 120
 121
 122 ### `RadioButtonFormField`
 123
 124 `RadioButtonFormField` is a form fields that allows the selection of a single option out of a predefined list of available options using radiobuttons.
 125 The class implements `IImmutableFormField` and `ISelectionFormField`.
 126
 127
 128 ### `RatingFormField`
 129
 130 `RatingFormField` is a form field to set a rating for an object.
 131 The class implements `IImmutableFormField`, `IMaximumFormField`, `IMinimumFormField`, and `INullableFormField`.
 132 Form fields of this class have `rating` as their default id, `wcf.form.field.rating` as their default label, `1` as their default minimum, and `5` as their default maximum.
 133 For this field, the minimum and maximum refer to the minimum and maximum rating an object can get.
 134 When the field is shown, there will be `maximum() - minimum() + 1` icons be shown with additional CSS classes that can be set and gotten via `defaultCssClasses(array $cssClasses)` and `getDefaultCssClasses()`.
 135 If a rating values is set, the first `getValue()` icons will instead use the classes that can be set and gotten via `activeCssClasses(array $cssClasses)` and `getActiveCssClasses()`.
 136 By default, the only default class is `fa-star-o` and the active classes are `fa-star` and `orange`.
 137
 138
 139 ### `ShowOrderFormField`
 140
 141 `ShowOrderFormField` is a [single selection form field](#singleselectionformfield) for which the selected value determines the position at which an object is shown.
 142 The show order field provides a list of all siblings and the object will be positioned **after** the selected sibling.
 143 To insert objects at the very beginning, the `options()` automatically method prepends an additional option for that case so that only the existing siblings need to be passed.
 144 The default id of instances of this class is `showOrder` and their default label is `wcf.form.field.showOrder`.
 145
 146 !!! info "It is important that the relevant object property is always kept updated. Whenever a new object is added or an existing object is edited or delete, the values of the other objects have to be adjusted to ensure consecutive numbering."
 147
 148
 149 ### `SingleSelectionFormField`
 150
 151 `SingleSelectionFormField` is a form fields that allows the selection of a single option out of a predefined list of available options.
 152 The class implements `IFilterableSelectionFormField`, `IImmutableFormField`, and `INullableFormField`.
 153 If the field is nullable and the current form field value is considered `empty` by PHP, `null` is returned as the save value.
 154
 155
 156 ### `SortOrderFormField`
 157
 158 `SingleSelectionFormField` is a [single selection form field](#singleselectionformfield) with default id `sortOrder`, default label `wcf.global.showOrder` and default options `ASC: wcf.global.sortOrder.ascending` and `DESC: wcf.global.sortOrder.descending`.
 159
 160
 161 ### `TextFormField`
 162
 163 `TextFormField` is a form field that allows entering a single line of text.
 164 The class implements `IImmutableFormField`, `II18nFormField`, `IMaximumLengthFormField`, `IMinimumLengthFormField`, and `IPlaceholderFormField`.
 165
 166
 167 ### `TitleFormField`
 168
 169 `TitleFormField` is a [text form field](#textformfield) with `title` as the default id and `wcf.global.title` as the default label.
 170
 171
 172 ### `UrlFormField`
 173
 174 `UrlFormField` is a [text form field](#textformfield) whose values are checked via `Url::is()`.
 175
 176
 177
 178 ## Specific Fields
 179
 180 The following form fields are reusable fields that generally are bound to a certain API or `DatabaseObject` implementation.
 181
 182
 183 ### `AclFormField`
 184
 185 `AclFormField` is used for setting up acl values for specific objects.
 186 The class implements `IObjectTypeFormField` and requires an object type of the object type definition `com.woltlab.wcf.acl`.
 187 Additionally, the class provides the methods `categoryName($categoryName)` and `getCategoryName()` that allow setting a specific name or filter for the acl option categories whose acl options are shown.
 188 A category name of `null` signals that no category filter is used.
 189
 190 `AclFormField` objects register a [custom form field data processor](php_api_form_builder-validation_data.md#customformfielddataprocessor) to add the relevant ACL object type id into the `$parameters` array directly using `{$objectProperty}_aclObjectTypeID` as the array key.
 191 The relevant database object action method is expected, based on the given ACL object type id, to save the ACL option values appropriately.
 192
 193
 194 ### `CaptchaFormField`
 195
 196 `CaptchaFormField` is used to add captcha protection to the form.
 197
 198 You must specify a captcha object type (`com.woltlab.wcf.captcha`) using the `objectType()` method.
 199
 200
 201 ### `ContentLanguageFormField`
 202
 203 `ContentLanguageFormField` is used to select the content language of an object.
 204 Fields of this class are only available if multilingualism is enabled and if there are content languages.
 205 The class implements `IImmutableFormField`.
 206
 207
 208 ### `LabelFormField`
 209
 210 `LabelFormField` is used to select a label from a specific label group.
 211 The class implements `IObjectTypeFormNode`.
 212
 213 The `labelGroup(ViewableLabelGroup $labelGroup)` and `getLabelGroup()` methods are specific to this form field class and can be used to set and get the label group whose labels can be selected.
 214 Additionally, there is the static method `createFields($objectType, array $labelGroups, $objectProperty = 'labelIDs)` that can be used to create all relevant label form fields for a given list of label groups.
 215 In most cases, `LabelFormField::createFields()` should be used.
 216
 217
 218 ### `OptionFormField`
 219
 220 `OptionFormField` is an [item list form field](#itemlistformfield) to set a list of options.
 221 The class implements `IPackagesFormField` and only options of the set packages are considered available.
 222 The default label of instances of this class is `wcf.form.field.option` and their default id is `options`.
 223
 224
 225 ### `SimpleAclFormField`
 226
 227 `SimpleAclFormField` is used for setting up simple acl values (one `yes`/`no` option per user and user group) for specific objects.
 228
 229 `SimpleAclFormField` objects register a [custom form field data processor](php_api_form_builder-validation_data.md#customformfielddataprocessor) to add the relevant simple ACL data array into the `$parameters` array directly using the object property as the array key.
 230
 231
 232 ### `SingleMediaSelectionFormField`
 233
 234 `SingleMediaSelectionFormField` is used to select a specific media file.
 235 The class implements `IImmutableFormField`.
 236
 237 The following methods are specific to this form field class:
 238
 239 - `imageOnly($imageOnly = true)` and `isImageOnly()` can be used to set and check if only images may be selected.
 240 - `getMedia()` returns the media file based on the current field value if a field is set.
 241
 242
 243 ### `TagFormField`
 244
 245 `TagFormField` is a form field to enter tags.
 246 Arrays passed to `TagFormField::values()` can contain tag names as strings and `Tag` objects.
 247 The default label of instances of this class is `wcf.tagging.tags` and their default description is `wcf.tagging.tags.description`.
 248
 249 `TagFormField` objects register a [custom form field data processor](php_api_form_builder-validation_data.md#customformfielddataprocessor) to add the array with entered tag names into the `$parameters` array directly using the object property as the array key.
 250
 251
 252 ### `UploadFormField`
 253
 254 `UploadFormField` is a form field that allows uploading files by the user.
 255
 256 `UploadFormField` objects register a [custom form field data processor](php_api_form_builder-validation_data.md#customformfielddataprocessor) to add the array of `wcf\system\file\upload\UploadFile\UploadFile` into the `$parameters` array directly using the object property as the array key. Also it registers the removed files as an array of `wcf\system\file\upload\UploadFile\UploadFile` into the `$parameters` array directly using the object property with the suffix `_removedFiles` as the array key.
 257
 258 The field supports additional settings:
 259 - `imageOnly($imageOnly = true)` and `isImageOnly()` can be used to ensure that the uploaded files are only images.
 260 - `allowSvgImage($allowSvgImages = true)` and `svgImageAllowed()` can be used to allow SVG images, if the image only mode is enabled (otherwise, the method will throw an exception). By default, SVG images are not allowed.
 261
 262 #### Provide value from database object
 263
 264 To provide values from a database object, you should implement the method `get{$objectProperty}UploadFileLocations()` to your database object class. This method must return an array of strings with the locations of the files.
 265
 266 #### Process files
 267
 268 To process files in the database object action class, you must [`rename`](https://secure.php.net/manual/en/function.rename.php) the file to the final destination. You get the temporary location, by calling the method `getLocation()` on the given `UploadFile` objects. After that, you call `setProcessed($location)` with `$location` contains the new file location. This method sets the `isProcessed` flag to true and saves the new location. For updating files, it is relevant, whether a given file is already processed or not. For this case, the `UploadFile` object has an method `isProcessed()` which indicates, whether a file is already processed or new uploaded.
 269
 270
 271 ### `UserFormField`
 272
 273 `UserFormField` is a form field to enter existing users.
 274 The class implements `IAutoFocusFormField`, `IImmutableFormField`, `IMultipleFormField`, and `INullableFormField`.
 275 While the user is presented the names of the specified users in the user interface, the field returns the ids of the users as data.
 276 The relevant `UserProfile` objects can be accessed via the `getUsers()` method.
 277
 278
 279 ### `UserGroupOptionFormField`
 280
 281 `UserGroupOptionFormField` is an [item list form field](#itemlistformfield) to set a list of user group options/permissions.
 282 The class implements `IPackagesFormField` and only user group options of the set packages are considered available.
 283 The default label of instances of this class is `wcf.form.field.userGroupOption` and their default id is `permissions`.
 284
 285
 286 ### `UsernameFormField`
 287
 288 `UsernameFormField` is used for entering one non-existing username.
 289 The class implements `IImmutableFormField`, `IMaximumLengthFormField`, `IMinimumLengthFormField`, `INullableFormField`, and `IPlaceholderFormField`.
 290 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.
 291
 292
 293
 294 ## Wysiwyg form container
 295
 296 To integrate a wysiwyg editor into a form, you have to create a `WysiwygFormContainer` object.
 297 This container takes care of creating all necessary form nodes listed below for a wysiwyg editor.
 298
 299 !!! warning "When creating the container object, its id has to be the id of the form field that will manage the actual text."
 300
 301 The following methods are specific to this form container class:
 302
 303 - `addSettingsNode(IFormChildNode $settingsNode)` and `addSettingsNodes(array $settingsNodes)` can be used to add nodes to the settings tab container.
 304 - `attachmentData($objectType, $parentObjectID)` can be used to set the data relevant for attachment support.
 305   By default, not attachment data is set, thus attachments are not supported.
 306 - `getAttachmentField()`, `getPollContainer()`, `getSettingsContainer()`, `getSmiliesContainer()`, and `getWysiwygField()` can be used to get the different components of the wysiwyg form container once the form has been built.
 307 - `enablePreviewButton($enablePreviewButton)` can be used to set whether the preview button for the message is shown or not.
 308   By default, the preview button is shown.
 309   This method is only relevant before the form is built.
 310   Afterwards, the preview button availability can not be changed.
 311   Only available since WoltLab Suite Core 5.3.
 312 - `getObjectId()` returns the id of the edited object or `0` if no object is edited.
 313 - `getPreselect()`, `preselect($preselect)` can be used to set the value of the wysiwyg tab menu's `data-preselect` attribute used to determine which tab is preselected.
 314   By default, the preselect is `'true'` which is used to pre-select the first tab.
 315 - `messageObjectType($messageObjectType)` can be used to set the message object type.
 316 - `pollObjectType($pollObjectType)` can be used to set the poll object type.
 317   By default, no poll object type is set, thus the poll form field container is not available.
 318 - `supportMentions($supportMentions)` can be used to set if mentions are supported.
 319   By default, mentions are not supported.
 320   This method is only relevant before the form is built.
 321   Afterwards, mention support can only be changed via the wysiwyg form field.
 322 - `supportSmilies($supportSmilies)` can be used to set if smilies are supported.
 323   By default, smilies are supported.
 324   This method is only relevant before the form is built.
 325   Afterwards, smiley availability can only be changed via changing the availability of the smilies form container.
 326
 327 ### `WysiwygAttachmentFormField`
 328
 329 `WysiwygAttachmentFormField` provides attachment support for a wysiwyg editor via a tab in the menu below the editor.
 330 This class should not be used directly but only via `WysiwygFormContainer`.
 331 The methods `attachmentHandler(AttachmentHandler $attachmentHandler)` and `getAttachmentHandler()` can be used to set and get the `AttachmentHandler` object that is used for uploaded attachments.
 332
 333 ### `WysiwygPollFormContainer`
 334
 335 `WysiwygPollFormContainer` provides poll support for a wysiwyg editor via a tab in the menu below the editor.
 336 This class should not be used directly but only via `WysiwygFormContainer`.
 337 `WysiwygPollFormContainer` contains all form fields that are required to create polls and requires edited objects to implement `IPollContainer`.
 338
 339 The following methods are specific to this form container class:
 340
 341 - `getEndTimeField()` returns the form field to set the end time of the poll once the form has been built.
 342 - `getIsChangeableField()` returns the form field to set if poll votes can be changed once the form has been built.
 343 - `getIsPublicField()` returns the form field to set if poll results are public once the form has been built.
 344 - `getMaxVotesField()` returns the form field to set the maximum number of votes once the form has been built.
 345 - `getOptionsField()` returns the form field to set the poll options once the form has been built.
 346 - `getQuestionField()` returns the form field to set the poll question once the form has been built.
 347 - `getResultsRequireVoteField()` returns the form field to set if viewing the poll results requires voting once the form has been built.
 348 - `getSortByVotesField()` returns the form field to set if the results are sorted by votes once the form has been built.
 349
 350 ### `WysiwygSmileyFormContainer`
 351
 352 `WysiwygSmileyFormContainer` provides smiley support for a wysiwyg editor via a tab in the menu below the editor.
 353 This class should not be used directly but only via `WysiwygFormContainer`.
 354 `WysiwygSmileyFormContainer` creates a sub-tab for each smiley category.
 355
 356 #### `WysiwygSmileyFormNode`
 357
 358 `WysiwygSmileyFormNode` is contains the smilies of a specific category.
 359 This class should not be used directly but only via `WysiwygSmileyFormContainer`.
 360
 361 ### Example
 362
 363 The following code creates a WYSIWYG editor component for a `message` object property.
 364 As smilies are supported by default and an attachment object type is given, the tab menu below the editor has two tabs: “Smilies” and “Attachments”.
 365 Additionally, mentions and quotes are supported.
 366
 367 ```php
 368 WysiwygFormContainer::create('message')
 369         ->label('foo.bar.message')
 370         ->messageObjectType('com.example.foo.bar')
 371         ->attachmentData('com.example.foo.bar')
 372         ->supportMentions()
 373         ->supportQuotes()
 374 ```
 375
 376
 377 ### `WysiwygFormField`
 378
 379 `WysiwygFormField` is used for wysiwyg editor form fields.
 380 This class should, in general, not be used directly but only via `WysiwygFormContainer`.
 381 The class implements `IMaximumLengthFormField`, `IMinimumLengthFormField`, and `IObjectTypeFormNode` and requires an object type of the object type definition `com.woltlab.wcf.message`.
 382 The following methods are specific to this form field class:
 383
 384 - `autosaveId($autosaveId)` and `getAutosaveId()` can be used enable automatically saving the current editor contents in the browser using the given id.
 385   An empty string signals that autosaving is disabled.
 386 - `lastEditTime($lastEditTime)` and `getLastEditTime()` can be used to set the last time the contents have been edited and saved so that the JavaScript can determine if the contents stored in the browser are older or newer.
 387   `0` signals that no last edit time has been set.
 388 - `supportAttachments($supportAttachments)` and `supportsAttachments()` can be used to set and check if the form field supports attachments.
 389
 390   !!! warning "It is not sufficient to simply signal attachment support via these methods for attachments to work. These methods are relevant internally to signal the Javascript code that the editor supports attachments. Actual attachment support is provided by `WysiwygAttachmentFormField`."
 391 - `supportMentions($supportMentions)` and `supportsMentions()` can be used to set and check if the form field supports mentions of other users.
 392
 393 `WysiwygFormField` objects register a [custom form field data processor](php_api_form_builder-validation_data.md#customformfielddataprocessor) to add the relevant simple ACL data array into the `$parameters` array directly using the object property as the array key.
 394
 395
 396 ### `TWysiwygFormNode`
 397
 398 All form nodes that need to know the id of the `WysiwygFormField` field should use `TWysiwygFormNode`.
 399 This trait provides `getWysiwygId()` and `wysiwygId($wysiwygId)` to get and set the relevant wysiwyg editor id.
 400
 401
 402
 403 ## Single-Use Form Fields
 404
 405 The following form fields are specific for certain forms and hardly reusable in other contexts.
 406
 407
 408 ### `BBCodeAttributesFormField`
 409
 410 `DevtoolsProjectExcludedPackagesFormField` is a form field for setting the attributes of a BBCode.
 411
 412
 413 ### `DevtoolsProjectExcludedPackagesFormField`
 414
 415 `DevtoolsProjectExcludedPackagesFormField` is a form field for setting the excluded packages of a devtools project.
 416
 417
 418 ### `DevtoolsProjectInstructionsFormField`
 419
 420 `DevtoolsProjectExcludedPackagesFormField` is a form field for setting the installation and update instructions of a devtools project.
 421
 422
 423 ### `DevtoolsProjectOptionalPackagesFormField`
 424
 425 `DevtoolsProjectExcludedPackagesFormField` is a form field for setting the optional packages of a devtools project.
 426
 427
 428 ### `DevtoolsProjectRequiredPackagesFormField`
 429
 430 `DevtoolsProjectExcludedPackagesFormField` is a form field for setting the required packages of a devtools project.