\BrickrougeAlert

A `<DIV.alert>` element.

The Element class can create any kind of HTML element. It supports class names, dataset, children. It handles values and default values. It can decorate the HTML element with a label, a legend and a description.

This is the base class to all element types.

Summary

Methods
Properties
Constants
auto_element_id()
__construct()
offsetExists()
offsetGet()
offsetSet()
offsetUnset()
getIterator()
add_class()
remove_class()
has_class()
adopt()
get_ordered_children()
render_inner_html()
render()
__toString()
validate()
t()
$type
$tag_name
$children
$class
$dataset
$id
$name
$attributes
$ordered_children
TYPE_CHECKBOX
TYPE_CHECKBOX_GROUP
TYPE_RADIO
TYPE_RADIO_GROUP
CHILDREN
DEFAULT_VALUE
DESCRIPTION
GROUP
GROUPS
INLINE_HELP
INNER_HTML
LABEL
LABEL_POSITION
LABEL_POSITION_BEFORE
LABEL_POSITION_AFTER
LABEL_POSITION_ABOVE
LABEL_MISSING
LEGEND
REQUIRED
OPTIONS
OPTIONS_DISABLED
STATE
STATE_DEFAULT
STATE_DANGER
STATE_SUCCESS
STATE_WARNING
TRANSLATOR
VALIDATOR
VALIDATOR_OPTIONS
WEIGHT
WEIGHT_BEFORE_PREFIX
WEIGHT_AFTER_PREFIX
IS
CONTEXT
CONTEXT_DANGER
CONTEXT_INFO
CONTEXT_SUCCESS
CONTEXT_WARNING
HEADING
DISMISSIBLE
handle_assets()
add_assets()
get_dataset()
set_dataset()
get_attributes()
lazy_get_id()
get_class()
set_class()
alter_class_names()
render_class()
render_child()
render_children()
render_inner_html_for_select()
render_inner_html_for_textarea()
render_inner_html_for_checkbox_group()
render_inner_html_for_radio_group()
alter_attributes()
render_attributes()
alter_dataset()
render_dataset()
render_outer_html()
decorate()
decorate_with_label()
decorate_with_legend()
decorate_with_inline_help()
decorate_with_description()
render_alert_dismiss()
render_alert_heading()
render_alert_message()
render_alert_content()
render_errors()
$auto_element_id
$inner_html
$class_names
$message
$alert_type
N/A
No private methods found
$inputs
$has_attribute_disabled
$has_attribute_value
$has_attribute_required
$handled_assets
$attributes
$_dataset
N/A

Constants

TYPE_CHECKBOX

TYPE_CHECKBOX

Custom type used to create checkbox elements.

TYPE_CHECKBOX_GROUP

TYPE_CHECKBOX_GROUP

Custom type used to create checkbox group elements.

TYPE_RADIO

TYPE_RADIO

Custom type used to create radio elements.

TYPE_RADIO_GROUP

TYPE_RADIO_GROUP

Custom type used to create radio group elements.

CHILDREN

CHILDREN

Defines the children of an element.

DEFAULT_VALUE

DEFAULT_VALUE

Defines the default value of an element.

The default value is added to the dataset as 'default-value'.

DESCRIPTION

DESCRIPTION

Defines the description block of an element.

GROUP

GROUP

Defines the group of an element.

GROUPS

GROUPS

Defines the groups that can be used by children elements.

INLINE_HELP

INLINE_HELP

Defines the inline help of an element.

INNER_HTML

INNER_HTML

Defines the inner HTML of an element. If the value of the tag is null, the markup will be self-closing.

LABEL

LABEL

Defines the label of an element.

LABEL_POSITION

LABEL_POSITION

Defines the position of the label. Defaults to {@link LABEL_POSITION_AFTER}.

LABEL_POSITION_BEFORE

LABEL_POSITION_BEFORE

LABEL_POSITION_AFTER

LABEL_POSITION_AFTER

LABEL_POSITION_ABOVE

LABEL_POSITION_ABOVE

LABEL_MISSING

LABEL_MISSING

Defines the label to use to format validation message.

LEGEND

LEGEND

Defines the legend of an element. If the legend is defined the element is wrapped into a fieldset when it is rendered.

REQUIRED

REQUIRED

Defines the required state of an element.

OPTIONS

OPTIONS

Defines the options of the following element types: "select", {@link TYPE_RADIO_GROUP} and {@link TYPE_CHECKBOX_GROUP}.

OPTIONS_DISABLED

OPTIONS_DISABLED

Defines which options are disabled.

STATE

STATE

Defines the state of the element.

STATE_DEFAULT

STATE_DEFAULT

STATE_DANGER

STATE_DANGER

STATE_SUCCESS

STATE_SUCCESS

STATE_WARNING

STATE_WARNING

TRANSLATOR

TRANSLATOR

Defines the translator used to translate strings.

VALIDATOR

VALIDATOR

Defines the validator of an element. The validator is defined using an array made of a callback and a possible userdata array.

VALIDATOR_OPTIONS

VALIDATOR_OPTIONS

WEIGHT

WEIGHT

Defines the weight of an element. This attribute can be used to reorder children when a parent element is rendered.

WEIGHT_BEFORE_PREFIX

WEIGHT_BEFORE_PREFIX

WEIGHT_AFTER_PREFIX

WEIGHT_AFTER_PREFIX

IS

IS

Defines the factory name for the widget.

CONTEXT

CONTEXT

The context of the alert, one of "error", "success" or "info".

CONTEXT_DANGER

CONTEXT_DANGER

CONTEXT_INFO

CONTEXT_INFO

CONTEXT_SUCCESS

CONTEXT_SUCCESS

CONTEXT_WARNING

CONTEXT_WARNING

HEADING

HEADING

The heading of the alert.

DISMISSIBLE

DISMISSIBLE

Set to `true` for dismissible alerts.

Properties

$type

$type : string

Type if the element, as provided during {@link __construct()}.

Type

string

$tag_name

$tag_name : string

Tag name of the rendered HTML element.

Type

string

$children

$children : array

An array containing the children of the element.

Type

array

$class

$class : string

Assigns a class name or set of class names to an element. Any number of elements may be assigned the same class name or names. Multiple class names must be separated by white space characters.

Type

string

$dataset

$dataset : \Brickrouge\Dataset

The dataset property provides a convenient mapping to the data-* attributes on an element.

Type

\Brickrouge\Dataset

$id

$id : string

Assigns an identifier to an element. This identifier mush be unique in a document.

Type

string

$name

$name : string

Assigned by {@link Form} during validation.

Type

string

$attributes

$attributes : array

Element's attributes.

Type

array

$ordered_children

$ordered_children : array

Children ordered according to their {@link WEIGHT}.

Type

array

$auto_element_id

$auto_element_id : integer

Next available auto element id index.

Type

integer

$inner_html

$inner_html : string|null

Inner HTML of the element.

Type

string|null

$class_names

$class_names : array

Class names used to compose the value of the `class` attribute.

Type

array

$message

$message : 

Alert message.

Type

$alert_type

$alert_type : 

Alert type, one of "error", "success" or "info".

Type

$inputs

$inputs : 

Type

$has_attribute_disabled

$has_attribute_disabled : 

Type

$has_attribute_value

$has_attribute_value : 

Type

$has_attribute_required

$has_attribute_required : 

Type

$handled_assets

$handled_assets : 

Type

$attributes

$attributes : \Brickrouge\array[string]mixed

Attributes of the element, including HTML and special attributes.

Type

\Brickrouge\array[string]mixed

$_dataset

$_dataset : 

Type

Methods

auto_element_id()

auto_element_id() : string

Returns a unique element id string.

Returns

string

__construct()

__construct(string|array|\Brickrouge\Validate\Errors  $message, array  $attributes = array()) 

Creates a `<DIV.alert>` element.

Parameters

string|array|\Brickrouge\Validate\Errors $message

The alert message is provided as a string, an array of strings or a {@link Errors} object.

If the message is provided as a string it is used as is. If the message is provided as an array each value of the array is considered as a message. If the message is provided as an {@link Errors} object each entry of the object is considered as a message.

Each message is wrapped in a <P> element and they are concatenated to create the final message.

If the message is an instance of {@link Errors} the {@link CONTEXT} attribute is set to "error" in the initial attributes.

array $attributes

Additional attributes.

offsetExists()

offsetExists(string  $attribute) : boolean

Checks is an attribute is set.

Parameters

string $attribute

Returns

boolean

offsetGet()

offsetGet(string  $attribute, mixed|null  $default = null) : mixed

Returns the value of an attribute.

Parameters

string $attribute
mixed|null $default

The default value of the attribute.

Returns

mixed —

The value of the attribute, or null if is not set.

offsetSet()

offsetSet(string  $attribute, mixed  $value) 

Sets the value of an attribute.

Parameters

string $attribute

The attribute.

mixed $value

The value of the attribute.

offsetUnset()

offsetUnset(string  $attribute) 

Removes an attribute.

Parameters

string $attribute

The name of the attribute.

getIterator()

getIterator() : \Brickrouge\Iterator

Returns an iterator.

Returns

\Brickrouge\Iterator

add_class()

add_class(  $class) : \Brickrouge\Element

Adds a class name to the "class" attribute.

Parameters

$class

Returns

\Brickrouge\Element

remove_class()

remove_class(  $class) : \Brickrouge\Element

Removes a class name from the `class` attribute.

Parameters

$class

Returns

\Brickrouge\Element

has_class()

has_class(string  $class_name) : boolean

Checks if a class name is defined in the `class` attribute.

Parameters

string $class_name

Returns

boolean —

true if the element has the class name, false otherwise.

adopt()

adopt(string|\Brickrouge\Element|array  $child) 

Add a child or children to the element.

If the children are provided in an array, each key/value pair defines the name of a child and the child itself. If the key is not numeric it is considered as the child's name and is used to set its name attribute, unless the attribute is already defined.

Parameters

string|\Brickrouge\Element|array $child

The child or children to add.

get_ordered_children()

get_ordered_children() : array

Returns the children of the element ordered according to their weight.

Returns

array

render_inner_html()

render_inner_html() : string|null

Returns the HTML representation of the element's content.

The children of the element are ordered before they are rendered using the \render_children() method.

According to their types, the following methods can be invoked to render the inner HTML of elements:

  • \render_inner_html_for_select
  • \render_inner_html_for_textarea
  • \render_inner_html_for_checkbox_group
  • \render_inner_html_for_radio_group

Throws

\Brickrouge\ElementIsEmpty

if the message is empty.

Returns

string|null —

The content of the element. The element is to be considered self-closing if null is returned.

render()

render() : string

Renders the element into an HTML string.

Before the element is rendered the method \handle_assets() is invoked.

The inner HTML is rendered by the \render_inner_html() method. The outer HTML is rendered by the \render_outer_html() method. Finally, the HTML is decorated by the \decorate() method.

If the \ElementIsEmpty exception is caught during the rendering an empty string is returned.

Returns

string —

The HTML representation of the object

__toString()

__toString() : string

Renders the element into an HTML string.

The method \render() is invoked to render the element.

If an exception is thrown during the rendering it is rendered using the \render_exception() function and returned.

Returns

string —

The HTML representation of the object

validate()

validate(  $value, \ICanBoogie\Errors  $errors) : boolean

Validates the specified value.

This function uses the validator defined using the \VALIDATOR special attribute to validate its value.

Parameters

$value
\ICanBoogie\Errors $errors

Returns

boolean —

true if the validation succeed, false otherwise.

t()

t(string  $pattern, array  $args = array(), array  $options = array()) : string

Translates and formats a string.

The method uses the translator specified by \TRANSLATOR or the \t() function if it is not specified.

Parameters

string $pattern

The native string to translate.

array $args

An array of replacements to make after the translation. The replacement is handled by the {@link format()} function.

array $options

An array of additional options, with the following elements:

  • 'default': The default string to use if the translation failed.
  • 'scope': The scope of the translation.

Returns

string

handle_assets()

handle_assets() 

add_assets()

add_assets(\Brickrouge\Document  $document) 

Adds assets to the document.

Parameters

\Brickrouge\Document $document

get_dataset()

get_dataset() : \Brickrouge\Dataset

Returns the {@link Dataset} of the element.

Returns

\Brickrouge\Dataset

set_dataset()

set_dataset(  $dataset) : \Brickrouge\Dataset

Sets the dataset of the element.

Parameters

$dataset

Returns

\Brickrouge\Dataset

get_attributes()

get_attributes() : array

Returns the attributes of the element.

Returns

array

lazy_get_id()

lazy_get_id() : string

Returns the element's id.

If the element's id is empty, a unique id is generated and added to its attributes.

Returns

string

get_class()

get_class() : string

Returns the value of the "class" attribute.

Returns

string

set_class()

set_class(string  $class) 

Sets the value of the "class" attribute.

Parameters

string $class

alter_class_names()

alter_class_names(array  $class_names) : array

Adds the `alert-error`, `alert-info` and `alert-success` class names according to the {@link CONTEXT} attribute.

Adds the alert-block class name if the \HEADING attribute is defined.

Adds the alert-dismissible class name if the \DISMISSIBLE attribute is true.

Parameters

array $class_names

Returns

array

render_class()

render_class(array  $class_names) : string

Renders the `class` attribute value.

Parameters

array $class_names

An array of class names. Each key/value pair describe a class name. The key is the identifier of the class name, the value is its value. If the value is empty then the class name is discarded. If the value is true the identifier of the class name is used as value.

Returns

string

render_child()

render_child(\Brickrouge\Element|string  $child) : string

Returns the HTML representation of a child element.

Parameters

\Brickrouge\Element|string $child

Returns

string

render_children()

render_children(array  $children) : string

Renders the children of the element into a HTML string.

Parameters

array $children

Returns

string

render_inner_html_for_select()

render_inner_html_for_select() : string

Renders inner HTML of `SELECT` elements.

Returns

string

render_inner_html_for_textarea()

render_inner_html_for_textarea() : string

Renders the inner HTML of `TEXTAREA` elements.

Returns

string

render_inner_html_for_checkbox_group()

render_inner_html_for_checkbox_group() : string

Renders inner HTML of {@link TYPE_CHECKBOX_GROUP} custom elements.

Returns

string

render_inner_html_for_radio_group()

render_inner_html_for_radio_group() : string

Renders inner HTML of {@link TYPE_RADIO_GROUP} custom elements.

Returns

string

alter_attributes()

alter_attributes(array  $attributes) : array

Alters the provided attributes.

  • The value, required, disabled and name attributes are discarded if they are not supported by the element type.

  • The title attribute is translated within the scope element.title.

  • The checked attribute of elements of type \TYPE_CHECKBOX is set to true if their \DEFAULT_VALUE attribute is not empty and their checked attribute is not defined (null).

  • The value attribute of INPUT and BUTTON elements is altered if the \DEFAULT_VALUE attribute is defined and the value attribute is not (null).

Parameters

array $attributes

Returns

array —

The altered attributes.

render_attributes()

render_attributes(array  $attributes) : string

Renders attributes.

Attributes with false or null values as well as custom attributes are discarded. Attributes with the true value are translated to XHTML standard e.g. readonly="readonly".

Parameters

array $attributes

Throws

\InvalidArgumentException

if the value is an array or an object that doesn't implement the toString() method.

Returns

string

alter_dataset()

alter_dataset(array  $dataset) : array

Alters the dataset.

The method is invoked before the dataset is rendered.

The method might add the default-value and \IS_ATTRIBUTE keys.

Parameters

array $dataset

Returns

array

render_dataset()

render_dataset(array  $dataset) : string

Renders dataset.

The dataset is rendered as a series of "data-*" attributes. Values of type array are encoded using the \json_encode() function. Attributes with null values are discarded, but unlike classic attributes boolean values are converted to integers.

Parameters

array $dataset

Returns

string

render_outer_html()

render_outer_html() : string

Returns the HTML representation of the element and its contents.

The attributes are filtered before they are rendered. The attributes with a false or null value are discarded as well as custom attributes, attributes that start with the has sign "#". The dataset properties—attributes starting with "data-*"—are extracted to be handled separately.

The \alter_attributes() method is invoked to alter the attributes and the \render_attributes() method is invoked to render them.

The \alter_dataset() method is invoked to alter the dataset and the \render_dataset() method is invoked to render them.

If the inner HTML is null the element is self-closing.

Note: The inner HTML is rendered before the outer HTML.

Returns

string

decorate()

decorate(string  $html) : string

Decorates the specified HTML.

The HTML can be decorated by following attributes:

  • A label defined by the \LABEL special attribute. The \decorate_with_label() method is used to decorate the HTML with the label.

  • An inline help defined by the \INLINE_HELP special attribute. The \decorate_with_inline_help() method is used to decorate the HTML with the inline help.

  • A description (or help block) defined by the \DESCRIPTION special attribute. The \decorate_with_description() method is used to decorate the HTML with the description.

  • A legend defined by the \LEGEND special attribute. The \decorate_with_label() method is used to decorate the HTML with the legend.

Parameters

string $html

The HTML to decorate.

Returns

string —

The decorated HTML.

decorate_with_label()

decorate_with_label(string  $html, string  $label) : string

Decorates the specified HTML with specified label.

The position of the label is defined using the \T_LABEL_POSITION tag

Parameters

string $html
string $label

The label as defined by the {@link T_LABEL} tag.

Returns

string

decorate_with_legend()

decorate_with_legend(string  $html, string  $legend) : string

Decorates the specified HTML with a fieldset and the specified legend.

Parameters

string $html
string $legend

Returns

string

decorate_with_inline_help()

decorate_with_inline_help(string  $html, string  $help) : string

Decorates the specified HTML with an inline help element.

Parameters

string $html
string $help

Returns

string

decorate_with_description()

decorate_with_description(string  $html, string  $description) : string

Decorates the specified HTML with the specified description.

Parameters

string $html
string $description

Returns

string

render_alert_dismiss()

render_alert_dismiss(boolean  $dismissible) : string|null

Renders dismiss button.

Parameters

boolean $dismissible

Returns

string|null

render_alert_heading()

render_alert_heading(string|null  $heading) : string|null

Renders alert heading.

Parameters

string|null $heading

Returns

string|null

render_alert_message()

render_alert_message(mixed  $message) : string

Renders alert message.

Parameters

mixed $message

Throws

\InvalidArgumentException

if the message cannot be rendered.

Returns

string

render_alert_content()

render_alert_content(string  $message) : string

Renders alert content.

Parameters

string $message

Returns

string

render_errors()

render_errors(\Brickrouge\Validate\Errors  $errors) : string

Renders errors as an HTML string.

Parameters

\Brickrouge\Validate\Errors $errors

Returns

string