Class Element

An HTML 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.

ICanBoogie\Object implements ICanBoogie\ToArrayRecursive uses ICanBoogie\ToArrayRecursiveTrait, ICanBoogie\PrototypeTrait

Brickrouge\Element implements ArrayAccess, IteratorAggregate, Brickrouge\HTMLStringInterface

Direct known subclasses

Indirect known subclasses

Namespace: Brickrouge
See: http://dev.w3.org/html5/spec/Overview.html#embedding-custom-non-visible-data-with-the-data-attributes
Located at vendor/brickrouge/brickrouge/lib/element.php

Methods summary

`protected static`	# `handle_assets( )`
`protected static`	# `add_assets( Brickrouge\Document $document )` Adds assets to the document. Adds assets to the document. Parameters `$document` `Brickrouge\Document` $document
`public static string`	# `auto_element_id( )` Returns a unique element id string. Returns a unique element id string. Returns `string`
`public`	# `__construct( string $type, array $attributes = array() )` Parameters `$type` `string` $type Type of the element, it can be one of the custom types (`TYPE_*`) or any HTML type. `$attributes` `array` $attributes HTML and custom attributes.
`public boolean`	# `offsetExists( string $attribute )` Checks is an attribute is set. Checks is an attribute is set. Parameters `$attribute` `string` $attribute Returns `boolean` Implementation of `ArrayAccess::offsetExists()`
`public mixed\|null`	# `offsetGet( string $attribute, null $default = null )` Returns the value of an attribute. Returns the value of an attribute. Parameters `$attribute` `string` $attribute `$default` `null` $default The default value of the attribute. Returns `mixed\|null` The value of the attribute, or null if is not set. Implementation of `ArrayAccess::offsetGet()`
`public`	# `offsetSet( string $attribute, mixed $value )` Sets the value of an attribute. Sets the value of an attribute. Parameters `$attribute` `string` $attribute The attribute. `$value` `mixed` $value The value of the attribute. Implementation of `ArrayAccess::offsetSet()`
`public`	# `offsetUnset( string $attribute )` Removes an attribute. Removes an attribute. Parameters `$attribute` `string` $attribute The name of the attribute. Implementation of `ArrayAccess::offsetUnset()`
`public Brickrouge\Iterator`	# `getIterator( )` Returns an iterator. Returns an iterator. Returns `Brickrouge\Iterator` Implementation of `IteratorAggregate::getIterator()`
`protected Brickrouge\Dataset`	# `get_dataset( )` Returns the `Brickrouge\Dataset` of the element. Returns the `Brickrouge\Dataset` of the element. Returns `Brickrouge\Dataset`
`protected Brickrouge\Dataset`	# `set_dataset( array\|Brickrouge\Dataset $dataset )` Sets the datset of the element. Sets the datset of the element. Parameters `$dataset` `array\|Brickrouge\Dataset` $properties Returns `Brickrouge\Dataset`
`protected`	# `get_attributes( )`
`protected string`	# `lazy_get_id( )` Returns the element's id. Returns the element's id. If the element's id is empty, a unique id is generated and added to its tags. Returns `string`
`protected string`	# `get_class( )` Returns the value of the "class" attribute. Returns the value of the "class" attribute. Returns `string`
`protected`	# `set_class( string $class )` Sets the value of the "class" attribute. Sets the value of the "class" attribute. Parameters `$class` `string` $class
`public Brickrouge\Element`	# `add_class( mixed $class )` Adds a class name to the "class" attribute. Adds a class name to the "class" attribute. Parameters `$class` `mixed` $class Returns `Brickrouge\Element`
`public Brickrouge\Element`	# `remove_class( mixed $class )` Removes a class name from the `class` attribute. Removes a class name from the `class` attribute. Parameters `$class` `mixed` $class Returns `Brickrouge\Element`
`public boolean`	# `has_class( string $class_name )` Checks if a class name is defined in the `class` attribute. Checks if a class name is defined in the `class` attribute. Parameters `$class_name` `string` $class_name Returns `boolean` true if the element has the class name, false otherwise.
`protected array`	# `alter_class_names( array $class_names )` Alters the class names. Alters the class names. This method is invoked before the class names are rendered. Parameters `$class_names` `array` $class_names Returns `array`
`protected string`	# `render_class( array $class_names )` Renders the `class` attribute value. Renders the `class` attribute value. Parameters `$class_names` `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 discarted. If the value is `true` the identifier of the class name is used as value. Returns `string`
`public`	# `adopt( string\|Brickrouge\Element\|array $child, string\|Brickrouge\Element $other = null )` Add a child or children to the element. 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 `$child` `string\|Brickrouge\Element\|array` $child The child or children to add. `$other` `string\|Brickrouge\Element` $other[optional] Other child.
`public array[int]Element\|string`	# `get_ordered_children( )` Returns the children of the element ordered according to their weight. Returns the children of the element ordered according to their weight. Returns `array[int]Element\|string`
`protected string`	# `render_child( Brickrouge\Element\|string $child )` Returns the HTML representation of a child element. Returns the HTML representation of a child element. Parameters `$child` `Brickrouge\Element\|string` $child Returns `string`
`protected string`	# `render_children( array $children )` Renders the children of the element into a HTML string. Renders the children of the element into a HTML string. Parameters `$children` `array` $children Returns `string`
`protected string\|null`	# `render_inner_html( )` Returns the HTML representation of the element's content. Returns the HTML representation of the element's content. The children of the element are ordered before they are rendered using the `Brickrouge\Element::render_children()` method. According to their types, the following methods can be invoked to render the inner HTML of elements: `Brickrouge\Element::render_inner_html_for_select()` `Brickrouge\Element::render_inner_html_for_textarea()` `Brickrouge\Element::render_inner_html_for_checkbox_group()` `Brickrouge\Element::render_inner_html_for_radio_group()` Returns `string\|null` The content of the element. The element is to be considered _self-closing_ if `null` is returned.
`protected string`	# `render_inner_html_for_select( )` Renders inner HTML of `SELECT` elements. Renders inner HTML of `SELECT` elements. Returns `string`
`protected string`	# `render_inner_html_for_textarea( )` Renders the inner HTML of `TEXTAREA` elements. Renders the inner HTML of `TEXTAREA` elements. Returns `string`
`protected string`	# `render_inner_html_for_checkbox_group( )` Renders inner HTML of `Brickrouge\Element::TYPE_CHECKBOX_GROUP` custom elements. Renders inner HTML of `Brickrouge\Element::TYPE_CHECKBOX_GROUP` custom elements. Returns `string`
`protected string`	# `render_inner_html_for_radio_group( )` Renders inner HTML of `Brickrouge\Element::TYPE_RADIO_GROUP` custom elements. Renders inner HTML of `Brickrouge\Element::TYPE_RADIO_GROUP` custom elements. Returns `string`
`protected array`	# `alter_attributes( array $attributes )` Alters the provided attributes. 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 `Brickrouge\Element::TYPE_CHECKBOX` is set to `true` if their `Brickrouge\Element::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 `Brickrouge\Element::DEFAULT_VALUE` attribute is defined and the `value` attribute is not (`null`). Parameters `$attributes` `array` $attributes Returns `array` The altered attributes.
`protected string`	# `render_attributes( array $attributes )` Renders attributes. Renders attributes. Attributes with `false` or `null` values as well as custom attributes are discarted. Attributes with the `true` value are translated to XHTML standard e.g. readonly="readonly". Parameters `$attributes` `array` $attributes Returns `string` Throws `InvalidArgumentException` if the value is an array or an object that doesn't implement the `toString()` method.
`protected array`	# `alter_dataset( array $dataset )` Alters the dataset. Alters the dataset. The method is invoked before the dataset is rendered. The method might add the `default-value` and `widget-constructor` keys. Parameters `$dataset` `array` $dataset Returns `array`
`protected string`	# `render_dataset( array $dataset )` Renders dataset. 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 discarted, but unlike classic attributes boolean values are converted to integers. Parameters `$dataset` `array` $dataset Returns `string`
`protected string`	# `render_outer_html( )` Returns the HTML representation of the element and its contents. 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 `Brickrouge\Element::alter_attributes()` method is invoked to alter the attributes and the `Brickrouge\Element::render_attributes()` method is invoked to render them. The `Brickrouge\Element::alter_dataset()` method is invoked to alter the dataset and the `Brickrouge\Element::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`
`protected string`	# `decorate( string $html )` Decorates the specified HTML. Decorates the specified HTML. The HTML can be decorated by following attributes: A label defined by the `Brickrouge\Element::LABEL` special attribute. The `Brickrouge\Element::decorate_with_label()` method is used to decorate the HTML with the label. An inline help defined by the `Brickrouge\Element::INLINE_HELP` special attribute. The `Brickrouge\Element::decorate_with_inline_help()` method is used to decorate the HTML with the inline help. A description (or help block) defined by the `Brickrouge\Element::DESCRIPTION` special attribute. The `Brickrouge\Element::decorate_with_description()` method is used to decorate the HTML with the description. A legend defined by the `Brickrouge\Element::LEGEND` special attribute. The `Brickrouge\Element::decorate_with_label()` method is used to decorate the HTML with the legend. Parameters `$html` `string` $html The HTML to decorate. Returns `string` The decorated HTML.
`protected string`	# `decorate_with_label( string $html, string $label )` Decorates the specified HTML with specified label. Decorates the specified HTML with specified label. The position of the label is defined using the T_LABEL_POSITION tag Parameters `$html` `string` $html `$label` `string` $label The label as defined by the T_LABEL tag. Returns `string`
`protected string`	# `decorate_with_legend( string $html, string $legend )` Decorates the specified HTML with a fieldset and the specified legend. Decorates the specified HTML with a fieldset and the specified legend. Parameters `$html` `string` $html `$legend` `string` $legend Returns `string`
`protected string`	# `decorate_with_inline_help( string $html, string $help )` Decorates the specified HTML with an inline help element. Decorates the specified HTML with an inline help element. Parameters `$html` `string` $html `$help` `string` $help Returns `string`
`protected string`	# `decorate_with_description( string $html, string $description )` Decorates the specified HTML with the specified description. Decorates the specified HTML with the specified description. Parameters `$html` `string` $html `$description` `string` $description Returns `string`
`public string`	# `render( )` Renders the element into an HTML string. Renders the element into an HTML string. Before the element is rendered the method `Brickrouge\Element::handle_assets()` is invoked. The inner HTML is rendered by the `Brickrouge\Element::render_inner_html()` method. The outer HTML is rendered by the `Brickrouge\Element::render_outer_html()` method. Finaly, the HTML is decorated by the `Brickrouge\Element::decorate()` method. If the `Brickrouge\ElementIsEmpty` exception is caught during the rendering an empty string is returned. Returns `string` The HTML representation of the object
`public string`	# `__toString( )` Renders the element into an HTML string. Renders the element into an HTML string. The method `Brickrouge\Element::render()` is invoked to render the element. If an exception is thrown during the rendering it is rendered using the `Brickrouge\render_exception()` function and returned. Returns `string` The HTML representation of the object Implementation of `Brickrouge\HTMLStringInterface::__toString()`
`public boolean`	# `validate( mixed $value, ICanBoogie\Errors $errors )` Validates the specified value. Validates the specified value. This function uses the validator defined using the `Brickrouge\Element::VALIDATOR` special attribute to validate its value. Parameters `$value` `mixed` $value `$errors` `ICanBoogie\Errors` $errors Returns `boolean` `true` if the validation succeed, `false` otherwise.

Magic methods summary

Constants summary

`string`	`TYPE_CHECKBOX`	`'#checkbox'`	# Custom type used to create checkbox elements. Custom type used to create checkbox elements.
`string`	`TYPE_CHECKBOX_GROUP`	`'#checkbox-group'`	# Custom type used to create checkbox group elements. Custom type used to create checkbox group elements.
`string`	`TYPE_RADIO`	`'#radio'`	# Custom type used to create radio elements. Custom type used to create radio elements.
`string`	`TYPE_RADIO_GROUP`	`'#radio-group'`	# Custom type used to create radio group elements. Custom type used to create radio group elements.
`string`	`CHILDREN`	`'#children'`	# Used to define the children of an element. Used to define the children of an element.
`string`	`DEFAULT_VALUE`	`'#default-value'`	# Used to define the default value of an element. Used to define the default value of an element. The default value is added to the dataset as 'default-value'.
`string`	`DESCRIPTION`	`'#description'`	# Used to define the description block of an element. Used to define the description block of an element. See `Brickrouge\Element::decorate_with_description()`
`string`	`GROUP`	`'#group'`	# Used to define the group of an element. Used to define the group of an element.
`string`	`GROUPS`	`'#groups'`	# Used to define the groups that can be used by children elements. Used to define the groups that can be used by children elements.
`string`	`INLINE_HELP`	`'#inline-help'`	# Used to define the inline help of an element. Used to define the inline help of an element. See `Brickrouge\Element::decorate_with_inline_help()`
`string`	`INNER_HTML`	`'#inner-html'`	# Used to define the inner HTML of an element. If the value of the tag is null, the markup will be self-closing. Used to define the inner HTML of an element. If the value of the tag is null, the markup will be self-closing.
`string`	`LABEL`	`'#label'`	# Used to define the label of an element. Used to define the label of an element. See `Brickrouge\Element::decorate_with_label()`
`string`	`LABEL_POSITION`	`'#label-position'`	# Used to define the position of the label. Possible positions are "before", "after" and "above". Defaults to "after". Used to define the position of the label. Possible positions are "before", "after" and "above". Defaults to "after".
`string`	`LABEL_MISSING`	`'#label-missing'`	#
`string`	`LEGEND`	`'#element-legend'`	# Used to define the legend of an element. If the legend is defined the element is wrapped into a fieldset when it is rendered. Used to define the legend of an element. If the legend is defined the element is wrapped into a fieldset when it is rendered. See `Brickrouge\Element::decorate_with_legend()`
`string`	`REQUIRED`	`'required'`	# Used to define the required state of an element. Used to define the required state of an element. See `Brickrouge\Form::validate()` http://dev.w3.org/html5/spec/Overview.html#the-required-attribute
`string`	`OPTIONS`	`'#options'`	# Used to define the options of the following element types: "select", `Brickrouge\Element::TYPE_RADIO_GROUP` and `Brickrouge\Element::TYPE_CHECKBOX_GROUP`. Used to define the options of the following element types: "select", `Brickrouge\Element::TYPE_RADIO_GROUP` and `Brickrouge\Element::TYPE_CHECKBOX_GROUP`.
`string`	`OPTIONS_DISABLED`	`'#options-disabled'`	# Used to define which options are disabled. Used to define which options are disabled.
`string`	`STATE`	`'#state'`	# Used to define the state of the element: "success", "warning" or "error". Used to define the state of the element: "success", "warning" or "error".
`string`	`VALIDATOR`	`'#validator'`	# Used to define the validator of an element. The validator is defined using an array made of a callback and a possible userdata array. Used to define the validator of an element. The validator is defined using an array made of a callback and a possible userdata array.
`string`	`VALIDATOR_OPTIONS`	`'#validator-options'`	#
`string`	`WEIGHT`	`'#weight'`	# Use to define the weight of an element. This attribute can be used to reorder children when a parent element is rendered. Use to define the weight of an element. This attribute can be used to reorder children when a parent element is rendered. See `Brickrouge\Element::get_ordered_children()`
`string`	`WIDGET_CONSTRUCTOR`	`'#widget-constructor'`	# The name of the Javascript constructor that should be used to construct the widget. The name of the Javascript constructor that should be used to construct the widget.

Properties summary

`protected static integer`	`$auto_element_id`	# Next available auto element id index. Next available auto element id index.
`public string`	`$type`	# Type if the element, as provided during `Brickrouge\Element::__construct()`. Type if the element, as provided during `Brickrouge\Element::__construct()`.
`public string`	`$tag_name`	# Tag name of the rendered HTML element. Tag name of the rendered HTML element.
`public array`	`$children`	# An array containing the children of the element. An array containing the children of the element.
`protected array[string]mixed`	`$tags`	# Tags of the element, including HTML and special attributes. Tags of the element, including HTML and special attributes.
`protected string\|null`	`$inner_html`	# Inner HTML of the element. Inner HTML of the element. See `Brickrouge\Element::render_inner_html()`
`protected array`	`$class_names`	# Class names used to compose the value of the `class` attribute. Class names used to compose the value of the `class` attribute.

Magic properties

`public string`	`$class`	# 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. 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.
`public Brickrouge\Dataset`	`$dataset`	# The dataset property provides a convenient mapping to the data-* attributes on an element. The dataset property provides a convenient mapping to the data-* attributes on an element.
`public string`	`$id`	# Assigns an identifier to an element. This identifier mush be unique in a document. Assigns an identifier to an element. This identifier mush be unique in a document.

Magic properties inherited from ICanBoogie\Object

$prototype

Namespaces

Classes

Interfaces

Traits

Exceptions

Functions

Class Element

Direct known subclasses

Indirect known subclasses

Methods summary

Parameters

Returns

Parameters

Parameters

Returns

Implementation of

Parameters

Returns

Implementation of

Parameters

Implementation of

Parameters

Implementation of

Returns

Implementation of

Returns

Parameters

Returns

Returns

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Implementation of

Parameters

Returns

Methods inherited from ICanBoogie\Object

Methods inherited from ICanBoogie\ToArrayRecursive

Methods used from ICanBoogie\ToArrayRecursiveTrait