HTML_Common2

HTML_Common is mostly feature-complete, so the changes to its functionality when moving from PHP4 to PHP5 version should be minimal.

HTML_Common2 has a static $_options property containing options global for the whole HTML document, like those that were previously set via setTab() and setLineEnd() and (especially) the one requested by http://pear.php.net/bugs/bug.php?id=2410

Most of the methods that were marked as ”@access private” became protected and thus their names don't start with underscore per relevant RFC, some were given longer and easier to understand names. Methods _getAttrKey() / _updateAttrArray() were dropped, as they were leftovers from the age when HTML_Common generated non-XHTML output.

Several methods were renamed for easier understanding of their purpose: updateAttributes() became mergeAttributes(), setTabOffset() / getTabOffset() became setIndentLevel() / getIndentLevel().

apiVersion() was dropped: it is a job of the PEAR installer to resolve dependencies and as history showed the return value of this method was not properly changed anyway when introducing changes.

Per discussion here the API of HTML_Common2 is currently the following:

• public static methods: setOption()/getOption() for setting global document options.
• protected static methods: parseAttributes(), removeAttributeArray(), getAttributesString() — these should be used by child classes for working with “other” attribute arrays (i.e. not with $attributes property).
• public methods: setAttribute() / getAttribute(), setAttributes() / getAttributes(), mergeAttributes(), removeAttribute(), setIndentLevel() / getIndentLevel(), setComment() / getComment(), display().
• protected method: getIndent().
• abstract method: toHtml(). Due to the presence of this method class is declared abstract and cannot be instantiated.

The code was added to PHP CVS, view via web interface.

Currently toHtml() method is abstract and the class is abstract. Maybe we should consider adding some default HTML generation to the method and make the class usable as-is, without extending.

Making HTML_Common2 usable as-is (by removing the abstract) could only produce a string of name, value pairs. Without extra information from subclasses like tag name, etc., HTML_Common2 isn't able to produce valid html or xhtml.

One thing that I noticed when looking through HTML_Common2 in cvs was that the parseAttributes does more work than the method name implies. It has been that way since the original commit, so it's my fault to begin with. To follow good OOP I stick to the rule “Say what you mean and mean what you say” (at least now I do) Therefore parseAttributes should only except a string to parse the attributes from. The other functionality should be moved to setAttributes. Petty I know but if we are chaning things … — renamed in release 0.2.0, thanks for pointer.

Released 2006-07-03

Changelog:

• $attributes array is now protected rather than private (and thus renamed from $_attributes)
• parseAttributes() was renamed to prepareAttributes(), string parsing logic was extracted into the new parseAttributes() method
• Added magic __toString() method as an alias for toHtml(), deprecated display(): it is now possible to print an instance of HTML_Common2 subclass by simply using the

  echo $object;

• It is now possible to watch some attributes for changes, this can be used to
  • Make attributes read-only (like type attribute of <input /> tag)
  • Do some custom processing (update the element's value if its name changes)

The reasons for these changes are covered above and in the discussion about HTML_QuickForm2_Element.

• Addition of protected $content (with setContent() and getContent() methods) and $tagName properties and default implementation of toHTML() method. Class will, however, remain abstract since there will be no way to set $tagName without extending the class. 2006-06-23: Setting the content is the job of a subclass. We'll handle the content as a string, instance of HTML_Common2 or an array of those in default toHtml() implementation, however. A $tagEmpty property will be added also to toggle generation of <foo></foo> vs. <foo />.

Instead of $tagEmpty, I suggest just checking for $content. If it's null, then the result will be <foo />. If it's not null, for example if it's an empty string like ””, the result will be <foo></foo>. There is no need for another instance variable IMO.

I already thought about that, didn't like the idea for two reasons

1. Differentiating between null and empty string looks like “too much magic” to me,
2. Some elements make no sense with content (e.g. <br />), some break if rendered without closing tag (e.g. <script></script>). Thus we'll need different default values for content (null and ””) of these elements, might as well have an easier to understand property.

There is another school that uses this list http://www.w3.org/TR/REC-html40/index/elements.html in order to define which elements are empty tags. But I think this is a limited way to deal with the problem. I am convinced that using null (which is the default value of an unset property) and ”” is enough since it doesn't have the same meaning (if you think of SQL for example). Users know beforehand when a tag should contain a value, even if it's an empty value (textarea comes to mind). Or maybe we could use both solutions, if the value is empty, we check if the tagname is in the list of elements that can be empty and adjust the generated html accordingly…

• Up the stability to 'alpha'
• Move to BSD license
• Move to package.xml 2.0
• Remove display() and toHtml() methods
• Rename 'encoding' option to 'charset' (that's how it is called in htmlspecialchars()
• Always convert attribute values to strings