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