[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * TDataGridColumn class file
   4   *
   5   * @author Qiang Xue <qiang.xue@gmail.com>
   6   * @link http://www.pradosoft.com/
   7   * @copyright Copyright &copy; 2005 PradoSoft
   8   * @license http://www.pradosoft.com/license/
   9   * @version $Id: TDataGridColumn.php 1486 2006-11-03 13:22:08Z xue $
  10   * @package System.Web.UI.WebControls
  11   */
  12  
  13  /**
  14   * Includes TDataFieldAccessor and TDataValueFormatter classes
  15   */
  16  Prado::using('System.Util.TDataFieldAccessor');
  17  
  18  /**
  19   * TDataGridColumn class
  20   *
  21   * TDataGridColumn serves as the base class for the different column types of
  22   * the {@link TDataGrid} control.
  23   * TDataGridColumn defines the properties and methods that are common among
  24   * all datagrid column types. In particular, it initializes header and footer
  25   * cells according to {@link setHeaderText HeaderText} and {@link getHeaderStyle HeaderStyle}
  26   * {@link setFooterText FooterText} and {@link getFooterStyle FooterStyle} properties.
  27   * If {@link setHeaderImageUrl HeaderImageUrl} is specified, the image
  28   * will be displayed instead in the header cell.
  29   * The {@link getItemStyle ItemStyle} is applied to cells that belong to
  30   * non-header and -footer datagrid items.
  31   *
  32   * When the datagrid enables sorting, if the {@link setSortExpression SortExpression}
  33   * is not empty, the header cell will display a button (linkbutton or imagebutton)
  34   * that will bubble the sort command event to the datagrid.
  35   *
  36   * The following datagrid column types are provided by the framework currently,
  37   * - {@link TBoundColumn}, associated with a specific field in datasource and displays the corresponding data.
  38   * - {@link TEditCommandColumn}, displaying edit/update/cancel command buttons
  39   * - {@link TButtonColumn}, displaying generic command buttons that may be bound to specific field in datasource.
  40   * - {@link THyperLinkColumn}, displaying a hyperlink that may be bound to specific field in datasource.
  41   * - {@link TCheckBoxColumn}, displaying a checkbox that may be bound to specific field in datasource.
  42   * - {@link TTemplateColumn}, displaying content based on templates.
  43   *
  44   * To create your own column class, simply override {@link initializeCell()} method,
  45   * which is the major logic for managing the data and presentation of cells in the column.
  46   *
  47   * @author Qiang Xue <qiang.xue@gmail.com>
  48   * @version $Id: TDataGridColumn.php 1486 2006-11-03 13:22:08Z xue $
  49   * @package System.Web.UI.WebControls
  50   * @since 3.0
  51   */
  52  abstract class TDataGridColumn extends TApplicationComponent
  53  {
  54      private $_id='';
  55      private $_owner=null;
  56      private $_viewState=array();
  57  
  58      /**
  59       * @return string the ID of the column.
  60       */
  61  	public function getID()
  62      {
  63          return $this->_id;
  64      }
  65  
  66      /**
  67       * Sets the ID of the column.
  68       * By explicitly specifying the column ID, one can access the column
  69       * by $templateControl->ColumnID.
  70       * @param string the ID of the column.
  71       * @throws TInvalidDataValueException if the ID is of bad format
  72       */
  73  	public function setID($value)
  74      {
  75          if(!preg_match(TControl::ID_FORMAT,$value))
  76              throw new TInvalidDataValueException('datagridcolumn_id_invalid',get_class($this),$value);
  77          $this->_id=$value;
  78      }
  79  
  80      /**
  81       * @return string the text to be displayed in the header of this column
  82       */
  83  	public function getHeaderText()
  84      {
  85          return $this->getViewState('HeaderText','');
  86      }
  87  
  88      /**
  89       * @param string text to be displayed in the header of this column
  90       */
  91  	public function setHeaderText($value)
  92      {
  93          $this->setViewState('HeaderText',$value,'');
  94      }
  95  
  96      /**
  97       * @return string the url of the image to be displayed in header
  98       */
  99  	public function getHeaderImageUrl()
 100      {
 101          return $this->getViewState('HeaderImageUrl','');
 102      }
 103  
 104      /**
 105       * @param string the url of the image to be displayed in header
 106       */
 107  	public function setHeaderImageUrl($value)
 108      {
 109          $this->setViewState('HeaderImageUrl',$value,'');
 110      }
 111  
 112      /**
 113       * @param boolean whether to create a style if previously not existing
 114       * @return TTableItemStyle the style for header
 115       */
 116  	public function getHeaderStyle($createStyle=true)
 117      {
 118          if(($style=$this->getViewState('HeaderStyle',null))===null && $createStyle)
 119          {
 120              $style=new TTableItemStyle;
 121              $this->setViewState('HeaderStyle',$style,null);
 122          }
 123          return $style;
 124      }
 125  
 126      /**
 127       * @return string the text to be displayed in the footer of this column
 128       */
 129  	public function getFooterText()
 130      {
 131          return $this->getViewState('FooterText','');
 132      }
 133  
 134      /**
 135       * @param string text to be displayed in the footer of this column
 136       */
 137  	public function setFooterText($value)
 138      {
 139          $this->setViewState('FooterText',$value,'');
 140      }
 141  
 142      /**
 143       * @param boolean whether to create a style if previously not existing
 144       * @return TTableItemStyle the style for footer
 145       */
 146  	public function getFooterStyle($createStyle=true)
 147      {
 148          if(($style=$this->getViewState('FooterStyle',null))===null && $createStyle)
 149          {
 150              $style=new TTableItemStyle;
 151              $this->setViewState('FooterStyle',$style,null);
 152          }
 153          return $style;
 154      }
 155  
 156      /**
 157       * @param boolean whether to create a style if previously not existing
 158       * @return TTableItemStyle the style for item
 159       */
 160  	public function getItemStyle($createStyle=true)
 161      {
 162          if(($style=$this->getViewState('ItemStyle',null))===null && $createStyle)
 163          {
 164              $style=new TTableItemStyle;
 165              $this->setViewState('ItemStyle',$style,null);
 166          }
 167          return $style;
 168      }
 169  
 170      /**
 171       * @return string the name of the field or expression for sorting
 172       */
 173  	public function getSortExpression()
 174      {
 175          return $this->getViewState('SortExpression','');
 176      }
 177  
 178      /**
 179       * @param string the name of the field or expression for sorting
 180       */
 181  	public function setSortExpression($value)
 182      {
 183          $this->setViewState('SortExpression',$value,'');
 184      }
 185  
 186      /**
 187       * @return boolean whether the column is visible. Defaults to true.
 188       */
 189  	public function getVisible($checkParents=true)
 190      {
 191          return $this->getViewState('Visible',true);
 192      }
 193  
 194      /**
 195       * @param boolean whether the column is visible
 196       */
 197  	public function setVisible($value)
 198      {
 199          $this->setViewState('Visible',TPropertyValue::ensureBoolean($value),true);
 200      }
 201  
 202      /**
 203       * Returns a viewstate value.
 204       *
 205       * @param string the name of the viewstate value to be returned
 206       * @param mixed the default value. If $key is not found in viewstate, $defaultValue will be returned
 207       * @return mixed the viewstate value corresponding to $key
 208       */
 209  	protected function getViewState($key,$defaultValue=null)
 210      {
 211          return isset($this->_viewState[$key])?$this->_viewState[$key]:$defaultValue;
 212      }
 213  
 214      /**
 215       * Sets a viewstate value.
 216       *
 217       * Make sure that the viewstate value must be serializable and unserializable.
 218       * @param string the name of the viewstate value
 219       * @param mixed the viewstate value to be set
 220       * @param mixed default value. If $value===$defaultValue, the item will be cleared from the viewstate.
 221       */
 222  	protected function setViewState($key,$value,$defaultValue=null)
 223      {
 224          if($value===$defaultValue)
 225              unset($this->_viewState[$key]);
 226          else
 227              $this->_viewState[$key]=$value;
 228      }
 229  
 230      /**
 231       * Loads persistent state values.
 232       * @param mixed state values
 233       */
 234  	public function loadState($state)
 235      {
 236          $this->_viewState=$state;
 237      }
 238  
 239      /**
 240       * Saves persistent state values.
 241       * @return mixed values to be saved
 242       */
 243  	public function saveState()
 244      {
 245          return $this->_viewState;
 246      }
 247  
 248      /**
 249       * @return TDataGrid datagrid that owns this column
 250       */
 251  	public function getOwner()
 252      {
 253          return $this->_owner;
 254      }
 255  
 256      /**
 257       * @param TDataGrid datagrid object that owns this column
 258       */
 259  	public function setOwner(TDataGrid $value)
 260      {
 261          $this->_owner=$value;
 262      }
 263  
 264      /**
 265       * Initializes the column.
 266       * This method is invoked by {@link TDataGrid} when the column
 267       * is about to be used to initialize datagrid items.
 268       * Derived classes may override this method to do additional initialization.
 269       */
 270  	public function initialize()
 271      {
 272      }
 273  
 274      /**
 275       * Fetches the value of the data at the specified field.
 276       * If the data is an array, the field is used as an array key.
 277       * If the data is an of {@link TMap}, {@link TList} or their derived class,
 278       * the field is used as a key value.
 279       * If the data is a component, the field is used as the name of a property.
 280       * @param mixed data containing the field of value
 281       * @param string the data field
 282       * @return mixed data value at the specified field
 283       * @throws TInvalidDataValueException if the data or the field is invalid.
 284       */
 285  	protected function getDataFieldValue($data,$field)
 286      {
 287          return TDataFieldAccessor::getDataFieldValue($data,$field);
 288      }
 289  
 290  
 291      /**
 292       * Initializes the specified cell to its initial values.
 293       * The default implementation sets the content of header and footer cells.
 294       * If sorting is enabled by the grid and sort expression is specified in the column,
 295       * the header cell will show a link/image button. Otherwise, the header/footer cell
 296       * will only show static text/image.
 297       * This method can be overriden to provide customized intialization to column cells.
 298       * @param TTableCell the cell to be initialized.
 299       * @param integer the index to the Columns property that the cell resides in.
 300       * @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
 301       */
 302  	public function initializeCell($cell,$columnIndex,$itemType)
 303      {
 304          switch($itemType)
 305          {
 306              case TDataGrid::IT_HEADER:
 307                  $sortExpression=$this->getSortExpression();
 308                  $allowSorting=$sortExpression!=='' && (!$this->_owner || $this->_owner->getAllowSorting());
 309                  if($allowSorting)
 310                  {
 311                      if(($url=$this->getHeaderImageUrl())!=='')
 312                      {
 313                          $button=Prado::createComponent('System.Web.UI.WebControls.TImageButton');
 314                          $button->setImageUrl($url);
 315                          $button->setCommandName('Sort');
 316                          $button->setCommandParameter($sortExpression);
 317                          $button->setCausesValidation(false);
 318                          $cell->getControls()->add($button);
 319                      }
 320                      else if(($text=$this->getHeaderText())!=='')
 321                      {
 322                          $button=Prado::createComponent('System.Web.UI.WebControls.TLinkButton');
 323                          $button->setText($text);
 324                          $button->setCommandName('Sort');
 325                          $button->setCommandParameter($sortExpression);
 326                          $button->setCausesValidation(false);
 327                          $cell->getControls()->add($button);
 328                      }
 329                      else
 330                          $cell->setText('&nbsp;');
 331                  }
 332                  else
 333                  {
 334                      if(($url=$this->getHeaderImageUrl())!=='')
 335                      {
 336                          $image=Prado::createComponent('System.Web.UI.WebControls.TImage');
 337                          $image->setImageUrl($url);
 338                          $cell->getControls()->add($image);
 339                      }
 340                      else
 341                      {
 342                          if(($text=$this->getHeaderText())==='')
 343                              $text='&nbsp;';
 344                          $cell->setText($text);
 345                      }
 346                  }
 347                  break;
 348              case TDataGrid::IT_FOOTER:
 349                  if(($text=$this->getFooterText())!=='')
 350                      $cell->setText($text);
 351                  break;
 352          }
 353      }
 354  
 355      /**
 356       * Formats the text value according to a format string.
 357       * If the format string is empty, the original value is converted into
 358       * a string and returned.
 359       * If the format string starts with '#', the string is treated as a PHP expression
 360       * within which the token '{0}' is translated with the data value to be formated.
 361       * Otherwise, the format string and the data value are passed
 362       * as the first and second parameters in {@link sprintf}.
 363       * @param string format string
 364       * @param mixed the data to be formatted
 365       * @return string the formatted result
 366       */
 367  	protected function formatDataValue($formatString,$value)
 368      {
 369          if($formatString==='')
 370              return TPropertyValue::ensureString($value);
 371          else if($formatString[0]==='#')
 372          {
 373              $expression=strtr(substr($formatString,1),array('{0}'=>'$value'));
 374              try
 375              {
 376                  if(eval("\$result=$expression;")===false)
 377                      throw new Exception('');
 378                  return $result;
 379              }
 380              catch(Exception $e)
 381              {
 382                  throw new TInvalidDataValueException('datagridcolumn_expression_invalid',get_class($this),$expression,$e->getMessage());
 383              }
 384          }
 385          else
 386              return sprintf($formatString,$value);
 387      }
 388  }
 389  
 390  
 391  /**
 392   * TButtonColumnType class.
 393   * TButtonColumnType defines the enumerable type for the possible types of buttons
 394   * that can be used in a {@link TButtonColumn}.
 395   *
 396   * The following enumerable values are defined:
 397   * - LinkButton: link buttons
 398   * - PushButton: form buttons
 399   * - ImageButton: image buttons
 400   *
 401   * @author Qiang Xue <qiang.xue@gmail.com>
 402   * @version $Id: TDataGridColumn.php 1486 2006-11-03 13:22:08Z xue $
 403   * @package System.Web.UI.WebControls
 404   * @since 3.0.4
 405   */
 406  class TButtonColumnType extends TEnumerable
 407  {
 408      const LinkButton='LinkButton';
 409      const PushButton='PushButton';
 410      const ImageButton='ImageButton';
 411  }
 412  
 413  ?>