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

Backend\Behaviors\FormController

Source: ~/modules/backend/behaviors/FormController.php

Extends:

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',
];

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.

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

Reference to the back end controller.

protected Backend\Widgets\Form $formWidget

Reference to the widget object.

protected $requiredProperties

Properties that must exist in the controller using this behavior.

protected array $requiredConfig

Configuration values that must exist when applying the primary config file.

  • modelClass: Class name for the model
  • form: Form field definitions

protected array $actions

Visible actions in context of the controller

protected string $context

The context to pass to the form widget.

protected Model $model

The initialized model used by the form.

protected array $modelsToSave

List of prepared models that require saving.

Show inherited protected properties

Inherited protected properties

Public methods

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

Behavior constructor

Parameters

public void create(string $context=NULL)

Controller "create" action used for creating new model records.

Parameters
  • string $context - Form context

public mixed create_onSave(string $context=NULL)

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

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

Parameters
  • string $context - Form context

public static void extendFormFields(callable $callback)

Static helper for extending form fields.

Parameters
  • callable $callback

public void formAfterCreate(Model $model)

Called after the creation form is saved.

Parameters
  • Model $model

public void formAfterDelete(Model $model)

Called after the form model is deleted.

Parameters
  • Model $model

public void formAfterSave(Model $model)

Called after the creation or updating form is saved.

Parameters
  • Model $model

public void formAfterUpdate(Model $model)

Called after the updating form is saved.

Parameters
  • Model $model

public void formBeforeCreate(Model $model)

Called before the creation form is saved.

Parameters
  • Model $model

public void formBeforeSave(Model $model)

Called before the creation or updating form is saved.

Parameters
  • Model $model

public void formBeforeUpdate(Model $model)

Called before the updating form is saved.

Parameters
  • Model $model

public Model formCreateModelObject()

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

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

Called after the form fields are defined.

Parameters
  • Backend\Widgets\Form $host - The hosting form widget
  • array $fields - Array of all defined form field objects (\Backend\Classes\FormField)

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

Called before the form fields are defined.

Parameters

public Model formExtendModel(Model $model)

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

Parameters
  • Model $model

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

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

Parameters

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

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

Parameters

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

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

Parameters

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

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

Parameters

public Model formFindModelObject(string $recordId)

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

Parameters
  • string $recordId

public string formGetContext()

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

public string formGetId(string $suffix=NULL)

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>
Parameters
  • string $suffix

public October\Rain\Database\Model formGetModel()

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 string formGetSessionKey()

Helper to get the form session key.

public Backend\Widgets\Form formGetWidget()

Returns the form widget used by this behavior.

public bool formHasOutsideFields()

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 bool formHasPrimaryTabs()

View helper to check if a form tab has fields in the primary tab section.

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

public bool formHasSecondaryTabs()

View helper to check if a form tab has fields in the secondary tab section.

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

public string formRender(array $options=array())

Method to render 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:

Parameters
  • array $options - Render options

public string formRenderField(string $name, array $options=array())

View helper to render a single form field.

<?= $this->formRenderField('field_name') ?>
Parameters
  • string $name - Field name
  • array $options - (e.g. ['useContainer'=>false])

public string formRenderOutsideFields()

View helper to render the form fields belonging to the non-tabbed section (outside form fields).

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

public string formRenderPreview()

View helper to render the form in preview mode.

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

public string formRenderPrimaryTabs()

View helper to render the form fields belonging to the primary tabs section.

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

public string formRenderSecondaryTabs()

View helper to render the form fields belonging to the secondary tabs section.

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

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

Initialize 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:

Parameters

public Redirect makeRedirect(string $context=NULL, Model $model=NULL)

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

Parameters
  • string $context - Redirect context, eg: create, update, delete
  • Model $model - The active model to parse in it's ID and attributes.

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

Controller "preview" 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.

Parameters
  • int $recordId - Record identifier
  • string $context - Form context

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

Controller "update" 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.

Parameters
  • int $recordId - Record identifier
  • string $context - Form context

public mixed update_onDelete(int $recordId=NULL)

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

This handler will invoke the unique controller override formAfterDelete.

Parameters
  • int $recordId - Record identifier

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

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

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

Parameters
  • int $recordId - Record identifier
  • string $context - Form context

Show inherited public methods

Inherited public methods

Protected methods

protected October\Rain\Database\Model createModel()

Internal method used to prepare the form model object.

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

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

Parameters

protected string getLang(string $name, string $default=NULL, array $extras=array())

Parses in some default variables to a language string defined in config.

Parameters
  • string $name - Configuration property containing the language string
  • string $default - A default language string to use if the config is not found
  • array $extras - Any extra params to include in the language string variables

protected string getRedirectUrl(string $context=NULL)

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

Parameters
  • string $context - Redirect context, eg: create, update, delete.

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

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();
}
Parameters

protected void prepareVars(October\Rain\Database\Model $model)

Prepares commonly used view data.

Parameters

protected void setModelAttributes(October\Rain\Database\Model $model, array $saveData)

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

Parameters

Show inherited protected methods

Inherited protected methods