Class Browser

Description

Start a new Browser, add columns, set a join and Render it to create a basic list of records in a table.

You can, of course, get a lot fancier with setting ordering, where clauses totalled columns and so forth.

Located in /classBrowser.php (line 174)


	
			
Variable Summary
 mixed $BeginRow
 mixed $CloseRow
 mixed $Columns
 mixed $Distinct
 mixed $DivClose
 mixed $DivOpen
 mixed $ExtraRows
 mixed $FieldNames
 mixed $ForcedOrder
 mixed $Grouping
 mixed $Joins
 mixed $Limit
 mixed $match_value
 mixed $Offset
 mixed $Order
 mixed $OrderField
 mixed $Query
 mixed $SubTitle
 mixed $Title
 mixed $TotalFuncs
 mixed $Totals
 mixed $Union
 mixed $Where
Method Summary
 Browser Browser ([string $title = ""])
 void AddColumn (string $field, [string $header = ""], [string $align = ""], [string $format = ""], [string $sql = ""], [string $class = ""], [ $datatype = ""], [string $hook = null])
 void AddGrouping ( $field, [ $browser_array_key = 0])
 void AddHidden (string $field, [string $sql = ""])
 void AddOrder (string $field, string $direction, [string $browser_array_key = 0], [string $secondary = 0])
 void AddRow ( $column_values)
 void AddTotal (string $column_name, [string $total_function = false])
 void AndWhere (string $more_where)
 boolean DoQuery ()
 void ForceOrder (string $field, string $direction)
 void GetTotal (string $column_name)
 void MatchedRow (string $column, string $value, string $function)
 void MoreWhere (string $operator, string $more_where)
 void OrWhere (string $more_where)
 string Render ([string $title_tag = null], [ $subtitle_tag = null])
 void RowFormat (string $beginrow, string $closerow, string $rowargs)
 void SetDistinct (string $distinct)
 void SetDiv (string $open_div, string $close_div)
 void SetJoins (string $join_list)
 void SetLimit (int $limit_n)
 void SetOffset (int $offset_n)
 void SetOrdering ([ $default_fld = null], [ $default_dir = 'A'], [ $browser_array_key = 0])
 void SetSubTitle (string $sub_title)
 void SetTitle (string $new_title)
 void SetTranslatable (array $column_list)
 void SetUnion (string $union_select)
 void SetWhere (string $where_clause)
 string Title ([string $new_title = null])
 void ValueReplacement (array $matches)
Variables
mixed $BeginRow (line 194)
mixed $BeginRowArgs (line 196)
mixed $CloseRow (line 195)
mixed $Columns (line 179)
mixed $Distinct (line 183)
mixed $DivClose (line 204)
mixed $DivOpen (line 203)
mixed $ExtraRows (line 199)
mixed $FieldNames (line 178)
mixed $ForcedOrder (line 189)
mixed $Grouping (line 190)
mixed $HiddenColumns (line 180)
mixed $Joins (line 181)
mixed $Limit (line 191)
mixed $match_column (line 200)
mixed $match_function (line 202)
mixed $match_value (line 201)
mixed $Offset (line 192)
mixed $Order (line 185)
mixed $OrderBrowserKey (line 188)
mixed $OrderDirection (line 187)
mixed $OrderField (line 186)
mixed $Query (line 193)
mixed $SubTitle (line 177)
mixed $Title (line 176)
mixed $TotalFuncs (line 198)
mixed $Totals (line 197)
mixed $Union (line 184)
mixed $Where (line 182)
Methods
Constructor Browser (line 211)

The Browser class constructor

Browser Browser ([string $title = ""])
  • string $title: A title for the browser (optional).
AddColumn (line 257)

Add a column to the Browser.

This constructs a new BrowserColumn, appending it to the array of columns in this Browser.

Note that if the $format parameter starts with '<td>' the format will replace the column format, otherwise it will be used within '<td>...</td>' tags.

void AddColumn (string $field, [string $header = ""], [string $align = ""], [string $format = ""], [string $sql = ""], [string $class = ""], [ $datatype = ""], [string $hook = null])
  • string $field: The name of the field.
  • string $header: A column header for the field.
  • string $align: An alignment for column values.
  • string $format: A sprintf format for displaying column values.
  • string $sql: An SQL fragment for calculating the value.
  • string $class: A CSS class to apply to the cells of this column.
  • string $hook:

    The name of a global function which will preprocess the column value

    The hook function should be defined as follows: function hookfunction( $column_value, $column_name, $database_row ) { ... return $value; }

  • $datatype
AddGrouping (line 446)
void AddGrouping ( $field, [ $browser_array_key = 0])
  • $field
  • $browser_array_key
AddHidden (line 272)

Add a hidden column - one that is present in the SQL result, but for which there is no column displayed.

This can be useful for including a value in (e.g.) clickable links or title attributes which is not actually displayed as a visible column.

void AddHidden (string $field, [string $sql = ""])
  • string $field: The name of the field.
  • string $sql: An SQL fragment to calculate the field, if it is calculated.
AddOrder (line 471)

Add an ordering to the browser widget.

The ordering can be overridden by GET parameters which will be rendered into the column headers so that a user can click on the column headers to control the actual order.

void AddOrder (string $field, string $direction, [string $browser_array_key = 0], [string $secondary = 0])
  • string $field: The name of the field to be ordered by.
  • string $direction: A for Ascending, otherwise it will be descending order.
  • string $browser_array_key: Use this to distinguish between multiple browser widgets on the same page. Leave it empty if you only have a single browser instance.
  • string $secondary: Use this to indicate a default secondary order which shouldn't interfere with the default primary order.
AddRow (line 644)

Add an extra arbitrary row onto the end of the browser.

  • var: Contains an array of named fields, hopefully matching the column names.
void AddRow ( $column_values)
  • $column_values
AddTotal (line 554)

Mark a column as something to be totalled. You can also specify the name of a function which may modify the value before the actual totalling.

The callback function will be called with each row, with the first argument being the entire record object and the second argument being only the column being totalled. The callback should return a number, to be added to the total.

void AddTotal (string $column_name, [string $total_function = false])
  • string $column_name: The name of the column to be totalled.
  • string $total_function: The name of the callback function.
AndWhere (line 433)

Add an OR ... to the SQL Where clause

void AndWhere (string $more_where)
  • string $more_where: The extra part of the where clause
DoQuery (line 615)

This method is used to build and execute the database query.

You need not call this method, since Browser::Render() will call it for you if you have not done so at that point.

  • return: The success / fail status of the PgQuery::Exec()
boolean DoQuery ()
ForceOrder (line 505)

Force a particular ordering onto the browser widget.

void ForceOrder (string $field, string $direction)
  • string $field: The name of the field to be ordered by.
  • string $direction: A for Ascending, otherwise it will be descending order.
GetTotal (line 567)

Retrieve the total from a totalled column

void GetTotal (string $column_name)
  • string $column_name: The name of the column to be totalled.
MatchedRow (line 657)

Replace a row where $column = $value with an extra arbitrary row, returned from calling $function

void MatchedRow (string $column, string $value, string $function)
  • string $column: The name of a column to match
  • string $value: The value to match in the column
  • string $function: The name of the function to call for the matched row
MoreWhere (line 420)

Add an [operator] ... to the SQL Where clause

You will generally want to call OrWhere or AndWhere rather than this function, but hey: who am I to tell you how to code!

void MoreWhere (string $operator, string $more_where)
  • string $operator: The operator to combine with previous where clause parts.
  • string $more_where: The extra part of the where clause
OrWhere (line 442)

Add an OR ... to the SQL Where clause

void OrWhere (string $more_where)
  • string $more_where: The extra part of the where clause
Render (line 702)

This method is used to render the browser as HTML. If the query has not yet been executed then this will call DoQuery to do so.

The browser (including the title) will be displayed in a div with id="browser" so that you can style '#browser tr.header', '#browser tr.totals' and so forth.

  • return: The rendered HTML fragment to display to the user.
string Render ([string $title_tag = null], [ $subtitle_tag = null])
  • string $title_tag: The tag to use around the browser title (default 'h1')
  • $subtitle_tag
RowFormat (line 594)

Set the format for an output row.

The row format is set as an sprintf format string for the start of the row, and a plain text string for the close of the row. Subsequent arguments are interpreted as names of fields, the values of which will be sprintf'd into the beginrow string for each row.

Some special field names exist beginning with the '#' character which have 'magic' functionality, including '#even' which will insert '0' for even rows and '1' for odd rows, allowing a nice colour alternation if the beginrow format refers to it like: 'class="r%d"' so that even rows will become 'class="r0"' and odd rows will be 'class="r1"'.

At present only '#even' exists, although other magic values may be defined in future.

void RowFormat (string $beginrow, string $closerow, string $rowargs)
  • string $beginrow: The new printf format for the start of the row.
  • string $closerow: The new string for the close of the row.
  • string $rowargs: ... The row arguments which will be sprintf'd into the $beginrow format for each row
SetDistinct (line 385)

Set the SQL DISTINCT clause to a specific value.

The whole clause (except the keyword) needs to be supplied

void SetDistinct (string $distinct)
  • string $distinct: The whole clause, after 'DISTINCT'
SetDiv (line 336)

Set a div for wrapping the browse.

void SetDiv (string $open_div, string $close_div)
  • string $open_div: The HTML to open the div
  • string $close_div: The HTML to open the div
SetJoins (line 350)

Set the tables and joins for the SQL.

For a single table this should just contain the name of that table, but for multiple tables it should be the full content of the SQL 'FROM ...' clause (excluding the actual 'FROM' keyword).

void SetJoins (string $join_list)
  • string $join_list
SetLimit (line 396)

Set the SQL LIMIT clause to a specific value.

Only the limit number should be supplied.

void SetLimit (int $limit_n)
  • int $limit_n: A number of rows to limit the SQL selection to
SetOffset (line 407)

Set the SQL OFFSET clause to a specific value.

Only the offset number

void SetOffset (int $offset_n)
  • int $offset_n: A number of rows to offset the SQL selection to, based from the start of the results.
SetOrdering (line 532)

Set up the ordering for the browser. Generally you should call this with the first parameter set as a field to order by default. Call with the second parameter set to 'D' or 'DESCEND' if you want to reverse the default order.

void SetOrdering ([ $default_fld = null], [ $default_dir = 'A'], [ $browser_array_key = 0])
  • $default_fld
  • $default_dir
  • $browser_array_key
SetSubTitle (line 326)

Set a Sub Title for the browse.

void SetSubTitle (string $sub_title)
  • string $sub_title: The sub title string
SetTitle (line 286)

Set the Title for the browse.

This can also be set in the constructor but if you create a template Browser and then clone it in a loop you may want to assign a different Title for each instance.

void SetTitle (string $new_title)
  • string $new_title: The new title for the browser
SetTranslatable (line 308)

Set the named columns to be translatable

void SetTranslatable (array $column_list)
  • array $column_list: The list of columns which are translatable
SetUnion (line 363)

Set a Union SQL statement.

In rare cases this might be useful. It's currently a fairly simple hack which requires you to put an entire valid (& matching) UNION subclause (although without the UNION keyword).

void SetUnion (string $union_select)
  • string $union_select
SetWhere (line 374)

Set the SQL Where clause to a specific value.

The WHERE keyword should not be included.

void SetWhere (string $where_clause)
  • string $where_clause: A valide SQL WHERE ... clause.
Title (line 297)

Accessor for the Title for the browse, which could set the title also.

  • return: The current title for the browser
string Title ([string $new_title = null])
  • string $new_title: The new title for the browser
ValueReplacement (line 673)

Return values from the current row for replacing into a template.

This is used to return values from the current row, so they can be inserted into a row template. It is used as a callback function for preg_replace_callback.

void ValueReplacement (array $matches)
  • array $matches: of string $matches An array containing a field name as offset 1

Documentation generated on Thu, 15 Apr 2010 20:23:02 +1200 by phpDocumentor 1.3.2