1. Documentation
  2. API
  3. Backend
  4. Behaviors
  5. FormController

Backend\Behaviors\FormController

Overview

FormController adds features for working with backend forms. This behavior will inject CRUD actions to the controller — including create, update and preview — along with some relevant AJAX handlers.

Each action supports a custom context code, allowing fields to be displayed or hidden on a contextual basis, as specified by the form field definitions or some other custom logic.

This behavior is implemented in the controller like so:

public $implement = [
    \Backend\Behaviors\FormController::class,
];

public $formConfig = 'config_form.yaml';

The $formConfig property makes reference to the form configuration values as either a YAML file, located in the controller view directory, or directly as a PHP array.

Extends
See Also

Public Properties

There are no public properties in the class.

Show inherited public properties

Inherited Public Properties

Protected Properties

protected Backend\Classes\Controller|FormController $controller

controller reference

protected Backend\Widgets\Form $formWidget

formWidget object

protected $requiredProperties

requiredProperties that must exist in the controller using this behavior.

protected array $requiredConfig

requiredConfig that must exist when applying the primary config file

protected array $actions

actions visible in context of the controller

protected string $context

context to pass to the form widget

protected Model $model

model used by the form

protected array $customMessages

customMessages contains default messages that you can override

protected array $modelsToSave

modelsToSave are models that require saving

Show inherited protected properties

Inherited Protected Properties

Public Methods

public __construct()

public __construct(Backend\Classes\Controller $controller): void

__construct the behavior

public create()

public create(string $context = null): void

create controller action used for creating new model records.

public create_onCancel()

public create_onCancel($context = null): mixed

create_onCancel AJAX handler called from the create action and used for aborting record creation

This handler will invoke the unique controller override formAfterCancel.

public create_onSave()

public create_onSave(string $context = null): mixed

create_onSave AJAX handler called from the create action and primarily used for creating new records.

This handler will invoke the unique controller overrides formBeforeCreate and formAfterCreate.

public static extendFormFields()

public static extendFormFields($callback): void

extendFormFields is a static helper for extending form fields

public formAfterCancel()

public formAfterCancel(Model $model): void

formAfterCancel called after the user has cancelled the form

public formAfterCreate()

public formAfterCreate(Model $model): void

formAfterCreate is called after the creation form is saved

public formAfterDelete()

public formAfterDelete(Model $model): void

formAfterDelete called after the form model is deleted

public formAfterSave()

public formAfterSave(Model $model): void

formAfterSave is called after the creation or updating form is saved

public formAfterUpdate()

public formAfterUpdate(Model $model): void

formAfterUpdate is called after the updating form is saved

public formBeforeCreate()

public formBeforeCreate(Model $model): void

formBeforeCreate is called before the creation form is saved

public formBeforeSave()

public formBeforeSave(Model $model): void

formBeforeSave is called before the creation or updating form is saved

public formBeforeUpdate()

public formBeforeUpdate(Model $model): void

formBeforeUpdate is called before the updating form is saved

public formCheckPermission()

public formCheckPermission($name): void

formCheckPermission checks if a custom permission has been specified

public formCreateModelObject()

public formCreateModelObject(): Model

formCreateModelObject creates a new instance of a form model. This logic can be changed by overriding it in the controller.

public formExtendFields()

public formExtendFields(
    Backend\Widgets\Form $host,
    array $fields
): void

formExtendFields is called after the form fields are defined

public formExtendFieldsBefore()

public formExtendFieldsBefore(Backend\Widgets\Form $host): void

formExtendFieldsBefore is called before the form fields are defined

public formExtendModel()

public formExtendModel(Model $model): Model

formExtendModel extends the supplied model used by create and update actions, the model can be altered by overriding it in the controller.

public formExtendQuery()

public formExtendQuery(October\Rain\Database\Builder $query): void

formExtendQuery extends the query used for finding the form model. Extra conditions can be applied to the query, for example, $query->withTrashed();

public formExtendRefreshData()

public formExtendRefreshData(
    Backend\Widgets\Form $host,
    array $saveData
): array

formExtendRefreshData is called before the form is refreshed, should return an array of additional save data.

public formExtendRefreshFields()

public formExtendRefreshFields(
    Backend\Widgets\Form $host,
    array $fields
): array

formExtendRefreshFields is called when the form is refreshed, giving the opportunity to modify the form fields.

public formExtendRefreshResults()

public formExtendRefreshResults(
    Backend\Widgets\Form $host,
    array $result
): array

formExtendRefreshResults is called after the form is refreshed, should return an array of additional result parameters.

public formFindModelObject()

public formFindModelObject(string $recordId): Model

formFindModelObject finds a Model record by its primary identifier, used by update actions. This logic can be changed by overriding it in the controller.

public formGetConfig()

public formGetConfig(): object

formGetConfig returns the configuration used by this behavior. You may override this method in your controller as an alternative to defining a formConfig property.

public formGetContext()

public formGetContext(): string

Returns the active form context, either obtained from the postback variable called form_context or detected from the configuration, or routing parameters.

public formGetDesignFormSize()

public formGetDesignFormSize(): void

formGetDesignFormSize is an API call used by ListController

public formGetId()

public formGetId(string $suffix = null): string

formGetId returns a unique ID for the form widget used by this behavior. This is useful for dealing with identifiers in the markup.

<div id="<?= $this->formGetId()">...</div>

A suffix may be used passed as the first argument to reuse the identifier in other areas.

<button id="<?= $this->formGetId('button')">...</button>

public formGetModel()

public formGetModel(): October\Rain\Database\Model

Returns the model initialized by this form behavior. The model will be provided by one of the page actions or AJAX handlers via the initForm method.

public formGetRedirectUrl()

public formGetRedirectUrl(
    string $context = null,
    Model $model = null
): string

formGetRedirectUrl returns a URL based on supplied context, relative URLs are treated as backend URLs

public formGetSessionKey()

public formGetSessionKey(): string

formGetSessionKey is a helper to get the form session key.

public formGetWidget()

public formGetWidget(): Backend\Widgets\Form

formGetWidget returns the form widget used by this behavior.

public formHasMultisite()

public formHasMultisite($model): void

public formHasOutsideFields()

public formHasOutsideFields(): bool

formHasOutsideFields is a view helper to check if a form tab has fields in the non-tabbed section (outside fields).

<?php if ($this->formHasOutsideFields()): ?>
    <!-- Do something -->
<?php endif ?>

public formHasPrimaryTabs()

public formHasPrimaryTabs(): bool

formHasPrimaryTabs is a view helper to check if a form tab has fields in the primary tab section.

<?php if ($this->formHasPrimaryTabs()): ?>
    <!-- Do something -->
<?php endif ?>

public formHasSecondaryTabs()

public formHasSecondaryTabs(): bool

formHasSecondaryTabs is a view helper to check if a form tab has fields in the secondary tab section.

<?php if ($this->formHasSecondaryTabs()): ?>
    <!-- Do something -->
<?php endif ?>

public formMakePartial()

public formMakePartial(string $partial, array $params = []): string

formMakePartial is a controller accessor for making partials within this behavior.

public formRefreshFields()

public formRefreshFields(array|string $names): array

formRefreshField is a view helper to render a field from AJAX based on their field names.

public formRender()

public formRender(array $options = []): string

formRender the prepared form markup. This method is usually called from a view file.

<?= $this->formRender() ?>

The first argument supports an array of render options. The supported options can be found via the render method of the Form widget class.

<?= $this->formRender(['preview' => true, 'section' => 'primary']) ?>
See Also

public formRenderDesign()

public formRenderDesign($options = []): void

formRenderDesign renders a preset form design as either: basic, custom, sidebar, document, popup

public formRenderField()

public formRenderField(string $name, array $options = []): string

formRenderField is a view helper to render a single form field.

<?= $this->formRenderField('field_name') ?>

public formRenderOutsideFields()

public formRenderOutsideFields(): string

formRenderOutsideFields is a view helper to render the form fields belonging to the non-tabbed section (outside form fields).

<?= $this->formRenderOutsideFields() ?>

public formRenderPreview()

public formRenderPreview(): string

formRenderPreview is a view helper to render the form in preview mode.

<?= $this->formRenderPreview() ?>

public formRenderPrimaryTab()

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

formRenderPrimaryTab renders the contents of a primary tab

public formRenderPrimaryTabs()

public formRenderPrimaryTabs(): string

formRenderPrimaryTabs is a view helper to render the form fields belonging to the primary tabs section.

<?= $this->formRenderPrimaryTabs() ?>

public formRenderSecondaryTab()

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

formRenderSecondaryTab renders the contents of a secondary tab

public formRenderSecondaryTabs()

public formRenderSecondaryTabs(): string

formRenderSecondaryTabs is a view helper to render the form fields belonging to the secondary tabs section.

<?= $this->formRenderPrimaryTabs() ?>

public formSetSaveValue()

public formSetSaveValue($key, $value): void

formSetSaveValue will override the save values passed to the form. Set the value to null to omit the field from the dataset.

public index_onLoadPopupForm()

public index_onLoadPopupForm(): void

index_onPopupLoadForm

public index_onPopupCancel()

public index_onPopupCancel(): void

public index_onPopupDelete()

public index_onPopupDelete(): void

public index_onPopupSave()

public index_onPopupSave(): void

index_onSave

public initForm()

public initForm(
    October\Rain\Database\Model $model,
    string $context = null
): void

initForm initializes the form configuration against a model and context value. This will process the configuration found in the $formConfig property and prepare the Form widget, which is the underlying tool used for actually rendering the form. The model used by this form is passed to this behavior via this method as the first argument.

See Also

public makeMultisiteRedirect()

public makeMultisiteRedirect($context = null, $model = null): void

public makeRedirect()

public makeRedirect(
    string $context = null,
    Model $model = null,
    $queryParams = []
): Redirect

makeRedirect returns a Redirect object based on supplied context and parses the model primary key.

public onSwitchSite()

public onSwitchSite($recordId = null): void

public preview()

public preview(int $recordId = null, string $context = null): void

preview controller action used for viewing existing model records. This action takes a record identifier (primary key of the model) to locate the record used for sourcing the existing preview data.

public update()

public update(int $recordId = null, string $context = null): void

update controller action used for updating existing model records. This action takes a record identifier (primary key of the model) to locate the record used for sourcing the existing form values.

public update_onCancel()

public update_onCancel(int $recordId = null): mixed

update_onCancel AJAX handler called from the update action and used for aborting existing record updates.

This handler will invoke the unique controller override formAfterCancel.

public update_onDelete()

public update_onDelete(int $recordId = null): mixed

update_onDelete AJAX handler called from the update action and used for deleting existing records.

This handler will invoke the unique controller override formAfterDelete.

public update_onSave()

public update_onSave(
    int $recordId = null,
    string $context = null
): mixed

update_onSave AJAX handler called from the update action and primarily used for updating existing records.

This handler will invoke the unique controller overrides formBeforeUpdate and formAfterUpdate.

Show inherited public methods

Inherited Public Methods

Protected Methods

protected addHandlerToSiteSwitcher()

protected addHandlerToSiteSwitcher(): void

protected createModel()

protected createModel(): October\Rain\Database\Model

createModel internal method used to prepare the form model object.

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

protected getCustomLang($name, $default = null, $extras = []): string

getCustomLang parses custom messages provided by the config

protected getDesignBodyClass()

protected getDesignBodyClass(): void

protected getDesignDisplayMode()

protected getDesignDisplayMode(): void

protected getDesignFormSize()

protected getDesignFormSize(): void

protected getLang()

protected getLang(
    string $name,
    string $default = null,
    array $extras = []
): string

getLang parses in some default variables to a language string defined in config.

protected getRedirectUrl()

protected getRedirectUrl(string $context = null): string

getRedirectUrl is an internal method that returns a redirect URL from the config based on supplied context. Otherwise the default redirect is used.

protected hidePopupDesign()

protected hidePopupDesign(): void

protected isHorizontalForm()

protected isHorizontalForm(): bool

protected isPopupDesign()

protected isPopupDesign(): bool

protected isSurveyDesign()

protected isSurveyDesign(): bool

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(October\Rain\Database\Model $model): void

Prepares commonly used view data.

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.

Show inherited protected methods

Inherited Protected Methods