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

Backend\Behaviors\RelationController

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

Extends:

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

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.

Public properties

public string $relationType

Relationship type

public string $relationName

Relationship name

public Model $relationModel

Relationship model

public Model $relationObject

Relationship object

public string $sessionKey

Active session key, used for deferred bindings.

public bool $readOnly

Disables the ability to add, update, delete or create relations.

public bool $deferredBinding

Defers all binding actions using a session key when it is available.

Show inherited public properties

Inherited public properties

Protected properties

protected Backend\Widgets\Search $searchWidget

Reference to the search widget object.

protected Backend\Widgets\Toolbar $toolbarWidget

Reference to the toolbar widget object.

protected Backend\Classes\WidgetBase $viewWidget

Reference to the widget used for viewing (list or form).

protected Backend\Widgets\Filter $viewFilterWidget

Reference to the view filter widget.

protected Backend\Classes\WidgetBase $manageWidget

Reference to the widget used for relation management.

protected Backend\Widgets\Filter $manageFilterWidget

Reference to the manage filter widget.

protected Backend\Classes\WidgetBase $pivotWidget

Reference to widget for relations with pivot data.

protected $requiredProperties

Properties that must exist in the controller using this behavior.

protected array $requiredRelationProperties

Properties that must exist for each relationship definition.

protected array $requiredConfig

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

protected array $actions

Visible actions in context of the controller

protected array $originalConfig

Original configuration values

protected array $extraConfig

Config provided by the relationRender method

protected bool $initialized

Has the behavior been initialized.

protected Model $model

The parent model of the relationship.

protected Model $field

The relationship field as defined in the configuration.

protected string $alias

A unique alias to pass to widgets.

protected array $toolbarButtons

The set of buttons to display in view mode.

protected Model $viewModel

Reference to the model used for viewing (form only).

protected string $viewMode

Relation has many (multi) or has one (single).

protected string $manageTitle

The title used for the manage popup.

protected string $manageMode

Management of relation as list, form, or pivot.

protected string $forceViewMode

Force a certain view mode.

protected string $forceManageMode

Force a certain manage mode.

protected string $eventTarget

The target that triggered an AJAX event (button, list)

protected int $manageId

Primary id of an existing relation record.

protected int $foreignId

Foeign id of a selected pivot record.

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 initRelation(Model $model, string $field=NULL)

Prepare the widgets used by this behavior

Parameters
  • Model $model
  • string $field

public void onRelationButtonAdd()

public void onRelationButtonCreate()

public void onRelationButtonDelete()

public void onRelationButtonLink()

public void onRelationButtonRemove()

public void onRelationButtonUnlink()

public void onRelationButtonUpdate()

public void onRelationClickManageList()

public void onRelationClickManageListPivot()

public void onRelationClickViewList()

public void onRelationManageAdd()

Add an existing related model to the primary model

public void onRelationManageAddPivot()

Add multiple items using a single pivot form.

public void onRelationManageCreate()

Create a new related model

public void onRelationManageDelete()

Delete an existing related model completely

public void onRelationManageForm()

public void onRelationManagePivotCreate()

public void onRelationManagePivotForm()

public void onRelationManagePivotUpdate()

public void onRelationManageRemove()

Remove an existing related model from the primary model

public void onRelationManageUpdate()

Updated an existing related model's fields

public void prepareVars()

Prepares the view data.

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

Provides an opportunity to manipulate the field configuration.

Parameters

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

Provides an opportunity to manipulate the manage filter widget.

Parameters

public void relationExtendManageWidget(Backend\Classes\WidgetBase $widget, string $field, October\Rain\Database\Model $model)

Provides an opportunity to manipulate the manage widget.

Parameters

public void relationExtendPivotWidget(Backend\Classes\WidgetBase $widget, string $field, October\Rain\Database\Model $model)

Provides an opportunity to manipulate the pivot widget.

Parameters

public array relationExtendRefreshResults(string $field)

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

Parameters
  • string $field

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

Provides an opportunity to manipulate the view filter widget.

Parameters

public void relationExtendViewWidget(Backend\Classes\WidgetBase $widget, string $field, October\Rain\Database\Model $model)

Provides an opportunity to manipulate the view widget.

Parameters

public string relationGetId(string $suffix=NULL)

Returns a unique ID for this relation and field combination.

Parameters
  • string $suffix - A suffix to use with the identifier.

public Backend\Classes\WidgetBase relationGetManageWidget()

Returns the manage widget used by this behavior.

public void relationGetSessionKey($force=false)

Returns the active session key.

Parameters
  • $force

public Backend\Classes\WidgetBase relationGetViewWidget()

Returns the view widget used by this behavior.

public string relationMakePartial(string $partial, array $params=array())

Controller accessor for making partials within this behavior.

Parameters
  • string $partial
  • array $params

public array relationRefresh(string $field=NULL)

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

Parameters
  • string $field - Relation definition.

public string relationRender(string $field, array $options=array())

Renders the relationship manager.

Parameters
  • string $field - The relationship field.
  • array $options

public string relationRenderToolbar(string $field=NULL)

Renders the toolbar only.

Parameters
  • string $field - The relationship field.

public string relationRenderView(string $field=NULL)

Renders the view only.

Parameters
  • string $field - The relationship field.

Show inherited public methods

Inherited public methods

Protected methods

protected void applyExtraConfig($config, $field=NULL)

Apply extra configuration

Parameters
  • $config
  • $field

protected void beforeAjax()

The controller action is responsible for supplying the parent model so it's action must be fired. Additionally, each AJAX request must supply the relation's field name (_relation_field).

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 void evalFormContext($mode='manage', $exists=false)

Determine supplied form context.

Parameters
  • $mode
  • $exists

protected string evalManageMode()

Determine the management mode based on the relation type and settings.

protected string evalManageTitle()

Determine the management mode popup title.

protected string evalToolbarButtons()

Determine the default buttons based on the model relationship type.

protected string evalViewMode()

Determine the view mode based on the model relationship type.

protected void findExistingRelationIds($checkIds=NULL)

Returns the existing record IDs for the relation.

Parameters
  • $checkIds

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

Returns the configuration for a mode (view, manage, pivot) for an expected type (list, form). Uses fallback configuration.

Parameters
  • $mode
  • $type
  • $throwException

protected Backend\Classes\WidgetBase|null makeFilterWidget($type $type)

Initialize a filter widget

Parameters
  • $type $type - String Either 'manage' or 'view'

protected void makeManageWidget()

protected void makePivotWidget()

protected void makeSearchWidget()

protected void makeToolbarWidget()

protected void makeViewWidget()

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 setModelAttributes(October\Rain\Database\Model $model, array $saveData)

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

Parameters

protected string validateField(string $field=NULL)

Validates the supplied field and initializes the relation manager.

Parameters
  • string $field - The relationship field.

Show inherited protected methods

Inherited protected methods