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.

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

public $assetPath : string

Inherited from ControllerBehavior

Specifies a path to the asset directory.

public static $extendableStaticCalledClass : string

Inherited from ControllerBehavior

The calling class when using a static method.

public $layout : string

Inherited from ControllerBehavior

Layout to use for the view.

public $suppressLayout : bool

Inherited from ControllerBehavior

Prevents the use of a layout.

public $vars : array

Inherited from ControllerBehavior

A list of variables to pass to the page.

protected $assets : array

Inherited from ControllerBehavior

Collection of assets to display in the layout.

protected $config : array

Inherited from ControllerBehavior

Supplied configuration.

protected $configPath : string

Inherited from ControllerBehavior

Specifies a path to the config directory.

protected $controller : Backend\Classes\Controller

Inherited from ControllerBehavior

Reference to the back end controller.

protected static $extensionCallbacks : array

Inherited from ControllerBehavior

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

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

protected $extensionHidden : mixed

Inherited from ControllerBehavior

protected $layoutPath : string

Inherited from ControllerBehavior

Specifies a path to the layout directory.

protected $modelsToSave : array

Inherited from FormModelSaver

List of prepared models that require saving.

protected $requiredProperties : array

Inherited from ControllerBehavior

Properties that must exist in the controller using this behavior.

protected $viewPath : string | array

Inherited from ControllerBehavior

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 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 ($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.

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

Inherited from ControllerBehavior

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

Parameters
Property Description
$name
array | string

Specifies a path (URL) or an array of paths to the stylesheet(s).

$attributes
array

Adds extra HTML attributes to the asset link.

Returns
void

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

Inherited from ControllerBehavior

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

Parameters
Property Description
$name
array | string

Specifies a path (URL) or an array of paths to the script(s).

$attributes
array

Adds extra HTML attributes to the asset link.

Returns
void

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

Inherited from ControllerBehavior

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

Parameters
Property Description
$name
string

Specifies a path (URL) to the RSS channel

$attributes
array

Adds extra HTML attributes to the asset link.

Returns
void

public addViewPath (string | array $path) : void

Inherited from ControllerBehavior

Prepends a path on the available view path locations.

Parameters
Property Description
$path
string | array
Returns
void

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

Inherited from ControllerBehavior

Run the provided assets through the Asset Combiner

Parameters
Property Description
$assets
array

Collection of assets

$localPath
string

Prefix all assets with this path (optional)

Returns
string

public static extend (callable $callback)

Inherited from ControllerBehavior
Parameters
Property Description
$callback
callable
Returns
mixed

public extensionApplyInitCallbacks ()

Inherited from ControllerBehavior
Returns
mixed

public static extensionExtendCallback (callable $callback) : void

Inherited from ControllerBehavior

Helper method for ::extend() static method

Parameters
Property Description
$callback
callable
Returns
void

public extensionIsHiddenField ($name)

Inherited from ControllerBehavior
Parameters
Property Description
$name
mixed
Returns
mixed

public extensionIsHiddenMethod ($name)

Inherited from ControllerBehavior
Parameters
Property Description
$name
mixed
Returns
mixed

public flushAssets () : void

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

Locates a file based on it's definition. If the file starts with a forward slash, it will be returned in context of the application public path, otherwise it will be returned in context of the asset path.

Parameters
Property Description
$fileName
string

File to load.

$assetPath
string

Explicitly define an asset path.

Returns
string

Relative path to the asset file.

public getAssetPaths () : array

Inherited from ControllerBehavior

Returns an array of all registered asset paths.

Returns
array

public static getCalledExtensionClass ()

Inherited from ControllerBehavior
Returns
mixed

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

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

Inherited from ControllerBehavior

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.

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

Inherited from ControllerBehavior

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

public getViewPaths () : array

Inherited from ControllerBehavior

Returns the active view path locations.

Returns
array

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

Inherited from ControllerBehavior

Guess the package path for the called class.

Parameters
Property Description
$suffix
string

An extra path to attach to the end

Returns
string

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

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

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

public hasAssetsDefined () : bool

Inherited from ControllerBehavior

Returns true if assets any have been added.

Returns
bool

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

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

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

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

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

Inherited from ControllerBehavior

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

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

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

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

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.

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

Inherited from ControllerBehavior

Renders a layout partial

Parameters
Property Description
$partial
string
$params
array
Returns
string

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

Inherited from ControllerBehavior

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.

public makeView (string $view) : string

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

Renders supplied contents inside a layout.

Parameters
Property Description
$contents
string
$layout
mixed
Returns
string

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

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

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

public resetSession () : void

Inherited from ControllerBehavior

Resets all session data related to this widget.

Returns
void

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

protected addAsset (string $type, string $path, array $attributes)

Inherited from ControllerBehavior

Adds the provided asset to the internal asset collections

Parameters
Property Description
$type
string

The type of the asset: 'js' || 'css' || 'rss'

$path
string

The path to the asset

$attributes
array

The attributes for the asset

Returns
mixed

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

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

protected extensionHideField ($name)

Inherited from ControllerBehavior
Parameters
Property Description
$name
mixed
Returns
mixed

protected extensionHideMethod ($name)

Inherited from ControllerBehavior
Parameters
Property Description
$name
mixed
Returns
mixed

protected getAssetEntryBuildPath (array $asset) : string

Inherited from ControllerBehavior

Internal helper, attaches a build code to an asset path

Parameters
Property Description
$asset
array

Stored asset array

Returns
string

protected getAssetScheme (string $asset) : string

Inherited from ControllerBehavior

Internal helper, get asset scheme

Parameters
Property Description
$asset
string

Specifies a path (URL) to the asset.

Returns
string

protected getLocalPath (string | null $relativePath)

Inherited from ControllerBehavior
Parameters
Property Description
$relativePath
string | null
Returns
mixed

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

Inherited from ControllerBehavior

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

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

Inherited from ControllerBehavior

Handle a view exception.

Parameters
Property Description
$e
Throwable
$obLevel
integer
Returns
void

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

protected makeSessionId () : string

Inherited from ControllerBehavior

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

Returns
string

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.

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

Inherited from ControllerBehavior

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

protected removeDuplicates () : void

Inherited from ControllerBehavior

Removes duplicate assets from the entire collection.

Returns
void

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