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 |
SessionMaker
|
Session Maker Trait |
ViewMaker
|
View Maker Trait Adds view based methods to a class |
WidgetMaker
|
Widget Maker Trait |
Constants
Constant | Type | Value | Description |
---|---|---|---|
PARAM_EXTRA_CONFIG
|
string |
"_relation_extra_config"
|
string
"_relation_extra_config"
Postback parameter for read only mode. |
PARAM_FIELD
|
string |
"_relation_field"
|
string
"_relation_field"
Postback parameter for the active relationship field. |
PARAM_MODE
|
string |
"_relation_mode"
|
string
"_relation_mode"
Postback parameter for the active management mode. |
Properties
public
$deferredBinding
:
bool
= false
Defers all binding actions using a session key when it is available.
public
$readOnly
:
bool
= false
Disables the ability to add, update, delete or create relations.
public
$relationConfig
:
mixed
= "config_relation.yaml"
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
= false
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
= ["label"]
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
Specifies a path to the asset directory.
inherited
public
static
$extendableStaticCalledClass
:
string
= null
The calling class when using a static method.
inherited public $layout : string
Layout to use for the view.
inherited
public
$suppressLayout
:
bool
= false
Prevents the use of a layout.
inherited
public
$vars
:
array
= []
A list of variables to pass to the page.
inherited
protected
$assets
:
array
= {"js":[],"css":[],"rss":[],"vite":[]}
Collection of assets to display in the layout.
inherited protected $config : array
Supplied configuration.
inherited protected $configPath : string
Specifies a path to the config directory.
inherited protected $controller : Backend\Classes\Controller
Reference to the back end controller.
inherited
protected
static
$extensionCallbacks
:
array
= []
Used to extend the constructor of an extension class. Eg:
BehaviorClass::extend(function($obj) { })
inherited
protected
$extensionHidden
:
mixed
= {"fields":[],"methods":["extensionIsHiddenField","extensionIsHiddenMethod"]}
inherited protected $layoutPath : string
Specifies a path to the layout directory.
inherited
protected
$modelsToSave
:
array
= []
List of prepared models that require saving.
inherited protected $orderFactor : integer
Ensures "first-come, first-served" applies to assets of the same ordering.
inherited
protected
$requiredProperties
:
array
= []
Properties that must exist in the controller using this behavior.
inherited protected $viewPath : string | array
Specifies a path to the views directory.
Methods
public __construct (Backend\Classes\Controller $controller)
Behavior constructor
Property | Type | Description |
---|---|---|
$controller | Backend\Classes\Controller |
public
initRelation (Model $model, string $field = null
)
: void
Prepare the widgets used by this behavior
public onRelationButtonAdd ()
public onRelationButtonCreate ()
public onRelationButtonDelete ()
public onRelationButtonLink ()
public onRelationButtonRefresh ()
public onRelationButtonRemove ()
public onRelationButtonUnlink ()
public onRelationButtonUpdate ()
public onRelationClickManageList ()
public onRelationClickManageListPivot ()
public onRelationClickViewList ()
public onRelationManageAdd ()
Add an existing related model to the primary model
public onRelationManageAddPivot ()
Add multiple items using a single pivot form.
public onRelationManageCreate ()
Create a new related model
public onRelationManageDelete ()
Delete an existing related model completely
public onRelationManageForm ()
public onRelationManagePivotCreate ()
public onRelationManagePivotForm ()
public onRelationManagePivotUpdate ()
public onRelationManageRemove ()
Remove an existing related model from the primary model
public onRelationManageUpdate ()
Updated an existing related model's fields
public prepareVars () : void
Prepares the view data.
public relationExtendConfig (object $config, string $field, Winter\Storm\Database\Model $model)
Provides an opportunity to manipulate the field configuration.
Property | Type | Description |
---|---|---|
$config | object |
object
|
$field | string |
string
|
$model | Winter\Storm\Database\Model |
public relationExtendManageFilterWidget (Backend\Widgets\Filter $widget, string $field, Winter\Storm\Database\Model $model)
Provides an opportunity to manipulate the manage filter widget.
Property | Type | Description |
---|---|---|
$widget | Backend\Widgets\Filter | |
$field | string |
string
|
$model | Winter\Storm\Database\Model |
public relationExtendManageWidget (Backend\Classes\WidgetBase $widget, string $field, Winter\Storm\Database\Model $model)
Provides an opportunity to manipulate the manage widget.
Property | Type | Description |
---|---|---|
$widget | Backend\Classes\WidgetBase | |
$field | string |
string
|
$model | Winter\Storm\Database\Model |
public relationExtendPivotWidget (Backend\Classes\WidgetBase $widget, string $field, Winter\Storm\Database\Model $model)
Provides an opportunity to manipulate the pivot widget.
Property | Type | Description |
---|---|---|
$widget | Backend\Classes\WidgetBase | |
$field | string |
string
|
$model | Winter\Storm\Database\Model |
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'];
Property | Type | Description |
---|---|---|
$field | string |
string
|
public relationExtendViewFilterWidget (Backend\Widgets\Filter $widget, string $field, Winter\Storm\Database\Model $model)
Provides an opportunity to manipulate the view filter widget.
Property | Type | Description |
---|---|---|
$widget | Backend\Widgets\Filter | |
$field | string |
string
|
$model | Winter\Storm\Database\Model |
public relationExtendViewWidget (Backend\Classes\WidgetBase $widget, string $field, Winter\Storm\Database\Model $model)
Provides an opportunity to manipulate the view widget.
Property | Type | Description |
---|---|---|
$widget | Backend\Classes\WidgetBase | |
$field | string |
string
|
$model | Winter\Storm\Database\Model |
public
relationGetId (string $suffix = null
)
: string
Returns a unique ID for this relation and field combination.
Property | Type | Description |
---|---|---|
$suffix | string |
string
A suffix to use with the identifier. |
public relationGetManageWidget () : Backend\Classes\WidgetBase
public
relationGetSessionKey (boolean $force = false
)
Returns the active session key.
Property | Type | Description |
---|---|---|
$force | boolean |
boolean
|
public relationGetViewWidget () : Backend\Classes\WidgetBase
public
relationMakePartial (string $partial, array $params = []
)
: string
Controller accessor for making partials within this behavior.
Property | Type | Description |
---|---|---|
$partial | string |
string
|
$params | array |
array
|
Partial contents
public
relationRefresh (string $field = null
)
: array
Refreshes the relation container only, useful for returning in custom AJAX requests.
Property | Type | Description |
---|---|---|
$field | string |
string
Relation definition. |
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.
Property | Type | Description |
---|---|---|
$field | string |
string
The relationship field. |
$options | array |
array
|
Rendered HTML for the relationship manager.
public
relationRenderToolbar (string $field = null
)
: string
Renders the toolbar only.
Property | Type | Description |
---|---|---|
$field | string |
string
The relationship field. |
Rendered HTML for the toolbar.
public
relationRenderView (string $field = null
)
: string
Renders the view only.
Property | Type | Description |
---|---|---|
$field | string |
string
The relationship field. |
Rendered HTML for the view.
protected
applyExtraConfig ($config, $field = null
)
Apply extra configuration
Property | Type | Description |
---|---|---|
$config | mixed |
mixed
|
$field | mixed |
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).
protected
evalFormContext (string $mode = "manage"
, boolean $exists = false
)
Determine supplied form context.
Property | Type | Description |
---|---|---|
$mode | string |
string
|
$exists | boolean |
boolean
|
protected evalManageMode () : string
Determine the management mode based on the relation type and settings.
protected evalManageTitle () : string
Determine the management mode popup title.
protected evalToolbarButtons () : array | null
Determine the default buttons based on the model relationship type.
protected evalViewMode () : string
Determine the view mode based on the model relationship type.
protected
findExistingRelationIds ($checkIds = null
)
Returns the existing record IDs for the relation.
Property | Type | Description |
---|---|---|
$checkIds | mixed |
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.
Property | Type | Description |
---|---|---|
$mode | string |
string
|
$type | string |
string
|
$throwException | boolean |
boolean
|
protected makeFilterWidget (mixed $type) : Backend\Classes\WidgetBase | null
Initialize a filter widget
Property | Type | Description |
---|---|---|
$type | mixed |
mixed
string Either 'manage' or 'view' |
protected makeManageWidget ()
protected makePivotWidget ()
protected makeSearchWidget ()
protected makeToolbarWidget ()
protected makeViewWidget ()
protected
validateField (string $field = null
)
: string
Validates the supplied field and initializes the relation manager.
Property | Type | Description |
---|---|---|
$field | string |
string
The relationship field. |
The active field name.
inherited
public
addCss (string | array $name, array $attributes = []
)
: void
Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
Property | Type | Description |
---|---|---|
$name | string | array |
string | array
When an array of paths are provided they will be passed to the Asset Combiner |
$attributes | array |
array
When a string is provided it will be used as the 'build' attribute value |
inherited
public
addJs (string | array $name, array $attributes = []
)
: void
Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
Property | Type | Description |
---|---|---|
$name | string | array |
string | array
When an array of paths are provided they will be passed to the Asset Combiner |
$attributes | array |
array
When a string is provided it will be used as the 'build' attribute value |
inherited
public
addRss (string $name, array $attributes = []
)
: void
Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
Property | Type | Description |
---|---|---|
$name | string |
string
|
$attributes | array |
array
|
inherited public addViewPath (string | array $path) : void
Prepends a path on the available view path locations.
Property | Type | Description |
---|---|---|
$path | string | array |
string | array
|
inherited
public
addVite (array | string $entrypoints, ?string $package = null
)
: void
Adds Vite tags
Property | Type | Description |
---|---|---|
$entrypoints | array | string |
array | string
The list of entry points for Vite |
$package | ?string |
?string
The package name of the plugin or theme |
inherited
public
combineAssets (array $assets, string $localPath = ""
)
: string
Run the provided assets through the Asset Combiner
Property | Type | Description |
---|---|---|
$assets | array |
array
|
$localPath | string |
string
|
inherited public static extend (callable $callback)
Property | Type | Description |
---|---|---|
$callback | callable |
callable
|
inherited public extensionApplyInitCallbacks ()
inherited public static extensionExtendCallback (callable $callback) : void
Helper method for ::extend()
static method
Property | Type | Description |
---|---|---|
$callback | callable |
callable
|
inherited public extensionIsHiddenField ($name)
Property | Type | Description |
---|---|---|
$name | mixed |
mixed
|
inherited public extensionIsHiddenMethod ($name)
Property | Type | Description |
---|---|---|
$name | mixed |
mixed
|
inherited public flushAssets () : void
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.
inherited
public
getAssetPath (string $fileName, $assetPath = null
)
: string
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.
Property | Type | Description |
---|---|---|
$fileName | string |
string
|
$assetPath | mixed |
mixed
|
inherited public getAssetPaths () : array
Returns an array of all registered asset paths.
Assets will be prioritized based on their defined ordering.
inherited public static getCalledExtensionClass ()
inherited
public
getConfig (string $name = null
, mixed $default = null
)
: string
Safe accessor for configuration values.
Property | Type | Description |
---|---|---|
$name | string |
string
Config name, supports array names like "field[key]" |
$default | mixed |
mixed
Default value if nothing is found |
inherited
public
getConfigPath (string $fileName, mixed $configPath = null
)
: string
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.
Property | Type | Description |
---|---|---|
$fileName | string |
string
File to load. |
$configPath | mixed |
mixed
Explicitly define a config path. |
Full path to the config file.
inherited
public
getViewPath (string $fileName, $viewPaths = null
)
: string
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.
Property | Type | Description |
---|---|---|
$fileName | string |
string
|
$viewPaths | mixed |
mixed
|
inherited public getViewPaths () : array
Returns the active view path locations.
inherited
public
guessConfigPath (string $suffix = ""
)
: string
Guess the package path for the called class.
Property | Type | Description |
---|---|---|
$suffix | string |
string
An extra path to attach to the end |
inherited
public
guessConfigPathFrom (string $class, string $suffix = ""
)
: string
Guess the package path from a specified class.
Property | Type | Description |
---|---|---|
$class | string |
string
Class to guess path from. |
$suffix | string |
string
An extra path to attach to the end |
inherited
public
guessViewPath (string $suffix = ""
, boolean $isPublic = false
)
: string | null
Guess the package path for the called class.
Property | Type | Description |
---|---|---|
$suffix | string |
string
An extra path to attach to the end |
$isPublic | boolean |
boolean
Returns public path instead of an absolute one |
inherited
public
guessViewPathFrom (string $class, string $suffix = ""
, boolean $isPublic = false
)
: string | null
Guess the package path from a specified class.
Property | Type | Description |
---|---|---|
$class | string |
string
Class to guess path from. |
$suffix | string |
string
An extra path to attach to the end |
$isPublic | boolean |
boolean
Returns public path instead of an absolute one |
inherited public hasAssetsDefined () : bool
Returns true if assets any have been added.
inherited
public
makeAssets ($type = null
)
: string | null
Outputs <link>
and <script>
tags to load assets previously added
with addJs, addCss, & addRss method calls depending on the provided $type
Property | Type | Description |
---|---|---|
$type | mixed |
mixed
|
inherited
public
makeConfig (array $configFile = []
, array $requiredConfig = []
)
: array | stdClass
Reads the contents of the supplied file and applies it to this object.
Property | Type | Description |
---|---|---|
$configFile | array |
array
|
$requiredConfig | array |
array
|
inherited
public
makeConfigFromArray (array $configArray = []
)
: stdClass
Makes a config object from an array, making the first level keys properties of a new object.
Property | Type | Description |
---|---|---|
$configArray | array |
array
Config array. |
The config object
inherited
public
makeFileContents (string $filePath, array $extraParams = []
)
: string
Makes all views in context of the controller, not the behavior.
Property | Type | Description |
---|---|---|
$filePath | string |
string
Absolute path to the view file. |
$extraParams | array |
array
Parameters that should be available to the view. |
inherited
public
makeFormWidget (string $class, array $fieldConfig = []
, array $widgetConfig = []
)
: Backend\Classes\FormWidgetBase
Makes a form widget object with the supplied form field and widget configuration.
Property | Type | Description |
---|---|---|
$class | string |
string
Widget class name |
$fieldConfig | array |
array
A field name, an array of config or a FormField object. |
$widgetConfig | array |
array
An array of config. |
The widget object
inherited
public
makeLayout ($name = null
, array $params = []
, boolean $throwException = true
)
: string | bool
Render a layout, defaulting to the layout propery specified on the class
Property | Type | Description |
---|---|---|
$name | mixed |
mixed
|
$params | array |
array
|
$throwException | boolean |
boolean
|
The layout contents, or false.
inherited
public
makeLayoutPartial (string $partial, array $params = []
)
: string
Renders a layout partial
Property | Type | Description |
---|---|---|
$partial | string |
string
|
$params | array |
array
|
inherited
public
makePartial (string $partial, array $params = []
, boolean $throwException = true
)
: mixed
Render a partial file contents located in the views folder.
Property | Type | Description |
---|---|---|
$partial | string |
string
|
$params | array |
array
|
$throwException | boolean |
boolean
|
Partial contents or false if not throwing an exception.
inherited public makeView (string $view) : string
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
Property | Type | Description |
---|---|---|
$view | string |
string
|
inherited
public
makeViewContent (string $contents, $layout = null
)
: string
Renders supplied contents inside a layout.
Property | Type | Description |
---|---|---|
$contents | string |
string
|
$layout | mixed |
mixed
|
inherited
public
makeWidget (string $class, array $widgetConfig = []
)
: mixed | Backend\Classes\WidgetBase
Makes a widget object with the supplied configuration file.
Property | Type | Description |
---|---|---|
$class | string |
string
Widget class name |
$widgetConfig | array |
array
An array of config. |
The widget object
inherited public mergeConfig (mixed $configA, mixed $configB) : stdClass
Merges two configuration sources, either prepared or not, and returns them as a single configuration object.
Property | Type | Description |
---|---|---|
$configA | mixed |
mixed
|
$configB | mixed |
mixed
|
The config object
inherited public orderAssets (array $assets) : array
Prioritize assets based on the given order.
Property | Type | Description |
---|---|---|
$assets | array |
array
|
inherited public resetSession () : void
Resets all session data related to this widget.
inherited
public
setConfig (mixed $config, array $required = []
)
Sets the configuration values
Property | Type | Description |
---|---|---|
$config | mixed |
mixed
Config object or array |
$required | array |
array
Required config items |
inherited protected addAsset (string $type, string $path, array $attributes) : void
Adds the provided asset to the internal asset collections
Property | Type | Description |
---|---|---|
$type | string |
string
|
$path | string |
string
|
$attributes | array |
array
|
inherited protected controllerMethodExists (string $methodName) : bool
Returns true in case if a specified method exists in the extended controller.
Property | Type | Description |
---|---|---|
$methodName | string |
string
Specifies the method name |
inherited protected deferPurgedSaveAttributes (Winter\Storm\Database\Model $model, array $attributesToPurge) : void
Removes an array of attributes from the model. If the model implements the Purgeable trait, this is preferred over the internal logic.
Property | Type | Description |
---|---|---|
$model | Winter\Storm\Database\Model |
Model to adjust. |
$attributesToPurge | array |
array
Attribute values to remove from the model. |
inherited protected extensionHideField ($name)
Property | Type | Description |
---|---|---|
$name | mixed |
mixed
|
inherited protected extensionHideMethod ($name)
Property | Type | Description |
---|---|---|
$name | mixed |
mixed
|
inherited protected getAssetEntryBuildPath (array $asset) : string
Internal helper, attaches a build code to an asset path
Property | Type | Description |
---|---|---|
$asset | array |
array
|
inherited protected getAssetScheme (string $asset) : string
Internal helper, get asset scheme
Property | Type | Description |
---|---|---|
$asset | string |
string
|
inherited protected getLocalPath (string | null $relativePath) : string
Property | Type | Description |
---|---|---|
$relativePath | string | null |
string | null
|
inherited
protected
getSession (string $key = null
, string $default = null
)
: string
Retrieves a widget related key/value pair from session data.
Property | Type | Description |
---|---|---|
$key | string |
string
Unique key for the data store. |
$default | string |
string
A default value to use when value is not found. |
inherited protected handleViewException (Throwable $e, integer $obLevel) : void
Handle a view exception.
Property | Type | Description |
---|---|---|
$e | Throwable |
Throwable
|
$obLevel | integer |
integer
|
inherited protected hideAction (mixed $methodName)
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.
Property | Type | Description |
---|---|---|
$methodName | mixed |
mixed
Specifies a method name. |
inherited protected makeSessionId () : string
Returns a unique session identifier for this widget and controller action.
inherited protected prepareModelsToSave (Winter\Storm\Database\Model $model, array $saveData) : array
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();
}
Property | Type | Description |
---|---|---|
$model | Winter\Storm\Database\Model |
Model to fill. |
$saveData | array |
array
Attribute values to fill model. |
The collection of models to save.
inherited protected putSession (string $key, mixed $value) : void
Saves a widget related key/value pair in to session data.
Property | Type | Description |
---|---|---|
$key | string |
string
Unique key for the data store. |
$value | mixed |
mixed
The value to store. |
inherited protected removeDuplicates () : void
Removes duplicate assets from the entire collection.
inherited protected setModelAttributes (Winter\Storm\Database\Model $model, array $saveData) : void
Sets a data collection to a model attributes, relations are also set.
Property | Type | Description |
---|---|---|
$model | Winter\Storm\Database\Model |
Model to fill. |
$saveData | array |
array
Attribute values to fill model. |