Subclassing HTML_Common2

Subclassing HTML_Common2 – Protected methods, output formatting, "watched" attributes.

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" />
Setting document-wide options. (Previous) HTML_Crypt (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

There are no user contributed notes for this page.