PHP Class Habari\FormControl

Show file Open project: habari/system

Public Properties

Property Type Description
$caption string
$container FormContainer The container that contains this control
$controls_js True if the controls.init script has been output, false if not
$errors array An array of errors that is filled when the control is passed for validation
$has_errors boolean True when this control has errors, can be true with $errors isn't when the errors propagate to the container
$helptext boolean | string This is help text for the control, if it is set
$initial_value mixed This is the intially assigned value of the control, set and used internally
$name string The name of the control for the purposes of manipulating it from the container object
$on_enable array An array of enable handlers for this control
$on_save array An array of save handlers for this control
$on_success array An array of success handlers for this control
$properties array Contains an array of properties used to assign to the output HTML
$settings array Contains an array of settings that control the behavior of this control
$storage habari\FormStorage | null The storage object for this form
$validators array An array of validators to execute on this control
$value mixed This is the value of the control, which will differ depending on at what time you access it
$value_set_manually boolean If the value of this control was set manually, this should be true
$vars array These vars are added internally to the theme for output by the template

Public Methods

Method Description
__construct ( string $name, habari\FormStorage | string | null $storage = 'null:null', array $properties = [], array $settings = [] ) Construct a control.
_extend ( ) This function is called after __construct(). It does nothing, but its descendants might do something.
add_class ( array | string $classes ) : FormControl Add one or more CSS classes to this control
add_input_array ( integer | string $value ) : FormControl Add a value to the input_array setting
add_template_class ( string $target, array | string $classes ) : FormControl Add one or more CSS classes to this control's template
add_validator ( mixed $validator, mixed $option = null ) : FormControl Add a validation function to this control Multiple parameters are passed as parameters to the validation function
clear ( ) Set this control to its initial value
control_id ( ) : string Obtain a unique identifier for this control that is the same every time the form is generated
control_type ( ) : string Get the type of control this is (without the "FormControl" and in lower case) Usually used for template selection
controls_js ( string $out ) : string Render the controls.init script prior to the supplied script only if it hasn't already been rendered
create ( string $name, habari\FormStorage | string | null $storage = 'null:null', array $properties = [], array $settings = [] ) : mixed | FormControl Create a new instance of this class and return it, use the fluent interface
do_success ( FormUI $form ) : boolean | string Calls the success callback for the form, and saves the form value to the control's storage location
error_wrap ( string $output, array $errors ) : string Wrap the output of a control (or some text content) with error content
from_args ( array $arglist ) : FormControl Take an array of parameters, use the first as the FormControl class/type, and run the constructor with the rest
get ( Theme $theme ) : string Produce the control for display
get_form ( ) : FormUI Find the form that holds this control
get_id ( boolean $force_set = true ) : string | null Produce a unique id (not name) for this control for use with labels and such, only if one is not provided in the control properties
get_id_component ( ) : boolean | string Get a string that will be used to generate a component of a control's HTML id
get_label ( ) : string Get a text label for this control
get_setting ( string $name, mixed $default = null ) : mixed Get the value of a setting
get_template ( ) : array Get a list of potential templates that can render this control
get_theme ( ) : Theme Retreive the Theme used to display this form component and its descendants
get_visualizer ( ) Returns the HTML id of the element that the control exposes as a target, for example, for labels
input_name ( ) : string Get the name to use for the input field
is_enabled ( ) : boolean Determine if this controls should be enabled
label ( string $label ) : FormControlLabel Shortcut to wrap this control in a label
load ( ) Load this control's initial data from the initialized storage location
on_save ( mixed $callback ) : FormControl Set a function to call on form submission success
on_success ( mixed $callback ) : FormControl Set a function to call on form submission success
pop_input_array ( ) : FormControl Remove the most recent input_array setting
pre_out ( ) : string Output this once when the control is first output to the page
prep_theme ( Theme $theme_obj ) : Theme
process ( ) Obtain the value of this control as supplied by the incoming $_POST values
remove_class ( array | string $classes ) : FormControl Remove one or more CSS classes from this control
remove_validator ( string $name ) Removes a validation function from this control
save ( ) Save this control's data to the initialized storage location
set_container ( FormContainer $container ) Set the container for this control
set_enable ( Callable $enabler ) : FormControl Set a function to use to determine if this control should be enabled or provided in the form
set_helptext ( string $helptext ) : FormControl
set_properties ( array $properties, boolean $override = false ) : FormControl Set the HTML-related properties of this control
set_property ( string $name, mixed $value ) : FormControl Set an HTML-related property of this control
set_setting ( string $name, mixed $value ) : FormControl Set the value of a single setting
set_settings ( array $settings, boolean $override = false ) : FormControl
set_storage ( habari\FormStorage | string | null $storage ) : FormControl Set the storage for this control
set_template ( string | array $template ) : FormControl Set a template for use with this control
set_template_html ( Callable | string $template ) : FormControl Set an HTML value directly for the output of a control
set_template_properties ( string $target, array $properties, boolean $override = false ) : FormControl Set the HTML-related properties of this control's template
set_value ( mixed $value, boolean $manually = true ) : FormControl Set the value of the control
validate ( ) : array Runs any attached validation functions to check validation of this control.
wrap_by ( Callable | string $wrapper, mixed $thing ) : string Process a thing either using an sprintf-style string, or a closure

Method Details

__construct() public method

Construct a control.
public __construct ( string $name, habari\FormStorage | string | null $storage = 'null:null', array $properties = [], array $settings = [] )
$name string The name of the control
$storage habari\FormStorage | string | null A storage location for the data collected by the control
$properties array An array of properties that apply to the output HTML
$settings array An array of settings that apply to this control object

_extend() public method

This function is called after __construct(). It does nothing, but its descendants might do something.
public _extend ( )

add_class() public method

Add one or more CSS classes to this control
public add_class ( array | string $classes ) : FormControl
$classes array | string An array or a string of classes to add to this control
return FormControl $this

add_input_array() public method

Add a value to the input_array setting
public add_input_array ( integer | string $value ) : FormControl
$value integer | string The value to use as the array part of the input name
return FormControl $this Fluent interface

add_template_class() public method

Add one or more CSS classes to this control's template
public add_template_class ( string $target, array | string $classes ) : FormControl
$target string The name of the targeted element in the control template
$classes array | string An array or a string of classes to add to this control's template
return FormControl $this

add_validator() public method

Add a validation function to this control Multiple parameters are passed as parameters to the validation function
public add_validator ( mixed $validator, mixed $option = null ) : FormControl
$validator mixed A callback function
$option mixed Multiple parameters added to those used to call the validator callback
return FormControl Returns the control for chained execution

clear() public method

Set this control to its initial value
public clear ( )

control_id() public method

Obtain a unique identifier for this control that is the same every time the form is generated
public control_id ( ) : string
return string

control_type() public method

Get the type of control this is (without the "FormControl" and in lower case) Usually used for template selection
public control_type ( ) : string
return string The type of the control in lower case

controls_js() public method

Render the controls.init script prior to the supplied script only if it hasn't already been rendered
public controls_js ( string $out ) : string
$out string An existing script that depends on controls.init
return string The script with the controls.init script prepended, if needed

create() public static method

Create a new instance of this class and return it, use the fluent interface
public static create ( string $name, habari\FormStorage | string | null $storage = 'null:null', array $properties = [], array $settings = [] ) : mixed | FormControl
$name string The name of the control
$storage habari\FormStorage | string | null A storage location for the data collected by the control
$properties array An array of properties that apply to the output HTML
$settings array An array of settings that apply to this control object
return mixed | FormControl An instance of the referenced FormControl with the supplied parameters

do_success() public method

Calls the success callback for the form, and saves the form value to the control's storage location
public do_success ( FormUI $form ) : boolean | string
$form FormUI The form this control belongs to
return boolean | string A string to replace the rendering of the form with, or false

error_wrap() public method

Wrap the output of a control (or some text content) with error content
public error_wrap ( string $output, array $errors ) : string
$output string The HTML to wrap
$errors array An array of error strings
return string The returned output

from_args() public static method

Take an array of parameters, use the first as the FormControl class/type, and run the constructor with the rest
public static from_args ( array $arglist ) : FormControl
$arglist array The array of arguments
return FormControl The created control.

get() public method

Produce the control for display
public get ( Theme $theme ) : string
$theme Theme The theme that will be used to render the template
return string The output of the template

get_form() public method

Find the form that holds this control
public get_form ( ) : FormUI
return FormUI The form that this control is in

get_id() public method

Produce a unique id (not name) for this control for use with labels and such, only if one is not provided in the control properties
public get_id ( boolean $force_set = true ) : string | null
$force_set boolean Default to true, forcing the id to be set to the name of the control if it's not set already
return string | null The id of this control, or null if it's not set and not forced

get_id_component() public method

Get a string that will be used to generate a component of a control's HTML id
public get_id_component ( ) : boolean | string
return boolean | string False if this component doesn't contribute to id creation, or the string component

get_label() public method

Get a text label for this control
public get_label ( ) : string
return string The label

get_setting() public method

Get the value of a setting
public get_setting ( string $name, mixed $default = null ) : mixed
$name string The name of the setting to get
$default mixed The default value to use if the setting is not set
return mixed The value fo the setting or the default supplied

get_template() public method

Get a list of potential templates that can render this control
public get_template ( ) : array
return array An array of template names in fallback order

get_theme() public method

Retreive the Theme used to display this form component and its descendants
public get_theme ( ) : Theme
return Theme The theme object to display the template for the control

get_visualizer() public method

Returns the HTML id of the element that the control exposes as a target, for example, for labels
public get_visualizer ( )

input_name() public method

Get the name to use for the input field
public input_name ( ) : string
return string The name to use in the HTML for this control

is_enabled() public method

Determine if this controls should be enabled
public is_enabled ( ) : boolean
return boolean True if enabled, false if not enabled

label() public method

Shortcut to wrap this control in a label
public label ( string $label ) : FormControlLabel
$label string The caption of the label
return FormControlLabel The label control is returned. FYI, THIS BREAKS THE FLUENT INTERFACE.

load() public method

Load this control's initial data from the initialized storage location
public load ( )

on_save() public method

Set a function to call on form submission success
public on_save ( mixed $callback ) : FormControl
$callback mixed A callback function or a plugin filter name.
return FormControl $this Fluent interface

on_success() public method

Set a function to call on form submission success
public on_success ( mixed $callback ) : FormControl
$callback mixed A callback function or a plugin filter name (FormUI $form)
return FormControl $this Fluent interface

pop_input_array() public method

Remove the most recent input_array setting
public pop_input_array ( ) : FormControl
return FormControl $this Fluent interface

pre_out() public method

Output this once when the control is first output to the page
public pre_out ( ) : string
return string

prep_theme() public method

public prep_theme ( Theme $theme_obj ) : Theme
$theme_obj Theme
return Theme

process() public method

Obtain the value of this control as supplied by the incoming $_POST values
public process ( )

remove_class() public method

Remove one or more CSS classes from this control
public remove_class ( array | string $classes ) : FormControl
$classes array | string An array or a string of classes to remove from this control
return FormControl $this

remove_validator() public method

Removes a validation function from this control
public remove_validator ( string $name )
$name string The name of the validator to remove

save() public method

Save this control's data to the initialized storage location
public save ( )

set_container() public method

Set the container for this control
public set_container ( FormContainer $container )
$container FormContainer A container that this control is inside

set_enable() public method

Set a function to use to determine if this control should be enabled or provided in the form
public set_enable ( Callable $enabler ) : FormControl
$enabler Callable A function to call to determine if this control should be enabled
return FormControl $this

set_helptext() public method

public set_helptext ( string $helptext ) : FormControl
$helptext string Help text to appear for the control
return FormControl $this

set_properties() public method

Set the HTML-related properties of this control
public set_properties ( array $properties, boolean $override = false ) : FormControl
$properties array An array of properties that will be associated to this control's HTML output
$override boolean If true, the supplied properties completely replace the existing ones
return FormControl $this

set_property() public method

Set an HTML-related property of this control
public set_property ( string $name, mixed $value ) : FormControl
$name string The name of the property to set
$value mixed The value to set the property to
return FormControl $this

set_setting() public method

Set the value of a single setting
public set_setting ( string $name, mixed $value ) : FormControl
$name string The name of the setting
$value mixed The value of the setting
return FormControl $this Fluent interface

set_settings() public method

public set_settings ( array $settings, boolean $override = false ) : FormControl
$settings array An array of settings that affect the behavior of this control object
$override boolean If true, use the provided array to override the existing one
return FormControl $this

set_storage() public method

Set the storage for this control
public set_storage ( habari\FormStorage | string | null $storage ) : FormControl
$storage habari\FormStorage | string | null A storage location for the data collected by the control
return FormControl $this

set_template() public method

Set a template for use with this control
public set_template ( string | array $template ) : FormControl
$template string | array A template fallback list to search for this template
return FormControl $this

set_template_html() public method

Set an HTML value directly for the output of a control
public set_template_html ( Callable | string $template ) : FormControl
$template Callable | string The template to use for output of this control
return FormControl $this

set_template_properties() public method

Set the HTML-related properties of this control's template
public set_template_properties ( string $target, array $properties, boolean $override = false ) : FormControl
$target string the target element in the template to apply the properties to
$properties array An array of properties that will be associated to this control template's HTML output
$override boolean If true, the supplied properties completely replace the existing ones
return FormControl $this

set_value() public method

Set the value of the control
public set_value ( mixed $value, boolean $manually = true ) : FormControl
$value mixed The initial value of the control
$manually boolean True if the value was set manually in code rather than being submitted
return FormControl $this

validate() public method

Runs any attached validation functions to check validation of this control.
public validate ( ) : array
return array An array of string validation error descriptions or an empty array if no errors were found.

wrap_by() public method

Process a thing either using an sprintf-style string, or a closure
public wrap_by ( Callable | string $wrapper, mixed $thing ) : string
$wrapper Callable | string An sprintf-style wrapper or a function that accepts the same arguments as the call to this
$thing mixed One or more things to use as parameters to the sprintf/closure
return string The resultant string produced by applying the closure or sprintf template

Property Details

$caption public property

public string $caption
return string

$container public property

The container that contains this control
public FormContainer,habari $container
return FormContainer

$controls_js static public property

True if the controls.init script has been output, false if not
static public $controls_js

$errors public property

An array of errors that is filled when the control is passed for validation
public array $errors
return array

$has_errors public property

True when this control has errors, can be true with $errors isn't when the errors propagate to the container
public bool $has_errors
return boolean

$helptext public property

This is help text for the control, if it is set
public bool|string $helptext
return boolean | string

$initial_value public property

This is the intially assigned value of the control, set and used internally
public mixed $initial_value
return mixed

$name public property

The name of the control for the purposes of manipulating it from the container object
public string $name
return string

$on_enable public property

An array of enable handlers for this control
public array $on_enable
return array

$on_save public property

An array of save handlers for this control
public array $on_save
return array

$on_success public property

An array of success handlers for this control
public array $on_success
return array

$properties public property

Contains an array of properties used to assign to the output HTML
public array $properties
return array

$settings public property

Contains an array of settings that control the behavior of this control
public array $settings
return array

$storage public property

The storage object for this form
public FormStorage,habari|null $storage
return habari\FormStorage | null

$validators public property

An array of validators to execute on this control
public array $validators
return array

$value public property

This is the value of the control, which will differ depending on at what time you access it
public mixed $value
return mixed

$value_set_manually public property

If the value of this control was set manually, this should be true
public bool $value_set_manually
return boolean

$vars public property

These vars are added internally to the theme for output by the template
public array $vars
return array