WoltLab Suite 6.2 Handbuch
Deutsch/PHP-Version: Die Website-Struktur, Navigation und Überschriften sind auf Deutsch vorbereitet. Code-Beispiele und technische Namen bleiben unverändert.

Form Builder Fields

Abstract Form Fields

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.

AbstractFormField

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.

AbstractNumericFormField

AbstractNumericFormField is the abstract implementation of a form field handling a single numeric value.

The class implements IAttributeFormField, IAutoCompleteFormField, ICssClassFormField, 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.

Otherwise, the default step is any.

AbstractFormFieldDecorator

AbstractFormFieldDecorator is a default implementation of a decorator for form fields that forwards calls to all methods defined in IFormField to the respective method of the decorated object.

The class implements IFormfield.

If the implementation of a more specific interface is required then the remaining methods must be implemented in the concrete decorator derived from AbstractFormFieldDecorator and the type of the $field property must be narrowed appropriately.

General Form Fields

The following form fields are general reusable fields without any underlying context.

BooleanFormField

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, ICssClassFormField, and IImmutableFormField.

Example:

BooleanFormField::create('example')
  ->label('foo.bar.example')
  ->value(true)

CheckboxFormField

CheckboxFormField extends BooleanFormField and offers a simple HTML checkbox.

Example:

CheckboxFormField::create('example')
  ->label('foo.bar.example')

ClassNameFormField

ClassNameFormField is a text form field that supports additional settings, specific to entering a PHP class name:

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).

Example:

ClassNameFormField::create('example')
  ->label('foo.bar.example')
  ->classExists()
  ->implementedInterface(ExampleInterface::class)

CurrencyFormField

CurrencyFormField is an implementation designed for two-decimal currencies like EUR or USD. The API expect amounts to be provided in the smallest unit. For example, to set a value to 10 USD, provide an amount value of 1000 (i.e., 1000 cents).

Example:

CurrencyFormField::create('name')
  ->currency('USD')
  ->value(1000); // = USD 10

DateFormField

DateFormField is a form field to enter a date (and optionally a time).

The class implements IAttributeFormField, IAutoFocusFormField, ICssClassFormField, IImmutableFormField, and INullableFormField.

The following methods are specific to this form field class:

Example:

DateFormField::create('example')
  ->label('foo.bar.example')
  ->saveValueFormat('Y-m-d')
  ->value(DateUtil::format(DateUtil::getDateTimeByTimestamp(TIME_NOW), 'Y-m-d'))

DateRangeFormField

DateRangeFormField is a form field to enter a date range, consisting of a start and an end date.

The two values are separated by a semicolon in the value.

The class implements IAttributeFormField, IAutoFocusFormField, ICssClassFormField, IImmutableFormField, and INullableFormField.

The following methods are specific to this form field class:

Example:

DateRangeFormField::create('example')
  ->label('foo.bar.example')
  ->saveValueFormat('Y-m-d')
  ->value(DateUtil::format(DateUtil::getDateTimeByTimestamp(TIME_NOW - 86_400), 'Y-m-d') . ';' . DateUtil::format(DateUtil::getDateTimeByTimestamp(TIME_NOW), 'Y-m-d'))

DescriptionFormField

DescriptionFormField is a multi-line text form field with description as the default id and wcf.global.description as the default label.

Example:

DescriptionFormField::create('example')

EmailFormField

EmailFormField is a form field to enter an email address which is internally validated using UserUtil::isValidEmail().

The class implements IAttributeFormField, IAutoCompleteFormField, IAutoFocusFormField, ICssClassFormField, II18nFormField, IImmutableFormField, IInputModeFormField, IPatternFormField, and IPlaceholderFormField.

Example:

EmailFormField::create('example')
  ->label('foo.bar.example')

FloatFormField

FloatFormField is an implementation of AbstractNumericFormField for floating point numbers.

Example:

FloatFormField::create('example')
  ->label('foo.bar.example')
  ->value(0.5)

GoogleMapsFormField

GoogleMapsFormField is a form field that allows to specify coordinates using a Google Maps instance.

Example:

GoogleMapsFormField::create('location')
  ->label('foo.bar.example')

On submit the form field will populate 3 values to the data array:

1. Human-readable address or place name (location in the example above).

2. The latitude prefixed with the given ID (location_latitude).

3. The longitude prefixed with the given ID (location_longitude).

HiddenFormField

HiddenFormField is a form field without any user-visible UI.

Even though the form field is invisible to the user, the value can still be modified by the user, e.g. by leveraging the web browsers developer tools.

The HiddenFormField *must not* be used to transfer sensitive information or information that the user should not be able to modify.

Example:

HiddenFormField::create('example')
  ->value('hidden value')

IconFormField

IconFormField is a form field to select a FontAwesome icon.

Example:

IconFormField::create('example')
  ->label('foo.bar.example')

IntegerFormField

IntegerFormField is an implementation of AbstractNumericFormField for integers.

Example:

IntegerFormField::create('example')
  ->label('foo.bar.example')
  ->value(10)

IsDisabledFormField

IsDisabledFormField is a boolean form field with isDisabled as the default id.

Example:

IsDisabledFormField::create()
  ->label('foo.bar.example')

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, ICssClassFormField, 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:

By default, ItemListFormField::SAVE_VALUE_TYPE_CSV is used.

If ItemListFormField::SAVE_VALUE_TYPE_ARRAY is used as save value type, ItemListFormField objects register a custom form field data processor to add the relevant array into the $parameters array directly using the object property as the array key.

Example:

ItemListFormField::create('example')
  ->label('foo.bar.example')
  ->saveValueType(ItemListFormField::SAVE_VALUE_TYPE_CSV)

SpracheItemFormNode

LanguageItemFormNode is a form node that shows a language item without any surrounding HTML code.

Example:

LanguageItemFormNode::create('name')
  ->languageItem('name_of_language_item');

MultilineTextFormField

MultilineTextFormField is a text form field that supports multiple rows of text.

The methods rows($rows) and getRows() can be used to set and get the number of rows of the textarea elements.

The default number of rows is 10.

These methods do not, however, restrict the number of text rows that can be entered.

Example:

MultilineTextFormField::create('example')
  ->label('foo.bar.example')
  ->maximumLength(5000)
  ->rows(5)

MultipleSelectionFormField

MultipleSelectionFormField is a form fields that allows the selection of multiple options out of a predefined list of available options.

The class implements IAttributeFormField, ICssClassFormField, IFilterableSelectionFormField, and IImmutableFormField.

Example:

MultipleSelectionFormField::create('example')
  ->label('foo.bar.example')
  ->options([
    1 => 'one',
    2 => 'two',
  ])

HinweisFormNode

NoticeFormNode is a form node that shows a notice without any surrounding HTML code.

Example:

NoticeFormNode::create('name')
  ->type(NoticeFormNodeType::Success)
  ->languageItem('name_of_language_item');

NumericRangeFormField

NumericRangeFormField is a form field to enter a numeric range, consisting of a minimum and a maximum value.

The two values are separated by a semicolon in the value.

The class implements IAttributeFormField, IAutoFocusFormField, ICssClassFormField, IImmutableFormField, and INullableFormField.

The following methods are specific to this form field class:

Example:

NumericRangeFormField::create('example')
  ->label('foo.bar.example')
  ->integerValues()
  ->value('1;10')

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 IAttributeFormField, ICssClassFormField, IImmutableFormField, and ISelectionFormField.

Example:

RadioButtonFormField::create('example')
  ->label('foo.bar.example')
  ->options([
    1 => 'one',
    2 => 'two',
  ])

RatingFormField

RatingFormField is a form field to set a rating for an object.

The class implements IImmutableFormField, IMaximumFormField, IMinimumFormField, and INullableFormField.

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.

For this field, the minimum and maximum refer to the minimum and maximum rating an object can get.

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().

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().

By default, the only default class is star-o and the active classes are star and orange.

Example:

RatingFormField::create('example')
  ->label('foo.bar.example')
  ->minimum(1)
  ->maximum(5)

SelectFormField

SelectFormField is a form fields that allows the selection of a single option out of a predefined list of available options.

The class implements ICssClassFormField and IImmutableFormField.

Example:

SelectFormField::create('select')
  ->options(['option1', 'option2', 'option3']);

ShowOrderFormField

ShowOrderFormField is a single selection form field for which the selected value determines the position at which an object is shown.

The show order field provides a list of all siblings and the object will be positioned after the selected sibling.

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.

The default id of instances of this class is showOrder and their default label is wcf.form.field.showOrder.

!!! 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."

Example:

ShowOrderFormField::create('example')
  ->options(new FooList())

SingleSelectionFormField

SingleSelectionFormField is a form fields that allows the selection of a single option out of a predefined list of available options.

The class implements ICssClassFormField, IFilterableSelectionFormField, IImmutableFormField, and INullableFormField.

If the field is nullable and the current form field value is considered empty by PHP, null is returned as the save value.

Example:

SingleSelectionFormField::create('example')
  ->options(['option1', 'option2', 'option3'])

SortOrderFormField

SingleSelectionFormField is a single selection form field with default id sortOrder, default label wcf.global.showOrder and default options ASC: wcf.global.sortOrder.ascending and DESC: wcf.global.sortOrder.descending.

Example:

SingleSelectionFormField::create('example')

TextFormField

TextFormField is a form field that allows entering a single line of text.

The class implements IAttributeFormField, IAutoCompleteFormField, ICensorshipFormField, ICssClassFormField, IImmutableFormField, II18nFormField, IInputModeFormField, IMaximumLengthFormField, IMinimumLengthFormField, IPatternFormField, and IPlaceholderFormField.

Example:

TextFormField::create('example')
  ->label('foo.bar.example')

TitleFormField

TitleFormField is a text form field with title as the default id and wcf.global.title as the default label.

Example:

TitleFormField::create()

UrlFormField

UrlFormField is a text form field whose values are checked via Url::is().

Example:

UrlFormField::create('example')
  ->label('foo.bar.example')

Specific Fields

The following form fields are reusable fields that generally are bound to a certain API or DatabaseObject implementation.

AclFormField

AclFormField is used for setting up acl values for specific objects.

The class implements IObjectTypeFormField and requires an object type of the object type definition com.woltlab.wcf.acl.

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.

A category name of null signals that no category filter is used.

!!! info "Since version 5.5, the category name also supports filtering using a wildcard like user.*, see WoltLab/WCF#4355."

AclFormField objects register a custom form field data processor to add the relevant ACL object type id into the $parameters array directly using {$objectProperty}_aclObjectTypeID as the array key.

The relevant database object action method is expected, based on the given ACL object type id, to save the ACL option values appropriately.

Example

The following source code creates an AclFormField with the object type foo.bar.acl:

FormContainer::create('aclContainer')
  ->label('foo.bar.acl')
  ->appendChildren([
      AclFormField::create('acl')
          ->objectType('foo.bar.acl')
  ])

After submitting the form, the id of the object type is passed to the DatabaseObjectAction and can be used there to process the data with the help of the ACLHandler.

use wcf\data\AbstractDatabaseObjectAction;
use wcf\system\acl\ACLHandler;

class FooAction extends AbstractDatabaseObjectAction {
  public function create() {
    $object = parent::create();

    if (!empty($this->parameters['acl_aclObjectTypeID'])) {
      ACLHandler::getInstance()->save($object->getObjectID(), $this->parameters['acl_aclObjectTypeID']);
    }
  }
}

ButtonFormField

ButtonFormField shows a submit button as part of the form.

The class implements IAttributeFormField and ICssClassFormField.

Specifically for this form field, there is the IsNotClickedFormFieldDependency dependency with which certain parts of the form will only be processed if the relevent button has not clicked.

Example:

ButtonFormField::create('example')
  ->buttonLabel('foo.bar.example')

CaptchaFormField

CaptchaFormField is used to add captcha protection to the form.

You must specify a captcha object type (com.woltlab.wcf.captcha) using the objectType() method.

Example:

CaptchaFormField::create('captcha')
  ->objectType(CAPTCHA_TYPE)

ColorFormField

ColorFormField is used to specify RGBA colors using the rgba(r, g, b, a) format.

The class implements IImmutableFormField.

Example:

ColorFormField::create('example')
  ->label('foo.bar.example')
  ->value('rgba(1,1,1,1)')

ContentSpracheFormField

ContentLanguageFormField is used to select the content language of an object.

Fields of this class are only available if multilingualism is enabled and if there are content languages.

The class implements IImmutableFormField.

Example:

ContentLanguageFormField::create()

FileProcessorFormField

The FileProcessorFormField is used to upload files to the server via the file processor.

By default, FileProcessorFormField objects register a custom form field data processor to add the appropriate array of fileIDs to the $parameters array directly, using the object property as the array key.

If isSingleFileUpload() is enabled, the value will be added to the data sub-array of the parameters array and the value can be null.

The checks for the correct file size or extension don't take place in the FormField, this must be defined in the IFileProcessor.

__The field supports other settings:__

Example:

FileProcessorFormField::create('exampleFileID')
  ->objectType('foo.bar.example')
  ->label('foo.bar.example.title')
  ->singleFileUpload()
  ->bigPreview()

Additional Buttons

Additional buttons can be added with addActionButton(string $actionName, string $title, string $template, string $application = 'wcf', ?IFontAwesomeIcon $icon = null).

When this button is pressed, the fileProcessorCustomAction event is fired, which can be used via JavaScript to perform additional actions.

Example:

document.getElementById('exampleFileIDContainer').addEventListener('fileProcessorCustomAction', (event: CustomEvent<string>) => {
  const actionName = event.detail;
  // Perform your action
});

LabelFormField

LabelFormField is used to select a label from a specific label group.

The class implements IObjectTypeFormNode.

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.

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.

In most cases, LabelFormField::createFields() should be used.

Example:

LabelFormField::create('example')
  ->objectType('foo.bar.example.object.type')
  ->labelGroup(LabelHandler::getInstance()->getLabelGroup($groupID))

OptionFormField

OptionFormField is an item list form field to set a list of options.

The class implements IPackagesFormField and only options of the set packages are considered available.

The default label of instances of this class is wcf.form.field.option and their default id is options.

Example:

OptionFormField::create()
  ->description('foo.bar.example')
  ->packageIDs([1, 2])

SimpleAclFormField

SimpleAclFormField is used for setting up simple acl values (one yes/no option per user and user group) for specific objects.

SimpleAclFormField objects register a custom form field data processor to add the relevant simple ACL data array into the $parameters array directly using the object property as the array key.

!!! info "Since version 5.5, the field also supports inverted permissions, see WoltLab/WCF#4570."

The SimpleAclFormField supports inverted permissions, allowing the administrator to grant access to all non-selected users and groups. If this behavior is desired, it needs to be enabled by calling supportInvertedPermissions. An invertPermissions key containing a boolean value with the users selection will be provided together with the ACL values when saving the field.

Example:

SimpleAclFormField::create('example')
  ->label('foo.bar.example')
  ->supportInvertedPermissions(true)
  ->value([
      'allowAll' => false,
      'user' => [1, 2],
  ])

SingleMediaSelectionFormField

SingleMediaSelectionFormField is used to select a specific media file.

The class implements IImmutableFormField.

The following methods are specific to this form field class:

Example:

SingleMediaSelectionFormField::create('example')
  ->label('foo.bar.example')

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.

TagFormField objects register a custom form field data processor to add the array with entered tag names into the $parameters array directly using the object property as the array key.

Example:

TagFormField::create()
  ->objectType('foo.bar.example.object.type')

UploadFormField

UploadFormField is a form field that allows uploading files by the user.

UploadFormField objects register a custom form field data processor 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.

The field supports additional settings:

Example:

UploadFormField::create('example')
	->label('foo.bar.example')
	->maximum(1)
	->imageOnly(true)

Provide value from database object

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.

Process files

To process files in the database object action class, you must rename 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.

UserFormField

UserFormField is a form field to enter existing users.

The class implements IAutoCompleteFormField, IAutoFocusFormField, IImmutableFormField, IMultipleFormField, and INullableFormField.

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.

The relevant UserProfile objects can be accessed via the getUsers() method.

Example:

UserFormField::create('example')
	->label('foo.bar.example')

UserPasswordField

UserPasswordField is a form field for users' to enter their current password.

The class implements IAttributeFormField, IAttributeFormField, IAutoCompleteFormField, IAutoFocusFormField, and IPlaceholderFormField

Example:

UserPasswordField::create()
	->autocomplete('current-password')

UserGroupOptionFormField

UserGroupOptionFormField is an item list form field to set a list of user group options/permissions.

The class implements IPackagesFormField and only user group options of the set packages are considered available.

The default label of instances of this class is wcf.form.field.userGroupOption and their default id is permissions.

Example:

UserGroupOptionFormField::create()
  ->packageIDs([1, 2])

UsernameFormField

UsernameFormField is used for entering one non-existing username.

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.

Example:

UsernameFormField::create('example')
  ->label('foo.bar.example')

Wysiwyg form container

To integrate a wysiwyg editor into a form, you have to create a WysiwygFormContainer object.

This container takes care of creating all necessary form nodes listed below for a wysiwyg editor.

!!! warning "When creating the container object, its id has to be the id of the form field that will manage the actual text."

The following methods are specific to this form container class:

WysiwygAttachmentFormField

WysiwygAttachmentFormField provides attachment support for a wysiwyg editor via a tab in the menu below the editor.

This class should not be used directly but only via WysiwygFormContainer.

The methods attachmentHandler(AttachmentHandler $attachmentHandler) and getAttachmentHandler() can be used to set and get the AttachmentHandler object that is used for uploaded attachments.

WysiwygPollFormContainer

WysiwygPollFormContainer provides poll support for a wysiwyg editor via a tab in the menu below the editor.

This class should not be used directly but only via WysiwygFormContainer.

WysiwygPollFormContainer contains all form fields that are required to create polls and requires edited objects to implement IPollContainer.

The following methods are specific to this form container class:

WysiwygSmileyFormContainer

WysiwygSmileyFormContainer provides smiley support for a wysiwyg editor via a tab in the menu below the editor.

This class should not be used directly but only via WysiwygFormContainer.

WysiwygSmileyFormContainer creates a sub-tab for each smiley category.

WysiwygSmileyFormNode

WysiwygSmileyFormNode is contains the smilies of a specific category.

This class should not be used directly but only via WysiwygSmileyFormContainer.

Example

The following code creates a WYSIWYG editor component for a message object property.

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”.

Additionally, mentions and quotes are supported.

WysiwygFormContainer::create('message')
	->label('foo.bar.message')
	->messageObjectType('com.example.foo.bar')
	->attachmentData('com.example.foo.bar')
	->supportMentions()
	->supportQuotes()

WysiwygFormField

WysiwygFormField is used for wysiwyg editor form fields.

This class should, in general, not be used directly but only via WysiwygFormContainer.

The class implements IAttributeFormField, ICensorshipFormField, 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:

!!! 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."

WysiwygFormField objects register a custom form field data processor to add the relevant simple ACL data array into the $parameters array directly using the object property as the array key.

TWysiwygFormNode

All form nodes that need to know the id of the WysiwygFormField field should use TWysiwygFormNode.

This trait provides getWysiwygId() and wysiwygId($wysiwygId) to get and set the relevant wysiwyg editor id.

Application-Specific Form Fields

WoltLab Suite Forum

MultipleBoardSelectionFormField

MultipleBoardSelectionFormField is used to select multiple forums.

The class implements IAttributeFormField, ICssClassFormField, and IImmutableFormField.

The field supports additional settings:

Single-Use Form Fields

The following form fields are specific for certain forms and hardly reusable in other contexts.

BBCodeAttributesFormField

BBCodeAttributesFormField is a form field for setting the attributes of a BBCode.

DevtoolsProjectExcludedPaketeFormField

DevtoolsProjectExcludedPackagesFormField is a form field for setting the excluded packages of a devtools project.

DevtoolsProjectInstructionsFormField

DevtoolsProjectInstructionsFormField is a form field for setting the installation and update instructions of a devtools project.

DevtoolsProjectOptionalPaketeFormField

DevtoolsProjectOptionalPackagesFormField is a form field for setting the optional packages of a devtools project.

DevtoolsProjectRequiredPaketeFormField

DevtoolsProjectRequiredPackagesFormField is a form field for setting the required packages of a devtools project.