inc/classBrowser.php

   1 <?php
   2 /**
   3 * Table browser / lister class
   4 *
   5 * Browsers are constructed from BrowserColumns and can support sorting
   6 * and other interactive behaviour.  Cells may contain data which is
   7 * formatted as a link, or the entire row may be linked through an onclick
   8 * action.
   9 *
  10 * @package   awl
  11 * @subpackage   Browser
  12 * @author    Andrew McMillan <andrew@mcmillan.net.nz>
  13 * @copyright Catalyst IT Ltd, Morphoss Ltd <http://www.morphoss.com/>
  14 * @license   http://gnu.org/copyleft/gpl.html GNU GPL v2 or later
  15 */
  16
  17 require_once("AWLUtilities.php");
  18
  19 /**
  20 * Ensure that this is not set elsewhere.
  21 */
  22 $BrowserCurrentRow = (object) array();
  23
  24
  25
  26 /**
  27 * BrowserColumns are the basic building blocks.  You can specify just the
  28 * field name, and the column header or you can get fancy and specify an
  29 * alignment, format string, SQL formula and cell CSS class.
  30 * @package   awl
  31 */
  32 class BrowserColumn
  33 {
  34   var $Field;
  35   var $Header;
  36   var $Format;
  37   var $Sql;
  38   var $Align;
  39   var $Class;
  40   var $Type;
  41   var $Translatable;
  42   var $Hook;
  43   var $current_row;
  44
  45   /**
  46   * BrowserColumn constructor.  Only the first parameter is mandatory.
  47   *
  48   * @param string field The name of the column in the SQL result.
  49   * @param string header The text to appear in the column header on output
  50   *                      (@see BrowserColumn::RenderHeader()).  If this is not supplied then
  51   *                      a default of the field name will be used.
  52   * @param string align left|center|right - text alignment.  Defaults to 'left'.
  53   * @param string format A format (a-la-printf) to render data values within.
  54   *                      (@see BrowserColumn::RenderValue()).  If this is not supplied
  55   *                      then the default will ensure the column value is displayed as-is.
  56   * @param string sql Some SQL which will return the desired value to be presented as column 'field' of
  57   *                   the result. If this is blank then the column is assumed to be a real data column.
  58   * @param string class Additional classes to apply to the column header and column value cells.
  59   * @param string datatype This will allow 'date' or 'timestamp' to preformat the field correctly before
  60   *                        using it in replacements or display.  Other types may be added in future.
  61   * @param string $hook The name of a global function which will preprocess the column value
  62   *
  63   * The hook function should be defined as follows:
  64   *   function hookfunction( $column_value, $column_name, $database_row ) {
  65   *     ...
  66   *     return $value;
  67   *   }
  68   */
  69   function BrowserColumn( $field, $header="", $align="", $format="", $sql="", $class="", $datatype="", $hook=null ) {
  70     $this->Field  = $field;
  71     $this->Sql    = $sql;
  72     $this->Header = $header;
  73     $this->Format = $format;
  74     $this->Class  = $class;
  75     $this->Align  = $align;
  76     $this->Type   = $datatype;
  77     $this->Translatable = false;
  78     $this->Hook   = $hook;
  79   }
  80
  81   /**
  82   * GetTarget
  83   *
  84   * Retrieves a 'field' or '...SQL... AS field' definition for the target list of the SQL.
  85   */
  86   function GetTarget() {
  87     if ( $this->Sql == "" ) return $this->Field;
  88     return "$this->Sql AS $this->Field";
  89   }
  90
  91   /**
  92   * RenderHeader
  93   * Renders the column header cell for this column.  This will be rendered as a <th>...</th>
  94   * with class and alignment applied to it.  Browser column headers are clickable, and the
  95   * ordering will also display an 'up' or 'down' triangle with the column header that the SQL
  96   * is sorted on at the moment.
  97   *
  98   * @param string order_field The name of the field currently being sorted on.
  99   * @param string order_direction Whether the sort is Ascending or Descending.
 100   * @param int browser_array_key Used this to help handle separate ordering of
 101   *                              multiple browsers on the same page.
 102   * @param string forced_order If true, then we don't allow order to be changed.
 103   */
 104   function RenderHeader( $order_field, $order_direction, $browser_array_key=0, $forced_order=false ) {
 105     global $c;
 106     if ( $this->Align == "" ) $this->Align = "left";
 107     $html = '<th class="'.$this->Align.'" '. ($this->Class == "" ? "" : "class=\"$this->Class\"") . '>';
 108
 109     $direction = 'A';
 110     $image = "";
 111     if ( !$forced_order && $order_field == $this->Field ) {
 112       if ( strtoupper( substr( $order_direction, 0, 1) ) == 'A' ) {
 113         $image = 'down';
 114         $direction = 'D';
 115       }
 116       else {
 117         $image = 'up';
 118       }
 119       $image = "<img class=\"order\" src=\"$c->images/$image.gif\" alt=\"$image\" />";
 120     }
 121     if ( !isset($browser_array_key) || $browser_array_key == '' ) $browser_array_key = 0;
 122     if ( !$forced_order ) $html .= '<a href="'.replace_uri_params( $_SERVER['REQUEST_URI'], array( "o[$browser_array_key]" => $this->Field, "d[$browser_array_key]" => $direction ) ).'" class="order">';
 123     $html .= ($this->Header == "" ? $this->Field : $this->Header);
 124     if ( !$forced_order ) $html .= "$image</a>";
 125     $html .= "</th>\n";
 126     return $html;
 127   }
 128
 129   function SetTranslatable() {
 130     $this->Translatable = true;
 131   }
 132
 133   function RenderValue( $value, $extraclass = "" ) {
 134     global $session;
 135
 136     if ( $this->Type == 'date' || $this->Type == 'timestamp') {
 137       $value = $session->FormattedDate( $value, $this->Type );
 138     }
 139
 140     if ( $this->Hook && function_exists($this->Hook) ) {
 141       dbg_error_log( "Browser", ":Browser: Hook for $this->Hook on column $this->Field");
 142       $value = call_user_func( $this->Hook, $value, $this->Field, $this->current_row );
 143     }
 144
 145     if ( $this->Translatable ) {
 146       $value = translate($value);
 147     }
 148
 149     $value = str_replace( "\n", "<br />", $value );
 150     if ( substr(strtolower($this->Format),0,3) == "<td" ) {
 151       $html = sprintf($this->Format,$value);
 152     }
 153     else {
 154       // These quite probably don't work.  The CSS standard for multiple classes is 'class="a b c"' but is lightly
 155       // implemented according to some web references.  Perhaps modern browsers are better?
 156       $class = $this->Align . ($this->Class == "" ? "" : " $this->Class") . ($extraclass == "" ? "" : " $extraclass");
 157       if ( $class != "" ) $class = ' class="'.$class.'"';
 158       $html = sprintf('<td%s>',$class);
 159       $html .= ($this->Format == "" ? $value : sprintf($this->Format,$value,$value));
 160       $html .= "</td>\n";
 161     }
 162     return $html;
 163   }
 164 }
 165
 166
 167 /**
 168 * Start a new Browser, add columns, set a join and Render it to create a basic
 169 * list of records in a table.
 170 * You can, of course, get a lot fancier with setting ordering, where clauses
 171 * totalled columns and so forth.
 172 * @package   awl
 173 */
 174 class Browser
 175 {
 176   var $Title;
 177   var $SubTitle;
 178   var $FieldNames;
 179   var $Columns;
 180   var $HiddenColumns;
 181   var $Joins;
 182   var $Where;
 183   var $Distinct;
 184   var $Union;
 185   var $Order;
 186   var $OrderField;
 187   var $OrderDirection;
 188   var $OrderBrowserKey;
 189   var $ForcedOrder;
 190   var $Grouping;
 191   var $Limit;
 192   var $Offset;
 193   var $Query;
 194   var $BeginRow;
 195   var $CloseRow;
 196   var $BeginRowArgs;
 197   var $Totals;
 198   var $TotalFuncs;
 199   var $ExtraRows;
 200   var $match_column;
 201   var $match_value;
 202   var $match_function;
 203   var $DivOpen;
 204   var $DivClose;
 205
 206   /**
 207   * The Browser class constructor
 208   *
 209   * @param string $title A title for the browser (optional).
 210   */
 211   function Browser( $title = "" ) {
 212     global $c;
 213     $this->Title = $title;
 214     $this->SubTitle = "";
 215     $this->Distinct = "";
 216     $this->Order = "";
 217     $this->Limit = "";
 218     $this->Offset = "";
 219     $this->BeginRow = "<tr class=\"row%d\">\n";
 220     $this->CloseRow = "</tr>\n";
 221     $this->BeginRowArgs = array('#even');
 222     $this->Totals = array();
 223     $this->Columns = array();
 224     $this->HiddenColumns = array();
 225     $this->FieldNames = array();
 226     $this->DivOpen = '<div id="browser">';
 227     $this->DivClose = '</div>';
 228     $this->ForcedOrder = false;
 229     dbg_error_log( "Browser", ":Browser: New browser called $title");
 230   }
 231
 232   /**
 233   * Add a column to the Browser.
 234   *
 235   * This constructs a new BrowserColumn, appending it to the array of columns
 236   * in this Browser.
 237   *
 238   * Note that if the $format parameter starts with '<td>' the format will replace
 239   * the column format, otherwise it will be used within '<td>...</td>' tags.
 240   * @see BrowserColumn
 241   *
 242   * @param string $field The name of the field.
 243   * @param string $header A column header for the field.
 244   * @param string $align An alignment for column values.
 245   * @param string $format A sprintf format for displaying column values.
 246   * @param string $sql An SQL fragment for calculating the value.
 247   * @param string $class A CSS class to apply to the cells of this column.
 248   * @param string $hook The name of a global function which will preprocess the column value
 249   *
 250   * The hook function should be defined as follows:
 251   *   function hookfunction( $column_value, $column_name, $database_row ) {
 252   *     ...
 253   *     return $value;
 254   *   }
 255   *
 256   */
 257   function AddColumn( $field, $header="", $align="", $format="", $sql="", $class="", $datatype="", $hook=null ) {
 258     $this->Columns[] = new BrowserColumn( $field, $header, $align, $format, $sql, $class, $datatype, $hook );
 259     $this->FieldNames[$field] = count($this->Columns) - 1;
 260   }
 261
 262   /**
 263   * Add a hidden column - one that is present in the SQL result, but for
 264   * which there is no column displayed.
 265   *
 266   * This can be useful for including a value in (e.g.) clickable links or title
 267   * attributes which is not actually displayed as a visible column.
 268   *
 269   * @param string $field The name of the field.
 270   * @param string $sql An SQL fragment to calculate the field, if it is calculated.
 271   */
 272   function AddHidden( $field, $sql="" ) {
 273     $this->HiddenColumns[] = new BrowserColumn( $field, "", "", "", $sql );
 274     $this->FieldNames[$field] = count($this->Columns) - 1;
 275   }
 276
 277   /**
 278   * Set the Title for the browse.
 279   *
 280   * This can also be set in the constructor but if you create a template Browser
 281   * and then clone it in a loop you may want to assign a different Title for each
 282   * instance.
 283   *
 284   * @param string $new_title The new title for the browser
 285   */
 286   function SetTitle( $new_title ) {
 287     $this->Title = $new_title;
 288   }
 289
 290
 291   /**
 292   * Accessor for the Title for the browse, which could set the title also.
 293   *
 294   * @param string $new_title The new title for the browser
 295   * @return string The current title for the browser
 296   */
 297   function Title( $new_title = null ) {
 298     if ( isset($new_title) ) $this->Title = $new_title;
 299     return $this->Title;
 300   }
 301
 302
 303   /**
 304   * Set the named columns to be translatable
 305   *
 306   * @param array $column_list The list of columns which are translatable
 307   */
 308   function SetTranslatable( $column_list ) {
 309     $top = count($this->Columns);
 310     for( $i=0; $i < $top; $i++ ) {
 311       dbg_error_log( "Browser", "Comparing %s with column name list", $this->Columns[$i]->Field);
 312       if ( in_array($this->Columns[$i]->Field,$column_list) ) $this->Columns[$i]->SetTranslatable();
 313     }
 314     $top = count($this->HiddenColumns);
 315     for( $i=0; $i < $top; $i++ ) {
 316       dbg_error_log( "Browser", "Comparing %s with column name list", $this->HiddenColumns[$i]->Field);
 317       if ( in_array($this->HiddenColumns[$i]->Field,$column_list) ) $this->HiddenColumns[$i]->SetTranslatable();
 318     }
 319   }
 320
 321   /**
 322   * Set a Sub Title for the browse.
 323   *
 324   * @param string $sub_title The sub title string
 325   */
 326   function SetSubTitle( $sub_title ) {
 327     $this->SubTitle = $sub_title;
 328   }
 329
 330   /**
 331   * Set a div for wrapping the browse.
 332   *
 333   * @param string $open_div The HTML to open the div
 334   * @param string $close_div The HTML to open the div
 335   */
 336   function SetDiv( $open_div, $close_div ) {
 337     $this->DivOpen = $open_div;
 338     $this->DivClose = $close_div;
 339   }
 340
 341   /**
 342   * Set the tables and joins for the SQL.
 343   *
 344   * For a single table this should just contain the name of that table, but for
 345   * multiple tables it should be the full content of the SQL 'FROM ...' clause
 346   * (excluding the actual 'FROM' keyword).
 347   *
 348   * @param string $join_list
 349   */
 350   function SetJoins( $join_list ) {
 351     $this->Joins = $join_list;
 352   }
 353
 354   /**
 355   * Set a Union SQL statement.
 356   *
 357   * In rare cases this might be useful.  It's currently a fairly simple hack
 358   * which requires you to put an entire valid (& matching) UNION subclause
 359   * (although without the UNION keyword).
 360   *
 361   * @param string $union_select
 362   */
 363   function SetUnion( $union_select ) {
 364     $this->Union = $union_select;
 365   }
 366
 367   /**
 368   * Set the SQL Where clause to a specific value.
 369   *
 370   * The WHERE keyword should not be included.
 371   *
 372   * @param string $where_clause A valide SQL WHERE ... clause.
 373   */
 374   function SetWhere( $where_clause ) {
 375     $this->Where = $where_clause;
 376   }
 377
 378   /**
 379   * Set the SQL DISTINCT clause to a specific value.
 380   *
 381   * The whole clause (except the keyword) needs to be supplied
 382   *
 383   * @param string $distinct The whole clause, after 'DISTINCT'
 384   */
 385   function SetDistinct( $distinct ) {
 386     $this->Distinct = "DISTINCT ".$distinct;
 387   }
 388
 389   /**
 390   * Set the SQL LIMIT clause to a specific value.
 391   *
 392   * Only the limit number should be supplied.
 393   *
 394   * @param int $limit_n A number of rows to limit the SQL selection to
 395   */
 396   function SetLimit( $limit_n ) {
 397     $this->Limit = "LIMIT ".intval($limit_n);
 398   }
 399
 400   /**
 401   * Set the SQL OFFSET clause to a specific value.
 402   *
 403   * Only the offset number
 404   *
 405   * @param int $offset_n A number of rows to offset the SQL selection to, based from the start of the results.
 406   */
 407   function SetOffset( $offset_n ) {
 408     $this->Offset = "OFFSET ".intval($offset_n);
 409   }
 410
 411   /**
 412   * Add an [operator] ... to the SQL Where clause
 413   *
 414   * You will generally want to call OrWhere or AndWhere rather than
 415   * this function, but hey: who am I to tell you how to code!
 416   *
 417   * @param string $operator The operator to combine with previous where clause parts.
 418   * @param string $more_where The extra part of the where clause
 419   */
 420   function MoreWhere( $operator, $more_where ) {
 421     if ( $this->Where == "" ) {
 422       $this->Where = $more_where;
 423       return;
 424     }
 425     $this->Where = "$this->Where $operator $more_where";
 426   }
 427
 428   /**
 429   * Add an OR ...  to the SQL Where clause
 430   *
 431   * @param string $more_where The extra part of the where clause
 432   */
 433   function AndWhere( $more_where ) {
 434     $this->MoreWhere("AND",$more_where);
 435   }
 436
 437   /**
 438   * Add an OR ... to the SQL Where clause
 439   *
 440   * @param string $more_where The extra part of the where clause
 441   */
 442   function OrWhere( $more_where ) {
 443     $this->MoreWhere("OR",$more_where);
 444   }
 445
 446   function AddGrouping( $field, $browser_array_key=0 ) {
 447     if ( $this->Grouping == "" )
 448       $this->Grouping = "GROUP BY ";
 449     else
 450       $this->Grouping .= ", ";
 451
 452     $this->Grouping .= clean_string($field);
 453   }
 454
 455
 456   /**
 457   * Add an ordering to the browser widget.
 458   *
 459   * The ordering can be overridden by GET parameters which will be
 460   * rendered into the column headers so that a user can click on
 461   * the column headers to control the actual order.
 462   *
 463   * @param string $field The name of the field to be ordered by.
 464   * @param string $direction A for Ascending, otherwise it will be descending order.
 465   * @param string $browser_array_key Use this to distinguish between multiple
 466   *               browser widgets on the same page.  Leave it empty if you only
 467   *               have a single browser instance.
 468   * @param string $secondary Use this to indicate a default secondary order
 469   *               which shouldn't interfere with the default primary order.
 470   */
 471   function AddOrder( $field, $direction, $browser_array_key=0, $secondary=0 ) {
 472     $field = check_by_regex($field,'/^[^\'"!\\\\()\[\]|*\/{}&%@~;:?<>]+$/');
 473     if ( ! isset($this->FieldNames[$field]) ) return;
 474
 475     if ( !isset($this->Order) || $this->Order == "" )
 476       $this->Order = "ORDER BY ";
 477     else
 478       $this->Order .= ", ";
 479
 480     if ( $secondary == 0 ) {
 481       $this->OrderField = $field;
 482       $this->OrderBrowserKey = $browser_array_key;
 483     }
 484     $this->Order .= $field;
 485
 486     if ( preg_match( '/^A/i', $direction) ) {
 487       $this->Order .= " ASC";
 488       if ( $secondary == 0)
 489         $this->OrderDirection = 'A';
 490     }
 491     else {
 492       $this->Order .= " DESC";
 493       if ( $secondary == 0)
 494         $this->OrderDirection = 'D';
 495     }
 496   }
 497
 498
 499   /**
 500   * Force a particular ordering onto the browser widget.
 501   *
 502   * @param string $field The name of the field to be ordered by.
 503   * @param string $direction A for Ascending, otherwise it will be descending order.
 504   */
 505   function ForceOrder( $field, $direction ) {
 506     $field = clean_string($field);
 507     if ( ! isset($this->FieldNames[$field]) ) return;
 508
 509     if ( $this->Order == "" )
 510       $this->Order = "ORDER BY ";
 511     else
 512       $this->Order .= ", ";
 513
 514     $this->Order .= $field;
 515
 516     if ( preg_match( '/^A/i', $direction) ) {
 517       $this->Order .= " ASC";
 518     }
 519     else {
 520       $this->Order .= " DESC";
 521     }
 522
 523     $this->ForcedOrder = true;
 524   }
 525
 526
 527   /**
 528   * Set up the ordering for the browser.  Generally you should call this with
 529   * the first parameter set as a field to order by default.  Call with the second
 530   * parameter set to 'D' or 'DESCEND' if you want to reverse the default order.
 531   */
 532   function SetOrdering( $default_fld=null, $default_dir='A' , $browser_array_key=0 ) {
 533     if ( isset( $_GET['o'][$browser_array_key] ) && isset($_GET['d'][$browser_array_key] ) ) {
 534       $this->AddOrder( $_GET['o'][$browser_array_key], $_GET['d'][$browser_array_key], $browser_array_key );
 535     }
 536     else {
 537       if ( ! isset($default_fld) ) $default_fld = $this->Columns[0];
 538       $this->AddOrder( $default_fld, $default_dir, $browser_array_key );
 539     }
 540   }
 541
 542
 543   /**
 544   * Mark a column as something to be totalled.  You can also specify the name of
 545   * a function which may modify the value before the actual totalling.
 546   *
 547   * The callback function will be called with each row, with the first argument
 548   * being the entire record object and the second argument being only the column
 549   * being totalled.  The callback should return a number, to be added to the total.
 550   *
 551   * @param string $column_name The name of the column to be totalled.
 552   * @param string $total_function The name of the callback function.
 553   */
 554   function AddTotal( $column_name, $total_function = false ) {
 555     $this->Totals[$column_name] = 0;
 556     if ( $total_function != false ) {
 557       $this->TotalFuncs[$column_name] = $total_function;
 558     }
 559   }
 560
 561
 562   /**
 563   * Retrieve the total from a totalled column
 564   *
 565   * @param string $column_name The name of the column to be totalled.
 566   */
 567   function GetTotal( $column_name ) {
 568     return $this->Totals[$column_name];
 569   }
 570
 571
 572   /**
 573   * Set the format for an output row.
 574   *
 575   * The row format is set as an sprintf format string for the start of the row,
 576   * and a plain text string for the close of the row.  Subsequent arguments
 577   * are interpreted as names of fields, the values of which will be sprintf'd
 578   * into the beginrow string for each row.
 579   *
 580   * Some special field names exist beginning with the '#' character which have
 581   * 'magic' functionality, including '#even' which will insert '0' for even
 582   * rows and '1' for odd rows, allowing a nice colour alternation if the
 583   * beginrow format refers to it like: 'class="r%d"' so that even rows will
 584   * become 'class="r0"' and odd rows will be 'class="r1"'.
 585   *
 586   * At present only '#even' exists, although other magic values may be defined
 587   * in future.
 588   *
 589   * @param string $beginrow The new printf format for the start of the row.
 590   * @param string $closerow The new string for the close of the row.
 591   * @param string $rowargs ... The row arguments which will be sprintf'd into
 592   * the $beginrow format for each row
 593   */
 594   function RowFormat( $beginrow, $closerow, $rowargs )
 595   {
 596     $argc = func_num_args();
 597     $this->BeginRow = func_get_arg(0);
 598     $this->CloseRow = func_get_arg(1);
 599
 600     $this->BeginRowArgs = array();
 601     for( $i=2; $i < $argc; $i++ ) {
 602       $this->BeginRowArgs[] = func_get_arg($i);
 603     }
 604   }
 605
 606
 607   /**
 608   * This method is used to build and execute the database query.
 609   *
 610   * You need not call this method, since Browser::Render() will call it for
 611   * you if you have not done so at that point.
 612   *
 613   * @return boolean The success / fail status of the AwlQuery::Exec()
 614   */
 615   function DoQuery() {
 616     $target_fields = "";
 617     foreach( $this->Columns AS $k => $column ) {
 618       if ( $target_fields != "" ) $target_fields .= ", ";
 619       $target_fields .= $column->GetTarget();
 620     }
 621     if ( isset($this->HiddenColumns) ) {
 622       foreach( $this->HiddenColumns AS $k => $column ) {
 623         if ( $target_fields != "" ) $target_fields .= ", ";
 624         $target_fields .= $column->GetTarget();
 625       }
 626     }
 627     $where_clause = ((isset($this->Where) && $this->Where != "") ? "WHERE $this->Where" : "" );
 628     $sql = sprintf( "SELECT %s %s FROM %s %s %s ", $this->Distinct, $target_fields,
 629                  $this->Joins, $where_clause, $this->Grouping );
 630     if ( "$this->Union" != "" ) {
 631       $sql .= "UNION $this->Union ";
 632     }
 633     $sql .= $this->Order . ' ' . $this->Limit . ' ' . $this->Offset;
 634     $this->Query = new AwlQuery( $sql );
 635     return $this->Query->Exec("Browse:$this->Title:DoQuery");
 636   }
 637
 638
 639   /**
 640   * Add an extra arbitrary row onto the end of the browser.
 641   *
 642   * @var array $column_values Contains an array of named fields, hopefully matching the column names.
 643   */
 644   function AddRow( $column_values ) {
 645     if ( !isset($this->ExtraRows) || typeof($this->ExtraRows) != 'array' ) $this->ExtraRows = array();
 646     $this->ExtraRows[] = &$column_values;
 647   }
 648
 649
 650   /**
 651   * Replace a row where $column = $value with an extra arbitrary row, returned from calling $function
 652   *
 653   * @param string $column The name of a column to match
 654   * @param string $value  The value to match in the column
 655   * @param string $function The name of the function to call for the matched row
 656   */
 657   function MatchedRow( $column, $value, $function ) {
 658     $this->match_column = $column;
 659     $this->match_value  = $value;
 660     $this->match_function = $function;
 661   }
 662
 663
 664   /**
 665   * Return values from the current row for replacing into a template.
 666   *
 667   * This is used to return values from the current row, so they can
 668   * be inserted into a row template.  It is used as a callback
 669   * function for preg_replace_callback.
 670   *
 671   * @param array of string $matches An array containing a field name as offset 1
 672   */
 673   function ValueReplacement($matches)
 674   {
 675     // as usual: $matches[0] is the complete match
 676     // $matches[1] the match for the first subpattern
 677     // enclosed in '##...##' and so on
 678
 679     $field_name = $matches[1];
 680     if ( !isset($this->current_row->{$field_name}) && substr($field_name,0,4) == "URL:" ) {
 681       $field_name = substr($field_name,4);
 682       $replacement = urlencode($this->current_row->{$field_name});
 683     }
 684     else {
 685       $replacement = (isset($this->current_row->{$field_name}) ? $this->current_row->{$field_name} : '');
 686     }
 687     dbg_error_log( "Browser", ":ValueReplacement: Replacing %s with %s", $field_name, $replacement);
 688     return $replacement;
 689   }
 690
 691
 692   /**
 693   * This method is used to render the browser as HTML.  If the query has
 694   * not yet been executed then this will call DoQuery to do so.
 695   *
 696   * The browser (including the title) will be displayed in a div with id="browser" so
 697   * that you can style '#browser tr.header', '#browser tr.totals' and so forth.
 698   *
 699   * @param string $title_tag The tag to use around the browser title (default 'h1')
 700   * @return string The rendered HTML fragment to display to the user.
 701   */
 702   function Render( $title_tag = null, $subtitle_tag = null ) {
 703     global $c, $BrowserCurrentRow;
 704
 705     if ( !isset($this->Query) ) $this->DoQuery();  // Ensure the query gets run before we render!
 706
 707     dbg_error_log( "Browser", ":Render: browser $this->Title");
 708     $html = $this->DivOpen;
 709     if ( $this->Title != "" ) {
 710       if ( !isset($title_tag) ) $title_tag = 'h1';
 711       $html .= "<$title_tag>$this->Title</$title_tag>\n";
 712     }
 713     if ( $this->SubTitle != "" ) {
 714       if ( !isset($subtitle_tag) ) $subtitle_tag = 'h2';
 715       $html .= "<$subtitle_tag>$this->SubTitle</$subtitle_tag>\n";
 716     }
 717
 718     $html .= "<table id=\"browse_table\">\n";
 719     $html .= "<thead><tr class=\"header\">\n";
 720     foreach( $this->Columns AS $k => $column ) {
 721       $html .= $column->RenderHeader( $this->OrderField, $this->OrderDirection, $this->OrderBrowserKey, $this->ForcedOrder );
 722     }
 723     $html .= "</tr></thead>\n<tbody>";
 724
 725     $rowanswers = array();
 726     while( $BrowserCurrentRow = $this->Query->Fetch() ) {
 727
 728       // Work out the answers to any stuff that may be being substituted into the row start
 729       /** @TODO: We should deprecate this approach in favour of simply doing the ValueReplacement on field names */
 730       foreach( $this->BeginRowArgs AS $k => $fld ) {
 731         if ( isset($BrowserCurrentRow->{$fld}) ) {
 732           $rowanswers[$k] = $BrowserCurrentRow->{$fld};
 733         }
 734         else {
 735           switch( $fld ) {
 736             case '#even':
 737               $rowanswers[$k] = ($this->Query->rownum() % 2);
 738               break;
 739             default:
 740               $rowanswers[$k] = $fld;
 741           }
 742         }
 743       }
 744       // Start the row
 745       $row_html = vsprintf( preg_replace("/#@even@#/", ($this->Query->rownum() % 2), $this->BeginRow), $rowanswers);
 746
 747       if ( isset($this->match_column) && isset($this->match_value) && $BrowserCurrentRow->{$this->match_column} == $this->match_value ) {
 748         $row_html .= call_user_func( $this->match_function, $BrowserCurrentRow );
 749       }
 750       else {
 751         // Each column
 752         foreach( $this->Columns AS $k => $column ) {
 753           $row_html .= $column->RenderValue( (isset($BrowserCurrentRow->{$column->Field})?$BrowserCurrentRow->{$column->Field}:'') );
 754           if ( isset($this->Totals[$column->Field]) ) {
 755             if ( isset($this->TotalFuncs[$column->Field]) && function_exists($this->TotalFuncs[$column->Field]) ) {
 756               // Run the amount through the callback function  $floatval = my_function( $row, $fieldval );
 757               $this->Totals[$column->Field] += $this->TotalFuncs[$column->Field]( $BrowserCurrentRow, $BrowserCurrentRow->{$column->Field} );
 758             }
 759             else {
 760               // Just add the amount
 761               $this->Totals[$column->Field] += doubleval( preg_replace( '/[^0-9.-]/', '', $BrowserCurrentRow->{$column->Field} ));
 762             }
 763           }
 764         }
 765       }
 766
 767       // Finish the row
 768       $row_html .= preg_replace("/#@even@#/", ($this->Query->rownum() % 2), $this->CloseRow);
 769       $this->current_row = $BrowserCurrentRow;
 770       $html .= preg_replace_callback("/##([^#]+)##/", array( &$this, "ValueReplacement"), $row_html );
 771     }
 772
 773     if ( count($this->Totals) > 0 ) {
 774       $BrowserCurrentRow = (object) "";
 775       $row_html = "<tr class=\"totals\">\n";
 776       foreach( $this->Columns AS $k => $column ) {
 777         if ( isset($this->Totals[$column->Field]) ) {
 778           $row_html .= $column->RenderValue( $this->Totals[$column->Field], "totals" );
 779         }
 780         else {
 781           $row_html .= $column->RenderValue( "" );
 782         }
 783       }
 784       $row_html .= "</tr>\n";
 785       $this->current_row = $BrowserCurrentRow;
 786       $html .= preg_replace_callback("/##([^#]+)##/", array( &$this, "ValueReplacement"), $row_html );
 787     }
 788
 789
 790     if ( count($this->ExtraRows) > 0 ) {
 791       foreach( $this->ExtraRows AS $k => $v ) {
 792         $BrowserCurrentRow = (object) $v;
 793         // Work out the answers to any stuff that may be being substituted into the row start
 794         foreach( $this->BeginRowArgs AS $k => $fld ) {
 795           if ( isset( $BrowserCurrentRow->{$fld} ) ) {
 796             $rowanswers[$k] = $BrowserCurrentRow->{$fld};
 797           }
 798           else {
 799             switch( $fld ) {
 800               case '#even':
 801                 $rowanswers[$k] = ($this->Query->rownum() % 2);
 802                 break;
 803               default:
 804                 $rowanswers[$k] = $fld;
 805             }
 806           }
 807         }
 808
 809         // Start the row
 810         $row_html = vsprintf( preg_replace("/#@even@#/", ($this->Query->rownum() % 2), $this->BeginRow), $rowanswers);
 811
 812         if ( isset($this->match_column) && isset($this->match_value) && $BrowserCurrentRow->{$this->match_column} == $this->match_value ) {
 813           $row_html .= call_user_func( $this->match_function, $BrowserCurrentRow );
 814         }
 815         else {
 816           // Each column
 817           foreach( $this->Columns AS $k => $column ) {
 818             $row_html .= $column->RenderValue( (isset($BrowserCurrentRow->{$column->Field}) ? $BrowserCurrentRow->{$column->Field} : '') );
 819           }
 820         }
 821
 822         // Finish the row
 823         $row_html .= preg_replace("/#@even@#/", ($this->Query->rownum() % 2), $this->CloseRow);
 824         $this->current_row = $BrowserCurrentRow;
 825         $html .= preg_replace_callback("/##([^#]+)##/", array( &$this, "ValueReplacement"), $row_html );
 826       }
 827     }
 828
 829     $html .= "</tbody>\n</table>\n";
 830     $html .= $this->DivClose;
 831
 832     return $html;
 833   }
 834
 835 }