1. Documentation
  2. API
  3. Backend
  4. Widgets
  5. Form

Backend\Widgets\Form

Overview

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

Extends
Implements
  • 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.

Options:

  • 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

Options:

  • 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

renderField

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) {
    $modelToSave->save();
}

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