Documentation

Form extends WidgetBase
in package
Uses FormModelSaver

Form Widget Used for building back end forms and renders a form.

Tags
author

Alexey Bobkov, Samuel Georges

Table of Contents

$alias  : string
$arrayName  : string
$assetPath  : string
$config  : object
$context  : string
$data  : array<string|int, mixed>
$fields  : array<string|int, mixed>
$implement  : array<string|int, mixed>
$isNested  : bool
$layout  : string
$model  : Model
$previewMode  : bool
$secondaryTabs  : array<string|int, mixed>
$sessionKey  : string
$suppressLayout  : bool
$tabs  : array<string|int, mixed>
$vars  : array<string|int, mixed>
$allFields  : array<string|int, mixed>
$allTabs  : object
$assets  : array<string|int, mixed>
$configPath  : string
$controller  : Controller
$defaultAlias  : string
$extendableCallbacks  : array<string|int, mixed>
$extendableGuardProperties  : bool
$extendableStaticMethods  : array<string|int, mixed>
$extensionData  : array<string|int, mixed>
$fatalError  : string
$fieldsDefined  : bool
$formWidgets  : array<string|int, mixed>
$layoutPath  : string
$modelsToSave  : array<string|int, mixed>
$viewPath  : string|array<string|int, mixed>
$widgetManager  : WidgetManager
__call()  : mixed
__callStatic()  : mixed
__construct()  : mixed
Constructor
__get()  : mixed
__set()  : mixed
addCss()  : void
Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
addDynamicMethod()  : mixed
Programmatically adds a method to the extendable class
addDynamicProperty()  : mixed
Programmatically adds a property to the extendable class
addFields()  : void
Programatically add fields, used internally and for extensibility.
addJs()  : void
Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
addRss()  : void
Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
addSecondaryTabFields()  : void
addTabFields()  : void
Add tab fields.
addViewPath()  : void
Prepends a path on the available view path locations.
asExtension()  : mixed
Short hand for `getClassExtension()` method, except takes the short extension name, example:
bindToController()  : void
Ensure fields are defined and form widgets are registered so they can also be bound to the controller this allows their AJAX features to operate.
clearExtendedClasses()  : void
Clear the list of extended classes so they will be re-extended.
combineAssets()  : string
Run the provided assets through the Asset Combiner
extend()  : mixed
extendableCall()  : mixed
Magic method for `__call()`
extendableCallStatic()  : mixed
Magic method for `__callStatic()`
extendableConstruct()  : mixed
This method should be called as part of the constructor.
extendableExtendCallback()  : void
Helper method for `::extend()` static method
extendableGet()  : string
Magic method for `__get()`
extendableSet()  : string
Magic method for `__set()`
extendClassWith()  : void
Dynamically extend a class with a specified behavior
fireSystemEvent()  : mixed
Fires a combination of local and global events. The first segment is removed from the event name locally and the local object is passed as the first argument to the event globally. Halting is also enabled by default.
fireViewEvent()  : string
Special event function used for extending within view files, allowing HTML to be injected multiple times.
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.
getAssetPath()  : string
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.
getAssetPaths()  : array<string|int, mixed>
Returns an array of all registered asset paths.
getClassExtension()  : mixed
Returns a behavior object from an extendable class, example:
getClassMethods()  : array<string|int, mixed>
Get a list of class methods, extension equivalent of get_class_methods()
getConfig()  : string
Safe accessor for configuration values.
getConfigPath()  : 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.
getContext()  : string
Returns the active context for displaying the form.
getController()  : mixed
Returns the controller using this widget.
getDynamicProperties()  : array<string|int, mixed>
Returns all dynamic properties and their values
getEventHandler()  : string
Returns a fully qualified event handler name for this widget.
getFatalError()  : string
getField()  : mixed
Get a specified field object
getFields()  : array<string|int, mixed>
Get all the registered fields for the instance.
getFormWidget()  : mixed
Get a specified form widget
getFormWidgets()  : array<string|int, mixed>
Get all the loaded form widgets for the instance.
getId()  : string
Returns a unique ID for this widget. Useful in creating HTML markup.
getSaveData()  : array<string|int, mixed>
Returns post data from a submitted form.
getSessionKey()  : Route|mixed|string
Returns the active session key.
getTab()  : mixed
Get a specified tab object.
getTabs()  : mixed
Get all tab objects for the instance.
getViewPath()  : 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.
getViewPaths()  : array<string|int, mixed>
Returns the active view path locations.
guessConfigPath()  : string
Guess the package path for the called class.
guessConfigPathFrom()  : string
Guess the package path from a specified class.
guessViewPath()  : string
Guess the package path for the called class.
guessViewPathFrom()  : string
Guess the package path from a specified class.
handleError()  : mixed
Sets standard page variables in the case of a controller error.
hasAssetsDefined()  : bool
Returns true if assets any have been added.
hasFatalError()  : bool
init()  : void
Initialize the widget, called by the constructor and free from its parameters.
isClassExtendedWith()  : bool
Check if extendable class is extended with a behavior object
makeAssets()  : string
Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls
makeConfig()  : array<string|int, mixed>|stdClass
Reads the contents of the supplied file and applies it to this object.
makeConfigFromArray()  : stdClass
Makes a config object from an array, making the first level keys properties of a new object.
makeFileContents()  : string
Includes a file path using output buffering.
makeFormWidget()  : FormWidgetBase
Makes a form widget object with the supplied form field and widget configuration.
makeLayout()  : mixed
Render a layout.
makeLayoutPartial()  : string
Renders a layout partial
makePartial()  : mixed
Render a partial file contents located in the views folder.
makeView()  : string
Loads a view with the name specified. Applies layout if its name is provided by the parent object.
makeViewContent()  : string
Renders supplied contents inside a layout.
makeWidget()  : mixed|WidgetBase
Makes a widget object with the supplied configuration file.
mergeConfig()  : stdClass
Merges two configuration sources, either prepared or not, and returns them as a single configuration object.
methodExists()  : bool
Checks if a method exists, extension equivalent of method_exists()
nameToId()  : string
Helper method to convert a field name to a valid ID attribute.
onLazyLoadTab()  : array<string|int, mixed>
Renders all fields of a tab in the target tab-pane.
onRefresh()  : array<string|int, mixed>
Event handler for refreshing the form.
propertyExists()  : bool
Checks if a property exists, extension equivalent of `property_exists()`
removeField()  : bool
Programatically remove a field.
removeTab()  : bool
Programatically remove all fields belonging to a tab.
render()  : string|bool
Renders the widget.
renderField()  : string|bool
Renders a single form field
renderFieldElement()  : string|bool
Renders the HTML element for a field
resetSession()  : void
Resets all session data related to this widget.
setFormValues()  : array<string|int, mixed>
Sets or resets form field values.
addAsset()  : mixed
Adds the provided asset to the internal asset collections
applyFiltersFromModel()  : mixed
dataArrayGet()  : array<string|int, mixed>|null
Variant to array_get() but preserves dots in key names.
dataArraySet()  : array<string|int, mixed>
Variant to array_set() but preserves dots in key names.
deferPurgedSaveAttributes()  : void
Removes an array of attributes from the model. If the model implements the Purgeable trait, this is preferred over the internal logic.
defineFormFields()  : void
Creates a flat array of form fields from the configuration.
extendableIsAccessible()  : bool
Checks if a property is accessible, property equivalent of `is_callable()`
extensionExtractMethods()  : void
Extracts the available methods from a behavior and adds it to the list of callable methods.
fillFromConfig()  : void
Transfers config values stored inside the $config property directly on to the root object properties. If no properties are defined all config will be transferred if it finds a matching property.
getAssetEntryBuildPath()  : string
Internal helper, attaches a build code to an asset path
getAssetScheme()  : string
Internal helper, get asset scheme
getFieldDepends()  : string
Returns a HTML encoded value containing the other fields this field depends on
getFieldName()  : array<string|int, mixed>
Parses a field's name
getFieldValue()  : string
Looks up the field value.
getLocalPath()  : mixed
getOptionsFromModel()  : mixed
Looks at the model for defined options.
getSession()  : string
Retrieves a widget related key/value pair from session data.
handleViewException()  : void
Handle a view exception.
isFormWidget()  : bool
Check if a field type is a widget or not
loadAssets()  : void
Adds widget specific asset files. Use $this->addJs() and $this->addCss() to register new assets to include on the page.
makeFormField()  : FormField
Creates a form field object from name and configuration.
makeFormFieldWidget()  : FormWidgetBase|null
Makes a widget object from a form field object.
makeSessionId()  : string
Returns a unique session identifier for this widget and controller action.
objectMethodExists()  : bool
Internal helper for method existence checks.
prepareModelsToSave()  : array<string|int, mixed>
Takes a model and fills it with data from a multidimensional array.
prepareVars()  : void
Prepares the form data
processAutoSpan()  : void
Converts fields with a span set to 'auto' as either 'left' or 'right' depending on the previous field.
putSession()  : void
Saves a widget related key/value pair in to session data.
removeDuplicates()  : void
Removes duplicate assets from the entire collection.
setModelAttributes()  : void
Sets a data collection to a model attributes, relations are also set.
shouldFetchDefaultValues()  : mixed
Checks if default values should be taken from data.
showFieldLabels()  : bool
Helper method to determine if field should be rendered with label and comments.
validateModel()  : mixed
Validate the supplied form model.

Properties

$alias

public string $alias

Defined alias used for this widget.

$arrayName

public string $arrayName

If the field element names should be contained in an array. Eg:

$assetPath

public string $assetPath

Specifies a path to the asset directory.

$config

public object $config

Supplied configuration.

$context

public string $context

The context of this form, fields that do not belong to this context will not be shown.

$data

public array<string|int, mixed> $data

Dataset containing field values, if none supplied, model is used.

$fields

public array<string|int, mixed> $fields

Form field configuration.

$implement

public array<string|int, mixed> $implement

Extensions implemented by this class.

$isNested

public bool $isNested = false

Used to flag that this form is being rendered as part of another form, a good indicator to expect that the form model and dataset values will differ.

$layout

public string $layout

Layout to use for the view.

$previewMode

public bool $previewMode = false

Render this form with uneditable preview data.

$secondaryTabs

public array<string|int, mixed> $secondaryTabs

Secondary tab configuration.

$sessionKey

public string $sessionKey

Active session key, used for editing forms and deferred bindings.

$suppressLayout

public bool $suppressLayout = false

Prevents the use of a layout.

$tabs

public array<string|int, mixed> $tabs

Primary tab configuration.

$vars

public array<string|int, mixed> $vars = []

A list of variables to pass to the page.

$allFields

protected array<string|int, mixed> $allFields = []

Collection of all fields used in this form.

Tags
see
FormField

$allTabs

protected object $allTabs = ['outside' => null, 'primary' => null, 'secondary' => null]

Collection of tab sections used in this form.

Tags
see
FormTabs

$assets

protected array<string|int, mixed> $assets = ['js' => [], 'css' => [], 'rss' => []]

Collection of assets to display in the layout.

$configPath

protected string $configPath

Specifies a path to the config directory.

$defaultAlias

protected string $defaultAlias = 'form'

A unique alias to identify this widget.

Tags
inheritDoc

$extendableCallbacks

protected static array<string|int, mixed> $extendableCallbacks = []

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

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

$extendableGuardProperties

protected static bool $extendableGuardProperties = true

Indicates if dynamic properties can be created.

$extendableStaticMethods

protected static array<string|int, mixed> $extendableStaticMethods = []

Collection of static methods used by behaviors.

$extensionData

protected array<string|int, mixed> $extensionData = ['extensions' => [], 'methods' => [], 'dynamicMethods' => [], 'dynamicProperties' => []]

Class reflection information, including behaviors.

$fatalError

protected string $fatalError

Object used for storing a fatal error.

$fieldsDefined

protected bool $fieldsDefined = false

Determines if field definitions have been created.

$formWidgets

protected array<string|int, mixed> $formWidgets = []

Collection of all form widgets used in this form.

$layoutPath

protected string $layoutPath

Specifies a path to the layout directory.

$modelsToSave

protected array<string|int, mixed> $modelsToSave = []

List of prepared models that require saving.

$viewPath

protected string|array<string|int, mixed> $viewPath

Specifies a path to the views directory.

Methods

__call()

public __call(mixed $name, mixed $params) : mixed
Parameters
$name : mixed
$params : mixed
Return values
mixed —

__callStatic()

public static __callStatic(mixed $name, mixed $params) : mixed
Parameters
$name : mixed
$params : mixed
Return values
mixed —

__construct()

Constructor

public __construct() : mixed
Return values
mixed —

__get()

public __get(mixed $name) : mixed
Parameters
$name : mixed
Return values
mixed —

__set()

public __set(mixed $name, mixed $value) : mixed
Parameters
$name : mixed
$value : mixed
Return values
mixed —

addCss()

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

public addCss(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
$name : string

Specifies a path (URL) to the script.

$attributes : array<string|int, mixed> = []

Adds extra HTML attributes to the asset link.

Return values
void —

addDynamicMethod()

Programmatically adds a method to the extendable class

public addDynamicMethod(string $dynamicName, callable $method[, string $extension = null ]) : mixed
Parameters
$dynamicName : string
$method : callable
$extension : string = null
Return values
mixed —

addDynamicProperty()

Programmatically adds a property to the extendable class

public addDynamicProperty(string $dynamicName[, string $value = null ]) : mixed
Parameters
$dynamicName : string
$value : string = null
Return values
mixed —

addFields()

Programatically add fields, used internally and for extensibility.

public addFields(array<string|int, mixed> $fields[, string $addToArea = null ]) : void
Parameters
$fields : array<string|int, mixed>
$addToArea : string = null
Return values
void —

addJs()

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

public addJs(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
$name : string

Specifies a path (URL) to the script.

$attributes : array<string|int, mixed> = []

Adds extra HTML attributes to the asset link.

Return values
void —

addRss()

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

public addRss(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
$name : string

Specifies a path (URL) to the RSS channel

$attributes : array<string|int, mixed> = []

Adds extra HTML attributes to the asset link.

Return values
void —

addSecondaryTabFields()

public addSecondaryTabFields(array<string|int, mixed> $fields) : void
Parameters
$fields : array<string|int, mixed>
Return values
void —

addTabFields()

Add tab fields.

public addTabFields(array<string|int, mixed> $fields) : void
Parameters
$fields : array<string|int, mixed>
Return values
void —

addViewPath()

Prepends a path on the available view path locations.

public addViewPath(string|array<string|int, mixed> $path) : void
Parameters
$path : string|array<string|int, mixed>
Return values
void —

asExtension()

Short hand for `getClassExtension()` method, except takes the short extension name, example:

public asExtension(string $shortName) : mixed

$this->asExtension('FormController')

Parameters
$shortName : string
Return values
mixed —

bindToController()

Ensure fields are defined and form widgets are registered so they can also be bound to the controller this allows their AJAX features to operate.

public bindToController() : void
Return values
void —

clearExtendedClasses()

Clear the list of extended classes so they will be re-extended.

public static clearExtendedClasses() : void
Return values
void —

combineAssets()

Run the provided assets through the Asset Combiner

public combineAssets(array<string|int, mixed> $assets[, string $localPath = '' ]) : string
Parameters
$assets : array<string|int, mixed>

Collection of assets

$localPath : string = ''

Prefix all assets with this path (optional)

Return values
string —

extend()

public static extend(callable $callback) : mixed
Parameters
$callback : callable
Return values
mixed —

extendableCall()

Magic method for `__call()`

public extendableCall(string $name[, array<string|int, mixed> $params = null ]) : mixed
Parameters
$name : string
$params : array<string|int, mixed> = null
Return values
mixed —

extendableCallStatic()

Magic method for `__callStatic()`

public static extendableCallStatic(string $name[, array<string|int, mixed> $params = null ]) : mixed
Parameters
$name : string
$params : array<string|int, mixed> = null
Return values
mixed —

extendableConstruct()

This method should be called as part of the constructor.

public extendableConstruct() : mixed
Return values
mixed —

extendableExtendCallback()

Helper method for `::extend()` static method

public static extendableExtendCallback(callable $callback) : void
Parameters
$callback : callable
Return values
void —

extendableGet()

Magic method for `__get()`

public extendableGet(string $name) : string
Parameters
$name : string
Return values
string —

extendableSet()

Magic method for `__set()`

public extendableSet(string $name, string $value) : string
Parameters
$name : string
$value : string
Return values
string —

extendClassWith()

Dynamically extend a class with a specified behavior

public extendClassWith(string $extensionName) : void
Parameters
$extensionName : string
Return values
void —

fireSystemEvent()

Fires a combination of local and global events. The first segment is removed from the event name locally and the local object is passed as the first argument to the event globally. Halting is also enabled by default.

public fireSystemEvent(string $event[, array<string|int, mixed> $params = [] ][, bool $halt = true ]) : mixed

For example:

$this->fireSystemEvent('backend.list.myEvent', ['my value']);

Is equivalent to:

$this->fireEvent('list.myEvent', ['myvalue'], true);

Event::fire('backend.list.myEvent', [$this, 'myvalue'], true);
Parameters
$event : string

Event name

$params : array<string|int, mixed> = []

Event parameters

$halt : bool = true

Halt after first non-null result

Return values
mixed —

fireViewEvent()

Special event function used for extending within view files, allowing HTML to be injected multiple times.

public fireViewEvent(string $event[, array<string|int, mixed> $params = [] ]) : string

For example:

fireViewEvent('backend.auth.extendSigninView') ?>
Parameters
$event : string

Event name

$params : array<string|int, mixed> = []

Event parameters

Return values
string —

flushAssets()

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.

public flushAssets() : void
Return values
void —

getAssetPath()

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.

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

File to load.

$assetPath : string = null

Explicitly define an asset path.

Return values
string —

Relative path to the asset file.

getAssetPaths()

Returns an array of all registered asset paths.

public getAssetPaths() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getClassExtension()

Returns a behavior object from an extendable class, example:

public getClassExtension(string $name) : mixed

$this->getClassExtension('Backend.Behaviors.FormController')

Parameters
$name : string

Fully qualified behavior name

Return values
mixed —

getClassMethods()

Get a list of class methods, extension equivalent of get_class_methods()

public getClassMethods() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getConfig()

Safe accessor for configuration values.

public getConfig(string $name[, string $default = null ]) : string
Parameters
$name : string

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

$default : string = null

Default value if nothing is found

Return values
string —

getConfigPath()

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.

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

File to load.

$configPath : mixed = null

Explicitly define a config path.

Return values
string —

Full path to the config file.

getContext()

Returns the active context for displaying the form.

public getContext() : string
Return values
string —

getController()

Returns the controller using this widget.

public getController() : mixed
Return values
mixed —

getDynamicProperties()

Returns all dynamic properties and their values

public getDynamicProperties() : array<string|int, mixed>
Return values
array<string|int, mixed> —

['property' => 'value']

getEventHandler()

Returns a fully qualified event handler name for this widget.

public getEventHandler(string $name) : string
Parameters
$name : string

The ajax event handler name.

Return values
string —

getFatalError()

public getFatalError() : string
Return values
string —

The fatal error message

getField()

Get a specified field object

public getField(string $field) : mixed
Parameters
$field : string
Return values
mixed —

getFields()

Get all the registered fields for the instance.

public getFields() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getFormWidget()

Get a specified form widget

public getFormWidget(string $field) : mixed
Parameters
$field : string
Return values
mixed —

getFormWidgets()

Get all the loaded form widgets for the instance.

public getFormWidgets() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getId()

Returns a unique ID for this widget. Useful in creating HTML markup.

public getId([string $suffix = null ]) : string
Parameters
$suffix : string = null

An extra string to append to the ID.

Return values
string —

A unique identifier.

getSaveData()

Returns post data from a submitted form.

public getSaveData() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getSessionKey()

Returns the active session key.

public getSessionKey() : Route|mixed|string
Return values
Route|mixed|string —

getTab()

Get a specified tab object.

public getTab(mixed $tab) : mixed

Options: outside, primary, secondary.

Parameters
$tab : mixed
Return values
mixed —

getTabs()

Get all tab objects for the instance.

public getTabs() : mixed
Return values
mixed —

getViewPath()

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.

public getViewPath(string $fileName[, mixed $viewPath = null ]) : string
Parameters
$fileName : string

File to load.

$viewPath : mixed = null

Explicitly define a view path.

Return values
string —

Full path to the view file.

getViewPaths()

Returns the active view path locations.

public getViewPaths() : array<string|int, mixed>
Return values
array<string|int, mixed> —

guessConfigPath()

Guess the package path for the called class.

public guessConfigPath([string $suffix = '' ]) : string
Parameters
$suffix : string = ''

An extra path to attach to the end

Return values
string —

guessConfigPathFrom()

Guess the package path from a specified class.

public guessConfigPathFrom(string $class[, string $suffix = '' ]) : string
Parameters
$class : string

Class to guess path from.

$suffix : string = ''

An extra path to attach to the end

Return values
string —

guessViewPath()

Guess the package path for the called class.

public guessViewPath([string $suffix = '' ][, bool $isPublic = false ]) : string
Parameters
$suffix : string = ''

An extra path to attach to the end

$isPublic : bool = false

Returns public path instead of an absolute one

Return values
string —

guessViewPathFrom()

Guess the package path from a specified class.

public guessViewPathFrom(string $class[, string $suffix = '' ][, bool $isPublic = false ]) : string
Parameters
$class : string

Class to guess path from.

$suffix : string = ''

An extra path to attach to the end

$isPublic : bool = false

Returns public path instead of an absolute one

Return values
string —

handleError()

Sets standard page variables in the case of a controller error.

public handleError(mixed $exception) : mixed
Parameters
$exception : mixed
Return values
mixed —

hasAssetsDefined()

Returns true if assets any have been added.

public hasAssetsDefined() : bool
Return values
bool —

hasFatalError()

public hasFatalError() : bool
Return values
bool —

Whether a fatal error has been set or not.

init()

Initialize the widget, called by the constructor and free from its parameters.

public init() : void
Tags
inheritDoc
Return values
void —

isClassExtendedWith()

Check if extendable class is extended with a behavior object

public isClassExtendedWith(string $name) : bool
Parameters
$name : string

Fully qualified behavior name

Return values
bool —

makeAssets()

Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls

public makeAssets([string $type = null ]) : string
Parameters
$type : string = null

Return an asset collection of a given type (css, rss, js) or null for all.

Return values
string —

makeConfig()

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

public makeConfig([array<string|int, mixed> $configFile = [] ][, array<string|int, mixed> $requiredConfig = [] ]) : array<string|int, mixed>|stdClass
Parameters
$configFile : array<string|int, mixed> = []
$requiredConfig : array<string|int, mixed> = []
Return values
array<string|int, mixed>|stdClass —

makeConfigFromArray()

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

public makeConfigFromArray([array<string|int, mixed> $configArray = [] ]) : stdClass
Parameters
$configArray : array<string|int, mixed> = []

Config array.

Return values
stdClass —

The config object

makeFileContents()

Includes a file path using output buffering.

public makeFileContents(string $filePath[, array<string|int, mixed> $extraParams = [] ]) : string

Ensures that vars are available.

Parameters
$filePath : string

Absolute path to the view file.

$extraParams : array<string|int, mixed> = []

Parameters that should be available to the view.

Return values
string —

makeFormWidget()

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

public makeFormWidget(string $class[, mixed $fieldConfig = [] ][, array<string|int, mixed> $widgetConfig = [] ]) : FormWidgetBase
Parameters
$class : string

Widget class name

$fieldConfig : mixed = []

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

$widgetConfig : array<string|int, mixed> = []

An array of config.

Return values
FormWidgetBase —

The widget object

makeLayout()

Render a layout.

public makeLayout([string $name = null ][, array<string|int, mixed> $params = [] ][, bool $throwException = true ]) : mixed
Parameters
$name : string = null

Specifies the layout name. If this parameter is omitted, the $layout property will be used.

$params : array<string|int, mixed> = []

Parameter variables to pass to the view.

$throwException : bool = true

Throw an exception if the layout is not found

Return values
mixed —

The layout contents, or false.

makeLayoutPartial()

Renders a layout partial

public makeLayoutPartial(string $partial[, array<string|int, mixed> $params = [] ]) : string
Parameters
$partial : string

The view to load.

$params : array<string|int, mixed> = []

Parameter variables to pass to the view.

Return values
string —

The layout partial contents

makePartial()

Render a partial file contents located in the views folder.

public makePartial(string $partial[, array<string|int, mixed> $params = [] ][, bool $throwException = true ]) : mixed
Parameters
$partial : string

The view to load.

$params : array<string|int, mixed> = []

Parameter variables to pass to the view.

$throwException : bool = true

Throw an exception if the partial is not found.

Return values
mixed —

Partial contents or false if not throwing an exception.

makeView()

Loads a view with the name specified. Applies layout if its name is provided by the parent object.

public makeView(string $view) : string

The view file must be situated in the views directory, and has the extension "htm".

Parameters
$view : string

Specifies the view name, without extension. Eg: "index".

Return values
string —

makeViewContent()

Renders supplied contents inside a layout.

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

The inner contents as a string.

$layout : string = null

Specifies the layout name.

Return values
string —

makeWidget()

Makes a widget object with the supplied configuration file.

public makeWidget(string $class[, array<string|int, mixed> $widgetConfig = [] ]) : mixed|WidgetBase
Parameters
$class : string

Widget class name

$widgetConfig : array<string|int, mixed> = []

An array of config.

Return values
mixed|WidgetBase —

The widget object

mergeConfig()

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

public mergeConfig(mixed $configA, mixed $configB) : stdClass
Parameters
$configA : mixed
$configB : mixed
Return values
stdClass —

The config object

methodExists()

Checks if a method exists, extension equivalent of method_exists()

public methodExists(string $name) : bool
Parameters
$name : string
Return values
bool —

nameToId()

Helper method to convert a field name to a valid ID attribute.

public nameToId( $input) : string
Parameters
$input :
Return values
string —

onLazyLoadTab()

Renders all fields of a tab in the target tab-pane.

public onLazyLoadTab() : array<string|int, mixed>
Return values
array<string|int, mixed> —

onRefresh()

Event handler for refreshing the form.

public onRefresh() : array<string|int, mixed>
Return values
array<string|int, mixed> —

propertyExists()

Checks if a property exists, extension equivalent of `property_exists()`

public propertyExists(string $name) : bool
Parameters
$name : string
Return values
bool —

removeField()

Programatically remove a field.

public removeField(string $name) : bool
Parameters
$name : string
Return values
bool —

removeTab()

Programatically remove all fields belonging to a tab.

public removeTab(string $name) : bool
Parameters
$name : string
Return values
bool —

render()

Renders the widget.

public render([array<string|int, mixed> $options = [] ]) : string|bool

Options:

  • preview: Render this form as an uneditable preview. Default: false
  • useContainer: Wrap the result in a container, used by AJAX. Default: true
  • section: Which form section to render. Default: null
    • outside: Renders the Outside Fields section.
    • primary: Renders the Primary Tabs section.
    • secondary: Renders the Secondary Tabs section.
    • null: Renders all sections
Parameters
$options : array<string|int, mixed> = []
Return values
string|bool —

The rendered partial contents, or false if suppressing an exception

renderField()

Renders a single form field

public renderField(string|array<string|int, mixed> $field[, array<string|int, mixed> $options = [] ]) : string|bool

Options:

  • useContainer: Wrap the result in a container, used by AJAX. Default: true
Parameters
$field : string|array<string|int, mixed>

The field name or definition

$options : array<string|int, mixed> = []
Return values
string|bool —

The rendered partial contents, or false if suppressing an exception

renderFieldElement()

Renders the HTML element for a field

public renderFieldElement(FormWidgetBase $field) : string|bool
Parameters
$field : FormWidgetBase
Return values
string|bool —

The rendered partial contents, or false if suppressing an exception

resetSession()

Resets all session data related to this widget.

public resetSession() : void
Return values
void —

setFormValues()

Sets or resets form field values.

public setFormValues([array<string|int, mixed> $data = null ]) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed> = null
Return values
array<string|int, mixed> —

addAsset()

Adds the provided asset to the internal asset collections

protected addAsset(string $type, string $path, array<string|int, mixed> $attributes) : mixed
Parameters
$type : string

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

$path : string

The path to the asset

$attributes : array<string|int, mixed>

The attributes for the asset

Return values
mixed —

applyFiltersFromModel()

protected applyFiltersFromModel() : mixed
Return values
mixed —

dataArrayGet()

Variant to array_get() but preserves dots in key names.

protected dataArrayGet(array<string|int, mixed> $array, array<string|int, mixed> $parts[, null $default = null ]) : array<string|int, mixed>|null
Parameters
$array : array<string|int, mixed>
$parts : array<string|int, mixed>
$default : null = null
Return values
array<string|int, mixed>|null —

dataArraySet()

Variant to array_set() but preserves dots in key names.

protected dataArraySet(array<string|int, mixed> &$array, array<string|int, mixed> $parts, string $value) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
$parts : array<string|int, mixed>
$value : string
Return values
array<string|int, mixed> —

deferPurgedSaveAttributes()

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

protected deferPurgedSaveAttributes(Model $model, array<string|int, mixed> $attributesToPurge) : void
Parameters
$model : Model

Model to adjust.

$attributesToPurge : array<string|int, mixed>

Attribute values to remove from the model.

Return values
void —

defineFormFields()

Creates a flat array of form fields from the configuration.

protected defineFormFields() : void

Also slots fields in to their respective tabs.

Return values
void —

extendableIsAccessible()

Checks if a property is accessible, property equivalent of `is_callable()`

protected extendableIsAccessible(mixed $class, string $propertyName) : bool
Parameters
$class : mixed
$propertyName : string
Return values
bool —

extensionExtractMethods()

Extracts the available methods from a behavior and adds it to the list of callable methods.

protected extensionExtractMethods(string $extensionName, object $extensionObject) : void
Parameters
$extensionName : string
$extensionObject : object
Return values
void —

fillFromConfig()

Transfers config values stored inside the $config property directly on to the root object properties. If no properties are defined all config will be transferred if it finds a matching property.

protected fillFromConfig([array<string|int, mixed> $properties = null ]) : void
Parameters
$properties : array<string|int, mixed> = null
Return values
void —

getAssetEntryBuildPath()

Internal helper, attaches a build code to an asset path

protected getAssetEntryBuildPath(array<string|int, mixed> $asset) : string
Parameters
$asset : array<string|int, mixed>

Stored asset array

Return values
string —

getAssetScheme()

Internal helper, get asset scheme

protected getAssetScheme(string $asset) : string
Parameters
$asset : string

Specifies a path (URL) to the asset.

Return values
string —

getFieldDepends()

Returns a HTML encoded value containing the other fields this field depends on

protected getFieldDepends(FormField $field) : string
Parameters
$field : FormField
Return values
string —

getFieldName()

Parses a field's name

protected getFieldName(string $field) : array<string|int, mixed>
Parameters
$field : string

Field name

Return values
array<string|int, mixed> —

[columnName, context]

getFieldValue()

Looks up the field value.

protected getFieldValue(mixed $field) : string
Parameters
$field : mixed
Return values
string —

getLocalPath()

protected getLocalPath(string $relativePath) : mixed
Parameters
$relativePath : string
Return values
mixed —

getOptionsFromModel()

Looks at the model for defined options.

protected getOptionsFromModel( $field,  $fieldOptions) : mixed
Parameters
$field :
$fieldOptions :
Return values
mixed —

getSession()

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

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

Unique key for the data store.

$default : string = null

A default value to use when value is not found.

Return values
string —

handleViewException()

Handle a view exception.

protected handleViewException(Exception $e, int $obLevel) : void
Parameters
$e : Exception
$obLevel : int
Return values
void —

isFormWidget()

Check if a field type is a widget or not

protected isFormWidget(string $fieldType) : bool
Parameters
$fieldType : string
Return values
bool —

loadAssets()

Adds widget specific asset files. Use $this->addJs() and $this->addCss() to register new assets to include on the page.

protected loadAssets() : void
Tags
inheritDoc
Return values
void —

makeFormField()

Creates a form field object from name and configuration.

protected makeFormField(string $name[, array<string|int, mixed> $config = [] ]) : FormField
Parameters
$name : string
$config : array<string|int, mixed> = []
Return values
FormField —

makeFormFieldWidget()

Makes a widget object from a form field object.

protected makeFormFieldWidget( $field) : FormWidgetBase|null
Parameters
$field :
Return values
FormWidgetBase|null —

makeSessionId()

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

protected makeSessionId() : string
Return values
string —

objectMethodExists()

Internal helper for method existence checks.

protected objectMethodExists(object $object, string $method) : bool
Parameters
$object : object
$method : string
Return values
bool —

prepareModelsToSave()

Takes a model and fills it with data from a multidimensional array.

protected prepareModelsToSave(Model $model, array<string|int, mixed> $saveData) : array<string|int, mixed>

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
$model : Model

Model to fill.

$saveData : array<string|int, mixed>

Attribute values to fill model.

Return values
array<string|int, mixed> —

The collection of models to save.

prepareVars()

Prepares the form data

protected prepareVars() : void
Return values
void —

processAutoSpan()

Converts fields with a span set to 'auto' as either 'left' or 'right' depending on the previous field.

protected processAutoSpan(mixed $fields) : void
Parameters
$fields : mixed
Return values
void —

putSession()

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

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

Unique key for the data store.

$value : string

The value to store.

Return values
void —

removeDuplicates()

Removes duplicate assets from the entire collection.

protected removeDuplicates() : void
Return values
void —

setModelAttributes()

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

protected setModelAttributes(Model $model, array<string|int, mixed> $saveData) : void
Parameters
$model : Model

Model to fill.

$saveData : array<string|int, mixed>

Attribute values to fill model.

Return values
void —

shouldFetchDefaultValues()

Checks if default values should be taken from data.

protected shouldFetchDefaultValues() : mixed

This should be done when model exists or when explicitly configured

Return values
mixed —

showFieldLabels()

Helper method to determine if field should be rendered with label and comments.

protected showFieldLabels(FormField $field) : bool
Parameters
$field : FormField
Return values
bool —

validateModel()

Validate the supplied form model.

protected validateModel() : mixed
Return values
mixed —

Search results