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/Javascripts/TJavaScript.php | 74 +++++----
framework/Web/THttpUtility.php | 12 ++
framework/Web/UI/TClientScriptManager.php | 9 ++
framework/Web/UI/THtmlWriter.php | 244 +++++++++++++++---------------
framework/Web/UI/TPage.php | 2 +-
framework/Web/UI/TTemplateManager.php | 4 +-
framework/Web/UI/WebControls/TStyle.php | 3 +-
7 files changed, 191 insertions(+), 157 deletions(-)
(limited to 'framework/Web')
diff --git a/framework/Web/Javascripts/TJavaScript.php b/framework/Web/Javascripts/TJavaScript.php
index 47d506fb..0d081e02 100644
--- a/framework/Web/Javascripts/TJavaScript.php
+++ b/framework/Web/Javascripts/TJavaScript.php
@@ -13,7 +13,7 @@
/**
* TJavaScript class.
*
- * TJavaScript is a utility class containing commonly used javascript-related
+ * TJavaScript is a utility class containing commonly-used javascript-related
* functions.
*
* @author Wei Zhuo<weizhuo[at]gmail[dot]com>
@@ -23,6 +23,11 @@
*/
class TJavaScript
{
+ /**
+ * Renders a list of javascript files
+ * @param array URLs to the javascript files
+ * @return string rendering result
+ */
public static function renderScriptFiles($files)
{
$str='';
@@ -31,11 +36,21 @@ class TJavaScript
return $str;
}
+ /**
+ * Renders a javascript file
+ * @param string URL to the javascript file
+ * @return string rendering result
+ */
public static function renderScriptFile($file)
{
return '<script type="text/javascript" src="'.THttpUtility::htmlEncode($file)."\"></script>\n";
}
+ /**
+ * Renders a list of javascript blocks
+ * @param array javascript blocks
+ * @return string rendering result
+ */
public static function renderScriptBlocks($scripts)
{
if(count($scripts))
@@ -44,33 +59,24 @@ class TJavaScript
return '';
}
+ /**
+ * Renders javascript block
+ * @param string javascript block
+ * @return string rendering result
+ */
public static function renderScriptBlock($script)
{
return "<script type=\"text/javascript\">\n/*<![CDATA[*/\n{$script}\n/*]]>*/\n</script>\n";
}
- public static function renderArrayDeclarations($arrays)
- {
- if(count($arrays))
- {
- $str="<script type=\"text/javascript\">\n/*<![CDATA[*/\n";
- foreach($arrays as $name=>$array)
- $str.="var $name=new Array(".implode(',',$array).");\n";
- $str.="\n/*]]>*/\n</script>\n";
- return $str;
- }
- else
- return '';
- }
-
- public static function renderArrayDeclaration($array)
- {
- $str="<script type=\"text/javascript\">\n/*<![CDATA[*/\n";
- $str.="var $name=new Array(".implode(',',$array).");\n";
- $str.="\n/*]]>*/\n</script>\n";
- return $str;
- }
-
+ /**
+ * Quotes a javascript string.
+ * After processing, the string can be safely enclosed within a pair of
+ * quotation marks and serve as a javascript string.
+ * @param string string to be quoted
+ * @param boolean whether this string is used as a URL
+ * @return string the quoted string
+ */
public static function quoteString($js,$forUrl=false)
{
if($forUrl)
@@ -86,13 +92,17 @@ class TJavaScript
* <code>
* $options['onLoading'] = "doit";
* $options['onComplete'] = "more";
- * $js = new TJavascriptSerializer($options);
- * echo $js->toMap();
+ * echo TJavaScript::encode($options);
* //expects the following javascript code
* // {'onLoading':'doit','onComplete':'more'}
* </code>
*
- * For higher complexity data structures use TJSON to serialize and unserialize.
+ * For higher complexity data structures use {@link jsonEncode} and {@link jsonDecode}
+ * to serialize and unserialize.
+ *
+ * @param mixed PHP variable to be encoded
+ * @param boolean whether the output is a map or a list.
+ * @return string the encoded string
*/
public static function encode($value,$toMap=true)
{
@@ -144,12 +154,24 @@ class TJavaScript
return '';
}
+ /**
+ * Encodes a PHP variable into javascript string.
+ * This method invokes {@TJSON} utility class to perform the encoding.
+ * @param mixed variable to be encoded
+ * @return string encoded string
+ */
public static function jsonEncode($value)
{
Prado::using('System.Web.Javascripts.TJSON');
return TJSON::encode($value);
}
+ /**
+ * Decodes a javascript string into PHP variable.
+ * This method invokes {@TJSON} utility class to perform the decoding.
+ * @param string string to be decoded
+ * @return mixed decoded variable
+ */
public static function jsonDecode($value)
{
Prado::using('System.Web.Javascripts.TJSON');
diff --git a/framework/Web/THttpUtility.php b/framework/Web/THttpUtility.php
index 34f1a8a4..398b3cf3 100644
--- a/framework/Web/THttpUtility.php
+++ b/framework/Web/THttpUtility.php
@@ -22,11 +22,23 @@ class THttpUtility
{
private static $_entityTable=null;
+ /**
+ * HTML-encodes a string.
+ * It is equivalent to {@link htmlspeicalchars} PHP function.
+ * @param string string to be encoded
+ * @return string encoded string
+ */
public static function htmlEncode($s)
{
return htmlspecialchars($s);
}
+ /**
+ * HTML-decodes a string.
+ * It is the inverse of {@link htmlEncode}.
+ * @param string string to be decoded
+ * @return string decoded string
+ */
public static function htmlDecode($s)
{
if(!self::$_entityTable)
diff --git a/framework/Web/UI/TClientScriptManager.php b/framework/Web/UI/TClientScriptManager.php
index 5ff5dba6..17d680c3 100644
--- a/framework/Web/UI/TClientScriptManager.php
+++ b/framework/Web/UI/TClientScriptManager.php
@@ -136,6 +136,11 @@ class TClientScriptManager extends TApplicationComponent
}
}
+ /**
+ * Registers postback javascript for a control.
+ * @param TControl control to be registered with postback js
+ * @param string js namespace for the control
+ */
public function registerPostBackControl($control,$namespace='Prado.WebUI')
{
$options = $this->getPostBackOptions($control);
@@ -149,6 +154,10 @@ class TClientScriptManager extends TApplicationComponent
$this->registerPradoScript('prado');
}
+ /**
+ * @param TControl postback control
+ * @return array postback options for the control
+ */
protected function getPostBackOptions($control)
{
$postback = $control->getPostBackOptions();
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:
+ * <code>
+ * $writer->addAttribute($name1,$value1);
+ * $writer->addAttribute($name2,$value2);
+ * $writer->renderBeginTag($tagName);
+ * // ... render contents enclosed within the tag here
+ * $writer->renderEndTag();
+ * </code>
+ * 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 <qiang.xue@gmail.com>
* @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('<br/>');
}
- 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))!=='')
diff --git a/framework/Web/UI/TPage.php b/framework/Web/UI/TPage.php
index aa188a03..f0525e76 100644
--- a/framework/Web/UI/TPage.php
+++ b/framework/Web/UI/TPage.php
@@ -663,7 +663,7 @@ class TPage extends TTemplateControl
public function ensureRenderInForm($control)
{
if(!$this->_inFormRender)
- throw new TConfigurationException('page_control_outofform',get_class($control),$control->getUniqueID());
+ throw new TConfigurationException('page_control_outofform',$control->getUniqueID());
}
/**
diff --git a/framework/Web/UI/TTemplateManager.php b/framework/Web/UI/TTemplateManager.php
index 404be231..75f6268f 100644
--- a/framework/Web/UI/TTemplateManager.php
+++ b/framework/Web/UI/TTemplateManager.php
@@ -100,8 +100,8 @@ class TTemplateManager extends TModule
*/
protected function getLocalizedTemplate($filename)
{
- $app = $this->getApplication()->getGlobalization();
- if(is_null($app)) return $filename;
+ if(($app=$this->getApplication()->getGlobalization())===null)
+ return $filename;
foreach($app->getLocalizedResource($filename) as $file)
{
if(($file=realpath($file))!==false && is_file($file))
diff --git a/framework/Web/UI/WebControls/TStyle.php b/framework/Web/UI/WebControls/TStyle.php
index ab7e8568..e1636145 100644
--- a/framework/Web/UI/WebControls/TStyle.php
+++ b/framework/Web/UI/WebControls/TStyle.php
@@ -329,8 +329,7 @@ class TStyle extends TComponent
$writer->addStyleAttribute(trim($arr[0]),trim($arr[1]));
}
}
- foreach($this->_fields as $name=>$value)
- $writer->addStyleAttribute($name,$value);
+ $writer->addStyleAttributes($this->_fields);
if($this->_font!==null)
$this->_font->addAttributesToRender($writer);
if($this->_class!==null)
--
cgit v1.2.3