From eecb18e702bc269bbf7fd5b4f8a9ec9e18557031 Mon Sep 17 00:00:00 2001 From: xue <> Date: Mon, 20 Feb 2006 23:25:30 +0000 Subject: Code cleanup and added some documentation. --- framework/Web/UI/THtmlWriter.php | 244 +++++++++++++++++++-------------------- 1 file changed, 118 insertions(+), 126 deletions(-) (limited to 'framework/Web/UI/THtmlWriter.php') diff --git a/framework/Web/UI/THtmlWriter.php b/framework/Web/UI/THtmlWriter.php index 613d58dc..8a092460 100644 --- a/framework/Web/UI/THtmlWriter.php +++ b/framework/Web/UI/THtmlWriter.php @@ -10,13 +10,27 @@ * @package System.Web.UI */ -// todo: test if an attribute is a url -// keep nonclosing tag only -// add more utility methods (e.g. render....) -// implment encoding (for text and url) /** * THtmlWriter class * + * THtmlWriter is a writer that renders valid XHTML outputs. + * It provides functions to render tags, their attributes and stylesheet fields. + * Attribute and stylesheet values will be automatically HTML-encoded if + * they require so. For example, the 'value' attribute in an input tag + * will be encoded. + * + * A common usage of THtmlWriter is as the following sequence: + * + * $writer->addAttribute($name1,$value1); + * $writer->addAttribute($name2,$value2); + * $writer->renderBeginTag($tagName); + * // ... render contents enclosed within the tag here + * $writer->renderEndTag(); + * + * Make sure each invocation of {@link renderBeginTag} is accompanied with + * a {@link renderEndTag} and they are properly nested, like nesting + * tags in HTML and XHTML. + * * @author Qiang Xue * @version $Revision: $ $Date: $ * @package System.Web.UI @@ -24,110 +38,28 @@ */ class THtmlWriter extends TApplicationComponent implements ITextWriter { - const TAG_INLINE=0; - const TAG_NONCLOSING=1; - const TAG_OTHER=2; - const CHAR_NEWLINE="\n"; - const CHAR_TAB="\t"; - private static $_tagTypes=array( - '*'=>2, - 'a'=>0, - 'acronym'=>0, - 'address'=>2, - 'area'=>1, - 'b'=>0, - 'base'=>1, - 'basefont'=>1, - 'bdo'=>0, - 'bgsound'=>1, - 'big'=>0, - 'blockquote'=>2, - 'body'=>2, - 'br'=>2, - 'button'=>0, - 'caption'=>2, - 'center'=>2, - 'cite'=>0, - 'code'=>0, - 'col'=>1, - 'colgroup'=>2, - 'del'=>0, - 'dd'=>0, - 'dfn'=>0, - 'dir'=>2, - 'div'=>2, - 'dl'=>2, - 'dt'=>0, - 'em'=>0, - 'embed'=>1, - 'fieldset'=>2, - 'font'=>0, - 'form'=>2, - 'frame'=>1, - 'frameset'=>2, - 'h1'=>2, - 'h2'=>2, - 'h3'=>2, - 'h4'=>2, - 'h5'=>2, - 'h6'=>2, - 'head'=>2, - 'hr'=>1, - 'html'=>2, - 'i'=>0, - 'iframe'=>2, - 'img'=>1, - 'input'=>1, - 'ins'=>0, - 'isindex'=>1, - 'kbd'=>0, - 'label'=>0, - 'legend'=>2, - 'li'=>0, - 'link'=>1, - 'map'=>2, - 'marquee'=>2, - 'menu'=>2, - 'meta'=>1, - 'nobr'=>0, - 'noframes'=>2, - 'noscript'=>2, - 'object'=>2, - 'ol'=>2, - 'option'=>2, - 'p'=>0, - 'param'=>2, - 'pre'=>2, - 'ruby'=>2, - 'rt'=>2, - 'q'=>0, - 's'=>0, - 'samp'=>0, - 'script'=>2, - 'select'=>2, - 'small'=>2, - 'span'=>0, - 'strike'=>0, - 'strong'=>0, - 'style'=>2, - 'sub'=>0, - 'sup'=>0, - 'table'=>2, - 'tbody'=>2, - 'td'=>0, - 'textarea'=>0, - 'tfoot'=>2, - 'th'=>0, - 'thead'=>2, - 'title'=>2, - 'tr'=>2, - 'tt'=>0, - 'u'=>0, - 'ul'=>2, - 'var'=>0, - 'wbr'=>1, - 'xml'=>2 + /** + * @var array list of tags are do not need a closing tag + */ + private static $_simpleTags=array( + 'area'=>true, + 'base'=>true, + 'basefont'=>true, + 'bgsound'=>true, + 'col'=>true, + 'embed'=>true, + 'frame'=>true, + 'hr'=>true, + 'img'=>true, + 'input'=>true, + 'isindex'=>true, + 'link'=>true, + 'meta'=>true, + 'wbr'=>true, ); + /** + * @var array list of attributes that need HTML encoding + */ private static $_attrEncode=array( 'abbr'=>true, 'accesskey'=>true, @@ -145,81 +77,138 @@ class THtmlWriter extends TApplicationComponent implements ITextWriter 'title'=>true, 'value'=>true ); + /** + * @var array list of stylesheet attributes that need HTML encoding + */ private static $_styleEncode=array( 'background-image'=>true, 'list-style-image'=>true ); + /** + * @var array list of attributes to be rendered for a tag + */ private $_attributes=array(); + /** + * @var array list of openning tags + */ private $_openTags=array(); - private $_writer=null; + /** + * @var array list of style attributes + */ private $_styles=array(); + /** + * @var ITextWriter writer + */ + private $_writer=null; + /** + * Constructor. + * @param ITextWriter a writer that THtmlWriter will pass its rendering result to + */ public function __construct($writer) { $this->_writer=$writer; } - public function isValidFormAttribute($name) - { - return true; - } - + /** + * Adds a list of attributes to be rendered. + * @param array list of attributes to be rendered + */ public function addAttributes($attrs) { foreach($attrs as $name=>$value) $this->_attributes[$name]=isset(self::$_attrEncode[$name])?THttpUtility::htmlEncode($value):$value; } + /** + * Adds an attribute to be rendered. + * @param string name of the attribute + * @param string value of the attribute + */ public function addAttribute($name,$value) { $this->_attributes[$name]=isset(self::$_attrEncode[$name])?THttpUtility::htmlEncode($value):$value; } + /** + * Removes the named attribute from rendering + * @param string name of the attribute to be removed + */ public function removeAttribute($name) { - if(isset($this->_attributes[$name])) - unset($this->_attributes[$name]); + unset($this->_attributes[$name]); } - + + /** + * Adds a list of stylesheet attributes to be rendered. + * @param array list of stylesheet attributes to be rendered + */ + public function addStyleAttributes($attrs) + { + foreach($attrs as $name=>$value) + $this->_styles[$name]=isset(self::$_styleEncode[$name])?THttpUtility::htmlEncode($value):$value; + } + + /** + * Adds a stylesheet attribute to be rendered + * @param string stylesheet attribute name + * @param string stylesheet attribute value + */ public function addStyleAttribute($name,$value) { $this->_styles[$name]=isset(self::$_styleEncode[$name])?THttpUtility::htmlEncode($value):$value; } + /** + * Removes the named stylesheet attribute from rendering + * @param string name of the stylesheet attribute to be removed + */ public function removeStyleAttribute($name) { - if(isset($this->_styles[$name])) - unset($this->_styles[$name]); + unset($this->_styles[$name]); } + /** + * Flushes the rendering result. + * This will invoke the underlying writer's flush method. + */ public function flush() { $this->_writer->flush(); } + /** + * Renders a string. + * @param string string to be rendered + */ public function write($str) { $this->_writer->write($str); } + /** + * Renders a string and appends a newline to it. + * @param string string to be rendered + */ public function writeLine($str='') { - $this->_writer->write($str.self::CHAR_NEWLINE); + $this->_writer->write($str."\n"); } + /** + * Renders an HTML break. + */ public function writeBreak() { $this->_writer->write('
'); } - public function writeAttribute($name,$value,$encode=false) - { - $this->_writer->write(' '.$name.='"'.($encode?THttpUtility::htmlEncode($value):$value).'"'); - } - + /** + * Renders the openning tag. + * @param string tag name + */ public function renderBeginTag($tagName) { - $tagType=isset(self::$_tagTypes[$tagName])?self::$_tagTypes[$tagName]:self::TAG_OTHER; $str='<'.$tagName; foreach($this->_attributes as $name=>$value) $str.=' '.$name.'="'.$value.'"'; @@ -230,7 +219,7 @@ class THtmlWriter extends TApplicationComponent implements ITextWriter $str.=$name.':'.$value.';'; $str.='"'; } - if($tagType===self::TAG_NONCLOSING) + if(isset(self::$_simpleTags[$tagName])) { $str.=' />'; array_push($this->_openTags,''); @@ -245,6 +234,9 @@ class THtmlWriter extends TApplicationComponent implements ITextWriter $this->_styles=array(); } + /** + * Renders the closing tag. + */ public function renderEndTag() { if(!empty($this->_openTags) && ($tagName=array_pop($this->_openTags))!=='') -- cgit v1.2.3