RelationController

Uses a combination of lists and forms for managing Model relations.

 class Backend\Behaviors\RelationController
extends Backend\Classes\ControllerBehavior

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

Class Description
ControllerBehavior

Controller Behavior base class

Traits

Trait Description
AssetMaker

Asset Maker Trait Adds asset based methods to a class

ConfigMaker

Config Maker Trait Adds configuration based methods to a class

ExtensionTrait

Extension trait

FormModelSaver

Implements special logic for processing form data, typically from from postback, and filling the model attributes and attributes of any related models. This is a customized, safer and simplified version of $model->push().

SessionMaker

Session Maker Trait

ViewMaker

View Maker Trait Adds view based methods to a class

WidgetMaker

Widget Maker Trait

Constants

Constant Description
PARAM_EXTRA_CONFIG
string "_relation_extra_config"

Postback parameter for read only mode.

PARAM_FIELD
string "_relation_field"

Postback parameter for the active relationship field.

PARAM_MODE
string "_relation_mode"

Postback parameter for the active management mode.

Properties

public $deferredBinding : bool

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

public $readOnly : bool

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

public $relationConfig : mixed

Configuration for this behaviour

public $relationModel : Model

Relationship model

public $relationName : string

Relationship name

public $relationObject : Model

Relationship object

public $relationType : string

Relationship type

public $sessionKey : string

Active session key, used for deferred bindings.

protected $actions : array

Visible actions in context of the controller

protected $alias : string

A unique alias to pass to widgets.

protected $eventTarget : string

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

protected $extraConfig : array

Config provided by the relationRender method

protected $field : Model

The relationship field as defined in the configuration.

protected $forceManageMode : string

Force a certain manage mode.

protected $forceViewMode : string

Force a certain view mode.

protected $foreignId : int

Foeign id of a selected pivot record.

protected $initialized : bool

Has the behavior been initialized.

protected $manageFilterWidget : Backend\Widgets\Filter

Reference to the manage filter widget.

protected $manageId : int

Primary id of an existing relation record.

protected $manageMode : string

Management of relation as list, form, or pivot.

protected $manageTitle : string

The title used for the manage popup.

protected $manageWidget : Backend\Classes\WidgetBase

Reference to the widget used for relation management.

protected $model : Model

The parent model of the relationship.

protected $originalConfig : array

Original configuration values

protected $pivotWidget : Backend\Classes\WidgetBase

Reference to widget for relations with pivot data.

protected $requiredConfig : array

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

protected $requiredRelationProperties : array

Properties that must exist for each relationship definition.

protected $searchWidget : Backend\Widgets\Search

Reference to the search widget object.

protected $toolbarButtons : array

The set of buttons to display in view mode.

protected $toolbarWidget : Backend\Widgets\Toolbar

Reference to the toolbar widget object.

protected $viewFilterWidget : Backend\Widgets\Filter

Reference to the view filter widget.

protected $viewMode : string

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

protected $viewModel : Model

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

protected $viewWidget : Backend\Classes\WidgetBase

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

inherited public $assetPath : string

Inherited from AssetMaker

Specifies a path to the asset directory.

inherited public static $extendableStaticCalledClass : string

Inherited from ExtensionTrait

The calling class when using a static method.

inherited public $layout : string

Inherited from ViewMaker

Layout to use for the view.

inherited public $suppressLayout : bool

Inherited from ViewMaker

Prevents the use of a layout.

inherited public $vars : array

Inherited from ViewMaker

A list of variables to pass to the page.

inherited protected $assets : array

Inherited from AssetMaker

Collection of assets to display in the layout.

inherited protected $config : array

Inherited from ControllerBehavior

Supplied configuration.

inherited protected $configPath : string

Inherited from ConfigMaker

Specifies a path to the config directory.

inherited protected $controller : Backend\Classes\Controller

Inherited from ControllerBehavior

Reference to the back end controller.

inherited protected static $extensionCallbacks : array

Inherited from ExtensionTrait

Used to extend the constructor of an extension class. Eg:

BehaviorClass::extend(function($obj) { })

inherited protected $extensionHidden : mixed

Inherited from ExtensionTrait

inherited protected $layoutPath : string

Inherited from ViewMaker

Specifies a path to the layout directory.

inherited protected $modelsToSave : array

Inherited from FormModelSaver

List of prepared models that require saving.

inherited protected $orderFactor : integer

Inherited from AssetMaker

Ensures "first-come, first-served" applies to assets of the same ordering.

inherited protected $requiredProperties : array

Inherited from ControllerBehavior

Properties that must exist in the controller using this behavior.

inherited protected $viewPath : string | array

Inherited from ViewMaker

Specifies a path to the views directory.

Methods

public __construct (Backend\Classes\Controller $controller)

Behavior constructor

Parameters
Property Description
$controller
Returns
mixed

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

Prepare the widgets used by this behavior

Parameters
Property Description
$model
$field
string
Returns
void

public onRelationButtonAdd ()

Returns
mixed

public onRelationButtonCreate ()

Returns
mixed

public onRelationButtonDelete ()

Returns
mixed

public onRelationButtonLink ()

Returns
mixed

public onRelationButtonRefresh ()

Returns
mixed

public onRelationButtonRemove ()

Returns
mixed

public onRelationButtonUnlink ()

Returns
mixed

public onRelationButtonUpdate ()

Returns
mixed

public onRelationClickManageList ()

Returns
mixed

public onRelationClickManageListPivot ()

Returns
mixed

public onRelationClickViewList ()

Returns
mixed

public onRelationManageAdd ()

Add an existing related model to the primary model

Returns
mixed

public onRelationManageAddPivot ()

Add multiple items using a single pivot form.

Returns
mixed

public onRelationManageCreate ()

Create a new related model

Returns
mixed

public onRelationManageDelete ()

Delete an existing related model completely

Returns
mixed

public onRelationManageForm ()

Returns
mixed

public onRelationManagePivotCreate ()

Returns
mixed

public onRelationManagePivotForm ()

Returns
mixed

public onRelationManagePivotUpdate ()

Returns
mixed

public onRelationManageRemove ()

Remove an existing related model from the primary model

Returns
mixed

public onRelationManageUpdate ()

Updated an existing related model's fields

Returns
mixed

public prepareVars () : void

Prepares the view data.

Returns
void

public relationExtendConfig (object $config, string $field, Winter\Storm\Database\Model $model)

Provides an opportunity to manipulate the field configuration.

Parameters
Property Description
$config
object
$field
string
$model
Returns
mixed

public relationExtendManageFilterWidget (Backend\Widgets\Filter $widget, string $field, Winter\Storm\Database\Model $model)

Provides an opportunity to manipulate the manage filter widget.

Parameters
Property Description
$widget
$field
string
$model
Returns
mixed

public relationExtendManageWidget (Backend\Classes\WidgetBase $widget, string $field, Winter\Storm\Database\Model $model)

Provides an opportunity to manipulate the manage widget.

Parameters
Returns
mixed

public relationExtendPivotWidget (Backend\Classes\WidgetBase $widget, string $field, Winter\Storm\Database\Model $model)

Provides an opportunity to manipulate the pivot widget.

Parameters
Returns
mixed

public relationExtendRefreshResults (string $field) : array

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
Property Description
$field
string
Returns
array

public relationExtendViewFilterWidget (Backend\Widgets\Filter $widget, string $field, Winter\Storm\Database\Model $model)

Provides an opportunity to manipulate the view filter widget.

Parameters
Property Description
$widget
$field
string
$model
Returns
mixed

public relationExtendViewWidget (Backend\Classes\WidgetBase $widget, string $field, Winter\Storm\Database\Model $model)

Provides an opportunity to manipulate the view widget.

Parameters
Returns
mixed

public relationGetId (string $suffix = null) : string

Returns a unique ID for this relation and field combination.

Parameters
Property Description
$suffix
string

A suffix to use with the identifier.

Returns
string

public relationGetManageWidget () : Backend\Classes\WidgetBase

Returns the manage widget used by this behavior.

Returns

public relationGetSessionKey (boolean $force = false)

Returns the active session key.

Parameters
Property Description
$force
boolean
Returns
mixed

public relationGetViewWidget () : Backend\Classes\WidgetBase

Returns the view widget used by this behavior.

Returns

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

Controller accessor for making partials within this behavior.

Parameters
Property Description
$partial
string
$params
array
Returns
string

Partial contents

public relationRefresh (string $field = null) : array

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

Parameters
Property Description
$field
string

Relation definition.

Returns
array

The relation element selector as the key, and the relation view contents are the value.

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

Renders the relationship manager.

Parameters
Property Description
$field
string

The relationship field.

$options
array
Returns
string

Rendered HTML for the relationship manager.

public relationRenderToolbar (string $field = null) : string

Renders the toolbar only.

Parameters
Property Description
$field
string

The relationship field.

Returns
string

Rendered HTML for the toolbar.

public relationRenderView (string $field = null) : string

Renders the view only.

Parameters
Property Description
$field
string

The relationship field.

Returns
string

Rendered HTML for the view.

protected applyExtraConfig ($config, $field = null)

Apply extra configuration

Parameters
Property Description
$config
mixed
$field
mixed
Returns
mixed

protected 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).

Returns
mixed

protected evalFormContext (string $mode = "manage", boolean $exists = false)

Determine supplied form context.

Parameters
Property Description
$mode
string
$exists
boolean
Returns
mixed

protected evalManageMode () : string

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

Returns
string

protected evalManageTitle () : string

Determine the management mode popup title.

Returns
string

protected evalToolbarButtons () : array | null

Determine the default buttons based on the model relationship type.

Returns
array | null

protected evalViewMode () : string

Determine the view mode based on the model relationship type.

Returns
string

protected findExistingRelationIds ($checkIds = null)

Returns the existing record IDs for the relation.

Parameters
Property Description
$checkIds
mixed
Returns
mixed

protected makeConfigForMode (string $mode = "view", string $type = "list", boolean $throwException = true)

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

Parameters
Property Description
$mode
string
$type
string
$throwException
boolean
Returns
mixed

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

Initialize a filter widget

Parameters
Property Description
$type
mixed

string Either 'manage' or 'view'

Returns

protected makeManageWidget ()

Returns
mixed

protected makePivotWidget ()

Returns
mixed

protected makeSearchWidget ()

Returns
mixed

protected makeToolbarWidget ()

Returns
mixed

protected makeViewWidget ()

Returns
mixed

protected validateField (string $field = null) : string

Validates the supplied field and initializes the relation manager.

Parameters
Property Description
$field
string

The relationship field.

Returns
string

The active field name.

inherited public addCss (string | array $name, array $attributes = []) : void

Inherited from AssetMaker

Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

Parameters
Property Description
$name
string | array

When an array of paths are provided they will be passed to the Asset Combiner

$attributes
array

When a string is provided it will be used as the 'build' attribute value

Returns
void

inherited public addJs (string | array $name, array $attributes = []) : void

Inherited from AssetMaker

Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

Parameters
Property Description
$name
string | array

When an array of paths are provided they will be passed to the Asset Combiner

$attributes
array

When a string is provided it will be used as the 'build' attribute value

Returns
void

inherited public addRss (string $name, array $attributes = []) : void

Inherited from AssetMaker

Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

Parameters
Property Description
$name
string
$attributes
array
Returns
void

inherited public addViewPath (string | array $path) : void

Inherited from ViewMaker

Prepends a path on the available view path locations.

Parameters
Property Description
$path
string | array
Returns
void

inherited public addVite (array | string $entrypoints, ?string $package = null) : void

Inherited from AssetMaker

Adds Vite tags

Parameters
Property Description
$entrypoints
array | string

The list of entry points for Vite

$package
?string

The package name of the plugin or theme

Returns
void

inherited public combineAssets (array $assets, string $localPath = "") : string

Inherited from AssetMaker

Run the provided assets through the Asset Combiner

Parameters
Property Description
$assets
array
$localPath
string
Returns
string

inherited public static extend (callable $callback)

Inherited from ExtensionBase
Parameters
Property Description
$callback
callable
Returns
mixed

inherited public extensionApplyInitCallbacks ()

Inherited from ExtensionTrait
Returns
mixed

inherited public static extensionExtendCallback (callable $callback) : void

Inherited from ExtensionTrait

Helper method for ::extend() static method

Parameters
Property Description
$callback
callable
Returns
void

inherited public extensionIsHiddenField ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited public extensionIsHiddenMethod ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited public flushAssets () : void

Inherited from AssetMaker

Disables the use, and subequent broadcast, of assets. This is useful to call during an AJAX request to speed things up. This method works by specifically targeting the hasAssetsDefined method.

Returns
void

inherited public getAssetPath (string $fileName, $assetPath = null) : string

Inherited from AssetMaker

Returns the URL to the provided asset. If the provided fileName is a relative path without a leading slash it will be assumbed to be relative to the asset path.

Parameters
Property Description
$fileName
string
$assetPath
mixed
Returns
string

inherited public getAssetPaths () : array

Inherited from AssetMaker

Returns an array of all registered asset paths.

Assets will be prioritized based on their defined ordering.

Returns
array

inherited public static getCalledExtensionClass ()

Inherited from ExtensionTrait
Returns
mixed

inherited public getConfig (string $name = null, mixed $default = null) : string

Inherited from ControllerBehavior

Safe accessor for configuration values.

Parameters
Property Description
$name
string

Config name, supports array names like "field[key]"

$default
mixed

Default value if nothing is found

Returns
string

inherited public getConfigPath (string $fileName, mixed $configPath = null) : string

Inherited from ConfigMaker

Locates a file based on it's definition. If the file starts with the ~ symbol it will be returned in context of the application base path, otherwise it will be returned in context of the config path.

Parameters
Property Description
$fileName
string

File to load.

$configPath
mixed

Explicitly define a config path.

Returns
string

Full path to the config file.

inherited public getViewPath (string $fileName, $viewPaths = null) : string

Inherited from ViewMaker

Locates a file based on its definition. The file name can be prefixed with a symbol (~|$) to return in context of the application or plugin base path, otherwise it will be returned in context of this object view path.

If the fileName cannot be found it will be returned unmodified.

Parameters
Property Description
$fileName
string
$viewPaths
mixed
Returns
string

inherited public getViewPaths () : array

Inherited from ViewMaker

Returns the active view path locations.

Returns
array

inherited public guessConfigPath (string $suffix = "") : string

Inherited from ConfigMaker

Guess the package path for the called class.

Parameters
Property Description
$suffix
string

An extra path to attach to the end

Returns
string

inherited public guessConfigPathFrom (string $class, string $suffix = "") : string

Inherited from ConfigMaker

Guess the package path from a specified class.

Parameters
Property Description
$class
string

Class to guess path from.

$suffix
string

An extra path to attach to the end

Returns
string

inherited public guessViewPath (string $suffix = "", boolean $isPublic = false) : string | null

Inherited from ViewMaker

Guess the package path for the called class.

Parameters
Property Description
$suffix
string

An extra path to attach to the end

$isPublic
boolean

Returns public path instead of an absolute one

Returns
string | null

inherited public guessViewPathFrom (string $class, string $suffix = "", boolean $isPublic = false) : string | null

Inherited from ViewMaker

Guess the package path from a specified class.

Parameters
Property Description
$class
string

Class to guess path from.

$suffix
string

An extra path to attach to the end

$isPublic
boolean

Returns public path instead of an absolute one

Returns
string | null

inherited public hasAssetsDefined () : bool

Inherited from AssetMaker

Returns true if assets any have been added.

Returns
bool

inherited public makeAssets ($type = null) : string | null

Inherited from AssetMaker

Outputs <link> and <script> tags to load assets previously added with addJs, addCss, & addRss method calls depending on the provided $type

Parameters
Property Description
$type
mixed
Returns
string | null

inherited public makeConfig (array $configFile = [], array $requiredConfig = []) : array | stdClass

Inherited from ConfigMaker

Reads the contents of the supplied file and applies it to this object.

Parameters
Property Description
$configFile
array
$requiredConfig
array
Returns
array | stdClass

inherited public makeConfigFromArray (array $configArray = []) : stdClass

Inherited from ConfigMaker

Makes a config object from an array, making the first level keys properties of a new object.

Parameters
Property Description
$configArray
array

Config array.

Returns
stdClass

The config object

inherited public makeFileContents (string $filePath, array $extraParams = []) : string

Inherited from ControllerBehavior

Makes all views in context of the controller, not the behavior.

Parameters
Property Description
$filePath
string

Absolute path to the view file.

$extraParams
array

Parameters that should be available to the view.

Returns
string

inherited public makeFormWidget (string $class, array $fieldConfig = [], array $widgetConfig = []) : Backend\Classes\FormWidgetBase

Inherited from WidgetMaker

Makes a form widget object with the supplied form field and widget configuration.

Parameters
Property Description
$class
string

Widget class name

$fieldConfig
array

A field name, an array of config or a FormField object.

$widgetConfig
array

An array of config.

Returns

The widget object

inherited public makeLayout ($name = null, array $params = [], boolean $throwException = true) : string | bool

Inherited from ViewMaker

Render a layout, defaulting to the layout propery specified on the class

Parameters
Property Description
$name
mixed
$params
array
$throwException
boolean
Returns
string | bool

The layout contents, or false.

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

Inherited from ViewMaker

Renders a layout partial

Parameters
Property Description
$partial
string
$params
array
Returns
string

inherited public makePartial (string $partial, array $params = [], boolean $throwException = true) : mixed

Inherited from ViewMaker

Render a partial file contents located in the views folder.

Parameters
Property Description
$partial
string
$params
array
$throwException
boolean
Returns
mixed

Partial contents or false if not throwing an exception.

inherited public makeView (string $view) : string

Inherited from ViewMaker

Loads the specified view. Applies the layout if one is set.

The view file must have the .php extension (or ".htm" for historical reasons) and be located in the views directory

Parameters
Property Description
$view
string
Returns
string

inherited public makeViewContent (string $contents, $layout = null) : string

Inherited from ViewMaker

Renders supplied contents inside a layout.

Parameters
Property Description
$contents
string
$layout
mixed
Returns
string

inherited public makeWidget (string $class, array $widgetConfig = []) : mixed | Backend\Classes\WidgetBase

Inherited from WidgetMaker

Makes a widget object with the supplied configuration file.

Parameters
Property Description
$class
string

Widget class name

$widgetConfig
array

An array of config.

Returns

The widget object

inherited public mergeConfig (mixed $configA, mixed $configB) : stdClass

Inherited from ConfigMaker

Merges two configuration sources, either prepared or not, and returns them as a single configuration object.

Parameters
Property Description
$configA
mixed
$configB
mixed
Returns
stdClass

The config object

inherited public orderAssets (array $assets) : array

Inherited from AssetMaker

Prioritize assets based on the given order.

Parameters
Property Description
$assets
array
Returns
array

inherited public resetSession () : void

Inherited from SessionMaker

Resets all session data related to this widget.

Returns
void

inherited public setConfig (mixed $config, array $required = [])

Inherited from ControllerBehavior

Sets the configuration values

Parameters
Property Description
$config
mixed

Config object or array

$required
array

Required config items

Returns
mixed

inherited protected addAsset (string $type, string $path, array $attributes) : void

Inherited from AssetMaker

Adds the provided asset to the internal asset collections

Parameters
Property Description
$type
string
$path
string
$attributes
array
Returns
void

inherited protected controllerMethodExists (string $methodName) : bool

Inherited from ControllerBehavior

Returns true in case if a specified method exists in the extended controller.

Parameters
Property Description
$methodName
string

Specifies the method name

Returns
bool

inherited protected deferPurgedSaveAttributes (Winter\Storm\Database\Model $model, array $attributesToPurge) : void

Inherited from FormModelSaver

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

Parameters
Property Description
$model

Model to adjust.

$attributesToPurge
array

Attribute values to remove from the model.

Returns
void

inherited protected extensionHideField ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited protected extensionHideMethod ($name)

Inherited from ExtensionTrait
Parameters
Property Description
$name
mixed
Returns
mixed

inherited protected getAssetEntryBuildPath (array $asset) : string

Inherited from AssetMaker

Internal helper, attaches a build code to an asset path

Parameters
Property Description
$asset
array
Returns
string

inherited protected getAssetScheme (string $asset) : string

Inherited from AssetMaker

Internal helper, get asset scheme

Parameters
Property Description
$asset
string
Returns
string

inherited protected getLocalPath (string | null $relativePath) : string

Inherited from AssetMaker
Parameters
Property Description
$relativePath
string | null
Returns
string

inherited protected getSession (string $key = null, string $default = null) : string

Inherited from SessionMaker

Retrieves a widget related key/value pair from session data.

Parameters
Property Description
$key
string

Unique key for the data store.

$default
string

A default value to use when value is not found.

Returns
string

inherited protected handleViewException (Throwable $e, integer $obLevel) : void

Inherited from ViewMaker

Handle a view exception.

Parameters
Property Description
$e
Throwable
$obLevel
integer
Returns
void

inherited protected hideAction (mixed $methodName)

Inherited from ControllerBehavior

Protects a public method from being available as an controller action.

These methods could be defined in a controller to override a behavior default action. Such methods should be defined as public, to allow the behavior object to access it. By default public methods of a controller are considered as actions. To prevent this occurrence, methods should be hidden by using this method.

Parameters
Property Description
$methodName
mixed

Specifies a method name.

Returns
mixed

inherited protected makeSessionId () : string

Inherited from SessionMaker

Returns a unique session identifier for this widget and controller action.

Returns
string

inherited protected prepareModelsToSave (Winter\Storm\Database\Model $model, array $saveData) : array

Inherited from FormModelSaver

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
Property Description
$model

Model to fill.

$saveData
array

Attribute values to fill model.

Returns
array

The collection of models to save.

inherited protected putSession (string $key, mixed $value) : void

Inherited from SessionMaker

Saves a widget related key/value pair in to session data.

Parameters
Property Description
$key
string

Unique key for the data store.

$value
mixed

The value to store.

Returns
void

inherited protected removeDuplicates () : void

Inherited from AssetMaker

Removes duplicate assets from the entire collection.

Returns
void

inherited protected setModelAttributes (Winter\Storm\Database\Model $model, array $saveData) : void

Inherited from FormModelSaver

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

Parameters
Property Description
$model

Model to fill.

$saveData
array

Attribute values to fill model.

Returns
void
Copyright © 2024 Winter CMS