Backend\Behaviors\RelationController

Overview

RelationController uses a combination of lists and forms for managing Model relations.

This behavior is implemented in the controller like so:

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

public $relationConfig = 'config_relation.yaml';

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

Extends

• Backend\Classes\ControllerBehavior
• October\Rain\Extension\ExtensionBase

See Also

• Relation Controller Documentation

---

Public Properties

public string $relationType

public string $relationName

public Model $relationModel

public Model $relationParent

public Model $relationObject

public string $sessionKey

sessionKey used for deferred bindings

public bool|null $readOnly

readOnly disables the ability to add, update, delete or create relations

public bool $deferredBinding

deferredBinding defers all binding actions using a session key

public string $popupSize

popupSize as, either giant, huge, large, small, tiny or adaptive

public string $externalToolbarAppState

externalToolbarAppState defines a mount point for the editor toolbar. Must include a module name that exports the Vue application and a state element name. Format: stateElementName Only works in Vue applications and form document layouts.

Show inherited public properties

Protected Properties

protected Backend\Widgets\Search $searchWidget

protected Backend\Widgets\Toolbar $toolbarWidget

protected array $requiredProperties

protected array $requiredRelationProperties

requiredRelationProperties that must exist for each relationship definition

protected array $requiredConfig

requiredConfig that must exist when applying the primary config file

protected array $actions

actions visible in context of the controller

protected object $originalConfig

originalConfig values

protected array $extraConfig

extraConfig provided by the relationRender method

protected bool $initialized

initialized informs if everything is ready

protected Model $model

model used as parent of the relationship

protected string $field

field for the relationship as defined in the configuration

protected string $alias

alias is something unique to pass to widgets

protected array $toolbarButtons

toolbarButtons to display in view mode.

protected string $eventTarget

eventTarget that triggered an AJAX event (button, list)

protected array $customMessages

customMessages contains default messages that you can override

protected array $modelsToSave

modelsToSave are models that require saving

protected ListWidget|null $viewListWidget

viewListWidget used for viewing as a list

protected FormWidget|null $viewFormWidget

viewFormWidget used for viewing as a form

protected Backend\Widgets\Filter $viewFilterWidget

protected Model $viewModel

viewModel is a reference to the model used for viewing (form only)

protected string $viewMode

viewMode if relation has many (multi) or has one (single)

protected ListWidget|null $manageListWidget

manageListWidget used for managing as a list

protected FormWidget|null $manageFormWidget

manageFormWidget used for managing as a form

protected Model $manageModel

manageModel is a reference to the model used for manage form

protected Backend\Widgets\Filter $manageFilterWidget

protected string $manageTitle

manageTitle used for the manage popup

protected string $manageMode

manageMode of relation as list, form, or pivot

protected int $manageId

manageId is the primary id of an existing relation record

protected Backend\Classes\WidgetBase $pivotWidget

pivotWidget for relations with pivot data

protected Model $pivotModel

pivotModel is a reference to the model used for pivot form

protected string $pivotTitle

pivotTitle used for the pivot popup

protected int $foreignId

foreignId of a selected pivot record

protected array $manageIds

manageIds provided by the relationship chain

Show inherited protected properties

---

Public Methods

public __construct()

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

__construct the behavior

public beforeDisplay()

public beforeDisplay(): void

beforeDisplay fires before the page is displayed and AJAX is executed.

public initRelation()

public initRelation(Model $model, string $field = null): void 

initRelation prepares the widgets used by this behavior

public onRelationButtonAdd()

public onRelationButtonAdd(): void

public onRelationButtonCreate()

public onRelationButtonCreate(): void

public onRelationButtonDelete()

public onRelationButtonDelete(): void

public onRelationButtonLink()

public onRelationButtonLink(): void

public onRelationButtonRemove()

public onRelationButtonRemove(): void

public onRelationButtonUnlink()

public onRelationButtonUnlink(): void

public onRelationButtonUpdate()

public onRelationButtonUpdate(): void

public onRelationClickManageList()

public onRelationClickManageList(): void

public onRelationClickManageListPivot()

public onRelationClickManageListPivot(): void

public onRelationClickViewList()

public onRelationClickViewList(): void

public onRelationManageAdd()

public onRelationManageAdd(): void

onRelationManageAdd an existing related model to the primary model

public onRelationManageAddPivot()

public onRelationManageAddPivot(): void

onRelationManageAddPivot adds multiple items using a single pivot form.

public onRelationManageCreate()

public onRelationManageCreate(): void

onRelationManageCreate a new related model

public onRelationManageDelete()

public onRelationManageDelete(): void

onRelationManageDelete an existing related model completely

public onRelationManageForm()

public onRelationManageForm(): void

public onRelationManagePivotCreate()

public onRelationManagePivotCreate(): void

public onRelationManagePivotForm()

public onRelationManagePivotForm(): void

public onRelationManagePivotUpdate()

public onRelationManagePivotUpdate(): void

public onRelationManageRemove()

public onRelationManageRemove(): void

onRelationManageRemove an existing related model from the primary model

public onRelationManageUpdate()

public onRelationManageUpdate(): void

onRelationManageUpdate an existing related model's fields

public prepareVars()

public prepareVars(): void

prepareVars for display

public relationAfterCancel()

public relationAfterCancel(string $field, Model $model): void

relationAfterCancel called after the user has cancelled the form

public relationAfterCreate()

public relationAfterCreate(string $field, Model $model): void

relationAfterCreate is called after the creation form is saved

public relationAfterDelete()

public relationAfterDelete(string $field, Model $model): void

relationAfterDelete called after the form model is deleted

public relationAfterSave()

public relationAfterSave(string $field, Model $model): void

relationAfterSave is called after the creation or updating form is saved

public relationAfterUpdate()

public relationAfterUpdate(string $field, Model $model): void

relationAfterUpdate is called after the updating form is saved

public relationBeforeCreate()

public relationBeforeCreate(string $field, Model $model): void

relationBeforeCreate is called before the creation form is saved

public relationBeforeSave()

public relationBeforeSave(string $field, Model $model): void

relationBeforeSave is called before the creation or updating form is saved

public relationBeforeUpdate()

public relationBeforeUpdate(string $field, Model $model): void

relationBeforeUpdate is called before the updating form is saved

public relationExtendConfig()

public relationExtendConfig(
    object $config,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendConfig provides an opportunity to manipulate the field configuration.

public relationExtendManageFilterWidget()

public relationExtendManageFilterWidget(
    Backend\Widgets\Filter $widget,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendManageFilterWidget provides an opportunity to manipulate the manage filter widget.

public relationExtendManageFormWidget()

public relationExtendManageFormWidget(
    Backend\Widgets\Form $widget,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendManageFormWidget provides an opportunity to manipulate the manage widget.

public relationExtendManageListWidget()

public relationExtendManageListWidget(
    Backend\Widgets\List $widget,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendManageListWidget provides an opportunity to manipulate the view widget.

public relationExtendManageWidget()

public relationExtendManageWidget($widget, $field, $model): void

public relationExtendPivotFormWidget()

public relationExtendPivotFormWidget(
    Backend\Widgets\Form $widget,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendPivotWidget provides an opportunity to manipulate the pivot widget.

public relationExtendPivotWidget()

public relationExtendPivotWidget($widget, $field, $model): void

public relationExtendRefreshResults()

public relationExtendRefreshResults(string $field): array 

relationExtendRefreshResults is needed because the view widget is often refreshed when the manage widget makes a change, you can use this method to inject additional containers when this process occurs. Return an array with the extra values to send to the browser, eg:

return ['#myCounter' => 'Total records: 6'];

public relationExtendViewFilterWidget()

public relationExtendViewFilterWidget(
    Backend\Widgets\Filter $widget,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendViewFilterWidget provides an opportunity to manipulate the view filter widget.

public relationExtendViewFormWidget()

public relationExtendViewFormWidget(
    Backend\Widgets\Form $widget,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendViewFormWidget provides an opportunity to manipulate the manage widget.

public relationExtendViewListWidget()

public relationExtendViewListWidget(
    Backend\Widgets\List $widget,
    string $field,
    October\Rain\Database\Model $model
): void

relationExtendViewListWidget provides an opportunity to manipulate the view widget.

public relationExtendViewWidget()

public relationExtendViewWidget($widget, $field, $model): void

public relationGetConfig()

public relationGetConfig(): object 

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

public relationGetId()

public relationGetId(string $suffix = null): string 

relationGetId returns a unique ID for this relation and field combination.

public relationGetManageFormWidget()

public relationGetManageFormWidget(): Backend\Widgets\Form|null 

relationGetManageFormWidget returns the manage form widget used by this behavior

public relationGetManageListWidget()

public relationGetManageListWidget(): Backend\Widgets\Lists|null 

relationGetManageListWidget returns the manage list widget used by this behavior

public relationGetManageWidget()

public relationGetManageWidget(): Backend\Classes\WidgetBase 

relationGetManageWidget returns the manage widget used by this behavior

public relationGetMessage()

public relationGetMessage($code): string 

relationGetMessage is a public API for accessing custom messages

public relationGetSessionKey()

public relationGetSessionKey($force = false): void

relationGetSessionKey returns the active session key.

public relationGetViewFormWidget()

public relationGetViewFormWidget(): Backend\Widgets\Form|null 

relationGetManageFormWidget returns the manage form widget used by this behavior

public relationGetViewListWidget()

public relationGetViewListWidget(): Backend\Widgets\Lists|null 

relationGetViewListWidget returns the manage list widget used by this behavior

public relationGetViewWidget()

public relationGetViewWidget(): Backend\Classes\WidgetBase 

relationGetViewWidget returns the view widget used by this behavior

public relationHasField()

public relationHasField($field): bool 

public relationMakePartial()

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

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

public relationRefresh()

public relationRefresh(string $field = null): array 

relationRefresh refreshes the relation container only, useful for returning in custom AJAX requests.

public relationRegisterField()

public relationRegisterField($relationName, $config): void

relationRegisterField registers a new relation dynamically

public relationRender()

public relationRender(
    string $field = null,
    array $options = []
): string 

relationRender renders the relationship manager.

public relationRenderToolbar()

public relationRenderToolbar(string $field = null): string 

relationRenderToolbar renders the toolbar only.

public relationRenderView()

public relationRenderView(string $field = null): string 

relationRenderView renders the view only.

Show inherited public methods

Protected Methods

protected applyExtraConfig()

protected applyExtraConfig($field = null): void

protected beforeAjax()

protected beforeAjax(): void

beforeAjax is needed because each AJAX request must initialize the relation's field name (_relation_field).

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

protected evalDeferredBinding(): bool 

protected evalEventTarget()

protected evalEventTarget(): string 

evalEventTarget determines the source of an AJAX event used for determining the manage mode state. See the evalManageMode method.

protected evalFormContext()

protected evalFormContext($mode = 'manage', $exists = false): void

evalFormContext determines supplied form context

protected evalManageMode()

protected evalManageMode(): string 

evalManageMode determines the management mode based on the relation type and settings

protected evalManageTitle()

protected evalManageTitle(): string 

evalManageTitle determines the management mode popup title

protected evalPivotTitle()

protected evalPivotTitle(): string 

evalPivotTitle determines the pivot mode popup title

protected evalToolbarButtons()

protected evalToolbarButtons(): array 

evalToolbarButtons determines the default buttons based on the model relationship type.

protected evalViewMode()

protected evalViewMode(): string 

evalViewMode determines the view mode based on the model relationship type

protected findExistingRelationIds()

protected findExistingRelationIds($checkIds = null): void

findExistingRelationIds returns the existing record IDs for the relation.

protected getCustomLang()

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

getCustomLang parses custom messages provided by the config

protected getExtraConfig()

protected getExtraConfig(): string 

getExtraConfig returns extra config with the relation chain, encoded

protected getPivotDataForAttach()

protected getPivotDataForAttach($saveData): array 

getPivotDataForAttach returns either a list of IDs to sync, or an associative array with sync keys and pivot attributes as values.

This method only exists to send the pivot attributes to the model.relation.attach event. The attributes are set and saved a second time via the regular life cycle. Eloquent should not send it to SQL twice if the attributes are an exact match.

protected initNestedRelation()

protected initNestedRelation($model, $parentField): void

initNestedRelation checks the extra configuration for a relationship chain and binds the manage forms to the controller, which may contain additional relation definitions via the relation form widget.

protected initRelationInternal()

protected initRelationInternal(
    Model $model,
    string $field = null
): void 

initRelationInternal is an internal method for initRelation

protected makeConfigForMode()

protected makeConfigForMode(
    $mode = 'view',
    $type = 'list',
    $throwException = true
): void

makeConfigForMode returns the configuration for a mode (view, manage, pivot) for an expected type (list, form) and uses fallback configuration

protected makeFilterWidgetFor()

protected makeFilterWidgetFor(
    $type $type
): Backend\Classes\WidgetBase|null 

protected makeListStructureConfig()

protected makeListStructureConfig($config): object|null 

protected makeManageFormWidget()

protected makeManageFormWidget(): Backend\Widgets\Form|null 

makeManageFormWidget prepares the form widget for management

protected makeManageListWidget()

protected makeManageListWidget(): Backend\Widgets\Lists|null 

makeManageListWidget prepares the list widget for management

protected makeNestedRelationModel()

protected makeNestedRelationModel($model, $field): void

makeNestedRelationModel resolves a relation based on a nested field name E.g: model[relation1][relation2] → $model->relation1()->relation2()

protected makePivotFormWidget()

protected makePivotFormWidget(): void

makePivotFormWidget return a form widget based on pivot configuration

protected makeSearchWidget()

protected makeSearchWidget(): void

protected makeToolbarWidget()

protected makeToolbarWidget(): void

protected makeViewFormWidget()

protected makeViewFormWidget(): Backend\Widgets\Form|null 

makeViewFormWidget prepares the form widget for viewing

protected makeViewListWidget()

protected makeViewListWidget(): Backend\Widgets\Lists|null 

makeViewListWidget prepares the list widget for viewing

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

protected resetViewWidgetModel(): void

resetViewWidgetModel is an internal method used when deleting singular relationships

protected setExtraConfig()

protected setExtraConfig($config): void

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

protected showFlashMessage($message): void 

showFlashMessage displays a flash message if its found

protected useFlashMessages()

protected useFlashMessages(): bool 

useFlashMessages determines if flash messages should be used

protected validateField()

protected validateField(string $field = null): string 

validateField validates the supplied field and initializes the relation manager.

Show inherited protected methods