Subclassing HTML_Common2
Output formatting
HTML_Common2 does not generate any HTML itself, except for a HTML attribute string. However, it provides several methods and configuration parameters that can be used by child classes to format their output.
It is possible to specify indentation level of the current tag via HTML_Common2::setIndentLevel() and HTML comment to output beside tag via HTML_Common2::setComment(). These methods have corresponding getters HTML_Common2::getIndentLevel() and HTML_Common2::getComment().
There is also a protected HTML_Common2::getIndent() method that returns a string to indent the current tag
based on indent level and 'indent' configuration parameter.
Protected Methods
Child classes may take advantage of protected static methods for handling of attributes strings and arrays:
- HTML_Common2::getAttributesString()
- Creates a HTML attribute string from a given attribute array.
- HTML_Common2::parseAttributes()
- Parses a given attribute string into an attribute array, properly handles non-XHTML strings.
- HTML_Common2::prepareAttributes()
-
Creates a proper attribute array from given array or string. Attribute names are
lowercased, integer-based keys are converted to
('value' => 'value'). This is the preferred method to handle incoming attributes.
Monitoring Changes to Specific Attributes
It is sometimes necessary either to prevent changing some attribute of a HTML tag (e.g.
type attribute of <input /> element) or monitor
changes to an attribute to do some additional processing (e.g. on changing element's
id attribute we should also update some references to that attribute).
HTML_Common2 provides means to do this additional processing in the form
of HTML_Common2::$watchedAttributes
property and HTML_Common2::onAttributeChange() method. When a change of an attribute with name
in $watchedAttributes array is attempted,
onAttributeChange() is called instead of performing the attempted change. It
is up to the programmer implementing the method to decide what to do with the attribute.
Usage Example
The following code prevents setting type attribute except via
constructor and to update the value attribute when name
attribute changes. It also shows how to use methods provided by
HTML_Common2 to format the resultant HTML.
Complex subclass of HTML_Common2
<?php
$_REQUEST = array(
'foo' => 'Foo value',
'bar' => 'Bar value'
);
class HTML_Tag_Input extends HTML_Common2
{
protected $watchedAttributes = array('name', 'type');
public function __construct($type, $name, $attributes = null)
{
$this->attributes['type'] = (string)$type;
$this->setName($name);
parent::__construct($attributes);
}
public function setName($name)
{
$this->attributes['name'] = (string)$name;
if (!empty($_REQUEST[$name])) {
$this->attributes['value'] = $_REQUEST[$name];
}
}
protected function onAttributeChange($name, $value)
{
if ('type' == $name) {
throw new Exception("Attribute 'type' is read-only");
} elseif ('name' == $name) {
if (null === $value) {
throw new Exception("Required attribute 'name' cannot be removed");
}
$this->setName($value);
}
}
public function __toString()
{
return ($this->getComment()
? $this->getIndent() . '<!-- ' . $this->getComment() . ' -->' . HTML_Common2::getOption('linebreak')
: '')
. $this->getIndent() . '<input' . $this->getAttributes(true) . ' />';
}
}
$input = new HTML_Tag_Input('text', 'foo');
echo $input . "\n";
try {
$input->setAttribute('type', 'file');
} catch (Exception $e) {
echo $e->getMessage() . "\n";
}
$input->setAttribute('name', 'bar')
->setIndentLevel(1)
->setComment('Simplified version of HTML_QuickForm2_Element_Input');
echo $input;
?>
The above code will produce the following output:
<input type="text" name="foo" value="Foo value" />
Attribute 'type' is read-only
<!-- Simplified version of HTML_QuickForm2_Element_Input -->
<input type="text" name="bar" value="Bar value" />