Form Widget is used for building back end forms and renders a form

  • October\Contracts\Element\FormElement

Public Properties

public array $fields

fields configuration.

public array $tabs

tabs (primary) configuration.

public array $secondaryTabs

secondaryTabs configuration.

public Model $model

model object for the form.

public array $data

data containing field values, if none supplied, model is used.

public string $context

context of this form, fields that do not belong to this context will not be shown.

public string $arrayName

arrayName if the field element names should be contained in an array. Eg: <input name="nameArray[fieldName]" />

public bool $isNested

isNested is used to flag that this form is being rendered as part of another form, a good indicator to expect that the form model and dataset values will differ.

public bool $useModelFields

useModelFields requests form fields from the supplied model.

public string $sessionKey

sessionKey for the active session, used for editing forms and deferred bindings.

public string $sessionKeySuffix

sessionKeySuffix adds some extra uniqueness to the session key.

public string|null $parentFieldName

parentFieldName if this form is nested in a field.

public bool $previewMode

previewMode renders this form with uneditable preview data.

public bool $surveyMode

surveyMode renders this form using a survey layout (no tabs)

public bool $horizontalMode

horizontalMode renders this form using a horizontal layout

Show inherited public properties

Inherited Public Properties

Protected Properties

protected $defaultAlias

defaultAlias to identify this widget.

protected boolean $fieldsDefined

fieldsDefined determines if field definitions have been created.

protected array $allFields

allFields used in this form.

See Also

protected object $allTabs

allTabs sections used in this form.

See Also

protected array $saveDataOverride

saveDataOverride allows for values to be changed during the save process

protected FieldsetDefinition|null $activeTabSection

activeTabSection where fields are currently being added

protected array $formWidgets

formWidgets collection of all form widgets used in this form.

protected Backend\Classes\WidgetManager $widgetManager

protected array $modelsToSave

modelsToSave are models that require saving

Show inherited protected properties

Inherited Protected Properties

Public Methods

public addField()

public addField($name, $config = ]): [Backend\Classes\FormField 

public addFields()

public addFields(
    array $fields,
    string $addToArea = null
): October\Rain\Element\ElementHolder 

addFields programmatically, used internally and for extensibility

public addFormField()

public addFormField(
    $fieldName = null,
    $label = null
): October\Rain\Element\Form\FieldDefinition 

addFormField adds a field to the fieldset

public addSecondaryTabField()

public addSecondaryTabField($name, $config = ]): [Backend\Classes\FormField 

public addSecondaryTabFields()

public addSecondaryTabFields($fields): October\Rain\Element\ElementHolder 

public addTabField()

public addTabField($name, $config = ]): [Backend\Classes\FormField 

public addTabFields()

public addTabFields($fields): October\Rain\Element\ElementHolder 

public bindToController()

public bindToController(): void 

bindToController ensure fields are defined and form widgets are registered so they can also be bound to the controller this allows their AJAX features to operate.

public getContext()

public getContext(): string 

getContext returns the active context for displaying the form.

public getField()

public getField($field): void

getField object specified

public getFields()

public getFields(): array 

getFields for the instance

public getFormContext()

public getFormContext(): void

getFormContext returns the current form context

public getFormFieldset()

public getFormFieldset(): October\Rain\Element\Form\FieldsetDefinition 

getFormFieldset returns the current fieldset definition

public getFormWidget()

public getFormWidget(string $field): void

getFormWidget returns a specified form widget

public getFormWidgets()

public getFormWidgets(): array 

getFormWidgets for the instance

public getModel()

public getModel(): Model|null 

getModel returns the active model for this form.

public getSaveData()

public getSaveData(): array 

getSaveData returns post data from a submitted form.

public getSessionKey()

public getSessionKey(): string 

getSessionKey returns the active session key.

public getSessionKeyWithSuffix()

public getSessionKeyWithSuffix(): string 

public getTab()

public getTab(string $field): mixed 

Get a specified tab object. Options: outside, primary, secondary.

public getTabs()

public getTabs(): object[FormTabs] 

getTabs for the instance

public init()

public init(): void

init the widget, called by the constructor and free from its parameters.

public nameToId()

public nameToId($input $input): string 

nameToId is a helper method to convert a field name to a valid ID attribute

public onLazyLoadTab()

public onLazyLoadTab(): void

onLazyLoadTab renders all fields of a tab in the target tab pane

public onRefresh()

public onRefresh(): array 

onRefresh event handler for refreshing the form.

public removeField()

public removeField($name): bool 

removeField programmatically

public removeTab()

public removeTab(string $name): void

removeTab programmatically remove all fields belonging to a tab

public render()

public render(array $options = []): string|bool 

render the widget.


  • preview: Render this form as an uneditable preview. Default: false
  • useContainer: Wrap the result in a container, used by AJAX. Default: true
  • section: Which form section to render. Default: null
    • outside: Renders the Outside Fields section.
    • primary: Renders the Primary Tabs section.
    • secondary: Renders the Secondary Tabs section.
    • null: Renders all sections

public renderField()

public renderField(
    Backend\Classes\FormField|string $field,
    array $options = []
): string|bool 

renderField renders a single form field


  • useContainer: Wrap the result in a container, used by AJAX. Default: true

public renderFieldElement()

public renderFieldElement(
    Backend\Classes\FormField|string $field
): string|bool 

renderFieldElement renders the HTML element for a field

public renderFields()

public renderFields($fields): string 

renderFields renders the specified fields.

public renderTab()

public renderTab($tabName, $options = []): void


public renderTabSection()

public renderTabSection($tabs): string 

renderTabSection renders the specified tabs.

public setFormValues()

public setFormValues(array $data = null): array 

setFormValues sets or resets form field values.

public setSaveDataOverride()

public setSaveDataOverride($key, $value): void

setSaveDataOverride will override the save data captured by the form

Show inherited public methods

Inherited Public Methods

Protected Methods

protected addFieldsFromModel()

protected addFieldsFromModel($addToArea = null): void 

addFieldsFromModel from the model

protected applyFiltersFromModel()

protected applyFiltersFromModel($applyData = null): void

applyFiltersFromModel allows the model to filter fields

protected cleanSaveDataInternal()

protected cleanSaveDataInternal($data): array 

cleanSaveDataInternal will purge disabled and hidden fields from the dataset

protected dataArrayForget()

protected dataArrayForget(array &$array, array $parts): void 

Variant to array_forget() but preserves dots in key names.

protected dataArrayGet()

protected dataArrayGet(
    array $array,
    array $parts,
    null $default = null
): mixed 

Variant to array_get() but preserves dots in key names.

protected dataArraySet()

protected dataArraySet(
    array &$array,
    array $parts,
    string $value
): array 

Variant to array_set() but preserves dots in key names.

protected deferPurgedSaveAttributes()

protected deferPurgedSaveAttributes(
    October\Rain\Database\Model $model,
    array $attributesToPurge
): void 

deferPurgedSaveAttributes removes an array of attributes from the model. If the model implements the Purgeable trait, this is preferred over the internal logic.

protected defineFormFields()

protected defineFormFields(): void

defineFormFields creates a flat array of form fields from the configuration and slots fields in to their respective tabs

protected evalFieldName()

protected evalFieldName($field): array 

evalFieldName parses a field's name for embedded context with a result of fieldName@context to [fieldName, context]

protected getFieldDepends()

protected getFieldDepends(Backend\Classes\FormField $field): string 

getFieldDepends returns a HTML encoded value containing the other fields this field depends on

protected getFieldValue()

protected getFieldValue(mixed $field, mixed $data = null): string 

getFieldValue looks up the field value.

protected getSaveDataInternal()

protected getSaveDataInternal(): array 

getSaveDataInternal will return all possible data to save

protected getSaveDataSourceInternal()

protected getSaveDataSourceInternal(): array 

protected hasFieldValue()

protected hasFieldValue($field, $data = null): bool 

hasFieldValue determines if the field value is found in the data.

protected initFormTabs()

protected initFormTabs(): void

protected initFormWidgetsConcern()

protected initFormWidgetsConcern(): void

protected isFormWidget()

protected isFormWidget($fieldType): bool 

isFormWidget checks if a field type is a widget or not

protected loadAssets()

protected loadAssets(): void

loadAssets adds widget specific asset files. Use $this->addJs() and $this->addCss() to register new assets to include on the page.

protected makeFormField()

protected makeFormField($name, $config = ]): [Backend\Classes\FormField 

makeFormField creates a form field object from name and configuration

protected makeFormFieldWidget()

protected makeFormFieldWidget($field): Backend\Classes\FormWidgetBase|null 

makeFormFieldWidget object from a form field object

protected performSaveOnModel()

protected performSaveOnModel($model, $data, $options = null): void

performSaveOnModel saves complex data against a model inside a database transaction.

protected prepareModelsToSave()

protected prepareModelsToSave(
    October\Rain\Database\Model $model,
    array $saveData
): array 

prepareModelsToSave takes a model and fills it with data from a multidimensional array. If an attribute is found to be a relationship, that relationship is also filled.

$modelsToSave = $this->prepareModelsToSave($model, [...]);

foreach ($modelsToSave as $modelToSave) {

protected prepareVars()

protected prepareVars(): void

prepareVars prepares the form data

protected processAutoOrder()

protected processAutoOrder($tabs): void

processAutoOrder applies a default sort order to all fields

protected processAutoSpan()

protected processAutoSpan($tabs): void

processAutoSpan converts fields with a span set to 'auto' as either 'left' or 'right' depending on the previous field.

protected processFieldOptionValues()

protected processFieldOptionValues($fields): void

processFieldOptionValues sets the callback for retrieving options from fields that specifically require it

protected processFormWidgetFields()

protected processFormWidgetFields($fields): void

processFormWidgetFields will mutate fields types that are registered as widgets, convert their type to 'widget' and internally allocate the widget object

protected processPermissionCheck()

protected processPermissionCheck($fields): void

processPermissionCheck check if user has permissions to show the field and removes it if permission is denied

protected processRequiredAttributes()

protected processRequiredAttributes($fields): void

processRequiredAttributes will set the required flag based on the model preference

protected processTranslatableAttributes()

protected processTranslatableAttributes($fields): void

processTranslatableAttributes will set the translatable flag based on the model preference

protected processValidationAttributes()

protected processValidationAttributes($fields): void

processValidationAttributes applies the field name to the validation engine

protected setFormValuesInternal()

protected setFormValuesInternal(array $data = null): array 

setFormValuesInternal method delays resetting form widgets

protected setModelAttributes()

protected setModelAttributes(
    October\Rain\Database\Model $model,
    array $saveData,
    $attrName = ''
): void 

setModelAttributes sets a data collection to a model attributes, relations are also set.

protected showFieldLabels()

protected showFieldLabels($field): bool 

showFieldLabels is a helper method to determine if field should be rendered with label and comments.

protected useDefaultValues()

protected useDefaultValues(): bool 

useDefaultValues determines when to apply default data, usually when the context is "create", the model is non-existent or the form is nested.

protected validateModel()

protected validateModel(): mixed 

validateModel validates the supplied form model.

Show inherited protected methods

Inherited Protected Methods